The tool to check the availability or syntax of domain, IP or URL.
::
██████╗ ██╗ ██╗███████╗██╗ ██╗███╗ ██╗ ██████╗███████╗██████╗ ██╗ ███████╗
██╔══██╗╚██╗ ██╔╝██╔════╝██║ ██║████╗ ██║██╔════╝██╔════╝██╔══██╗██║ ██╔════╝
██████╔╝ ╚████╔╝ █████╗ ██║ ██║██╔██╗ ██║██║ █████╗ ██████╔╝██║ █████╗
██╔═══╝ ╚██╔╝ ██╔══╝ ██║ ██║██║╚██╗██║██║ ██╔══╝ ██╔══██╗██║ ██╔══╝
██║ ██║ ██║ ╚██████╔╝██║ ╚████║╚██████╗███████╗██████╔╝███████╗███████╗
╚═╝ ╚═╝ ╚═╝ ╚═════╝ ╚═╝ ╚═══╝ ╚═════╝╚══════╝╚═════╝ ╚══════╝╚══════╝
Provides the base of all checker.
Author:
Nissar Chababy, @funilrys, contactTATAfunilrysTODTODcom
Special thanks:
https://pyfunceble.github.io/#/special-thanks
Contributors:
https://pyfunceble.github.io/#/contributors
Project link:
https://github.com/funilrys/PyFunceble
Project documentation:
https://docs.pyfunceble.com
Project homepage:
https://pyfunceble.github.io/
License:
::
Copyright 2017, 2018, 2019, 2020, 2022, 2023, 2024 Nissar Chababy
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
https://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
CheckerBase
Provides the base of all checker.
Parameters:
Name |
Type |
Description |
Default |
subject
|
str
|
Optional, The subject to work with.
|
None
|
do_syntax_check_first
|
bool
|
Optional, Forces the checker to first perform a syntax check, .. warning:: This does not apply to the syntax checker - itself.
|
None
|
Source code in PyFunceble/checker/base.py
| class CheckerBase:
"""
Provides the base of all checker.
:param str subject:
Optional, The subject to work with.
:param bool do_syntax_check_first:
Optional, Forces the checker to first perform a syntax check,
.. warning::
This does not apply to the syntax checker - itself.
"""
STD_DO_SYNTAX_CHECK_FIRST: bool = False
STD_USE_PLATFORM: bool = False
_do_syntax_check_first: bool = False
_use_platform: bool = False
_subject: Optional[str] = None
_idna_subject: Optional[str] = None
url2netloc: Optional[Url2Netloc] = None
db_session: Optional[Session] = None
platform_query_tool: Optional[PlatformQueryTool] = None
status: Optional[CheckerStatusBase] = None
params: Optional[CheckerParamsBase] = None
def __init__(
self,
subject: Optional[str] = None,
*,
do_syntax_check_first: Optional[bool] = None,
db_session: Optional[Session] = None,
use_platform: Optional[bool] = None,
) -> None:
self.platform_query_tool = PlatformQueryTool()
self.url2netloc = Url2Netloc()
if self.params is None:
self.params = CheckerParamsBase()
if self.status is None:
self.status = CheckerStatusBase()
if subject is not None:
self.subject = subject
if do_syntax_check_first is not None:
self.do_syntax_check_first = do_syntax_check_first
else:
self.do_syntax_check_first = self.STD_DO_SYNTAX_CHECK_FIRST
if use_platform is not None:
self.use_platform = use_platform
else:
self.guess_and_set_use_platform()
self.db_session = db_session
def propagate_subject(func): # pylint: disable=no-self-argument
"""
Propagates the subject to the object that need it after launching
the decorated method.
"""
@functools.wraps(func)
def wrapper(self, *args, **kwargs):
result = func(self, *args, **kwargs) # pylint: disable=not-callable
self.subject_propagator()
return result
return wrapper
def ensure_subject_is_given(func): # pylint: disable=no-self-argument
"""
Ensures that the subject is given before running the decorated method.
:raise TypeError:
If the subject is not a string.
"""
@functools.wraps(func)
def wrapper(self, *args, **kwargs): # pragma: no cover ## Safety!
if not isinstance(self.subject, str):
raise TypeError(
f"<self.subject> should be {str}, {type(self.subject)} given."
)
return func(self, *args, **kwargs) # pylint: disable=not-callable
return wrapper
def query_status_if_missing(func): # pylint: disable=no-self-argument
"""
Queries the status if it's missing.
"""
@functools.wraps(func)
def wrapper(self, *args, **kwargs): # pragma: no cover ## Safety!
if not self.status.status or self.status.status is None:
self.query_status()
return func(self, *args, **kwargs) # pylint: disable=not-callable
return wrapper
def update_status_date_after_query(func): # pylint: disable=no-self-argument
"""
Updates the status dates after running the decorated method.
"""
@functools.wraps(func)
def wrapper(self, *args, **kwargs): # pragma: no cover ## Safety!
result = func(self, *args, **kwargs) # pylint: disable=not-callable
self.status.tested_at = datetime.datetime.now(datetime.timezone.utc)
return result
return wrapper
@property
def subject(self) -> Optional[str]:
"""
Provides the current state of the :code:`_subject` attribute.
"""
return self._subject
@subject.setter
@propagate_subject
def subject(self, value: str) -> None:
"""
Sets the subject to work with.
:param value:
The subject to set.
:raise TypeError:
When the given :code:`value` is not a :py:class:`str`.
:raise ValueError:
When the given :code:`value` is empty.
"""
if not isinstance(value, str):
raise TypeError(f"<value> should be {str}, {type(value)} given.")
if not value:
raise ValueError("<value> should not be empty.")
self._subject = value
try:
self.idna_subject = domain2idna.domain2idna(value)
except ValueError:
self.idna_subject = value
def set_subject(self, value: str) -> "CheckerBase":
"""
Sets the subject to work with.
:param value:
The subject to set.
"""
self.subject = value
return self
@property
def idna_subject(self) -> Optional[str]:
"""
Provides the current state of the :code:`_idna_subject` attribute.
"""
return self._idna_subject
@idna_subject.setter
def idna_subject(self, value: str) -> None:
"""
Sets the subject to work with.
:param value:
The subject to set.
:raise TypeError:
When the given :code:`value` is not a :py:class:`str`.
:raise ValueError:
When the given :code:`value` is empty.
"""
if not isinstance(value, str):
raise TypeError(f"<value> should be {str}, {type(value)} given.")
if not value:
raise ValueError("<value> should not be empty.")
self._idna_subject = value
def set_idna_subject(self, value: str) -> "CheckerBase":
"""
Sets the subject to work with.
:param value:
The subject to set.
"""
self.idna_subject = value
return self
@property
def do_syntax_check_first(self) -> None:
"""
Provides the current state of the :code:`do_syntax_check_first`
attribute.
"""
return self._do_syntax_check_first
@do_syntax_check_first.setter
def do_syntax_check_first(self, value: bool) -> None:
"""
Sets the value which allow us to do a syntax check first.
:param value:
The subject to set.
:raise TypeError:
When the given :code:`value` is not a :py:class:`bool`.
"""
if not isinstance(value, bool):
raise TypeError(f"<value> should be {str}, {type(value)} given.")
self._do_syntax_check_first = self.params.do_syntax_check_first = value
def set_do_syntax_check_first(self, value: bool) -> "CheckerBase":
"""
Sets the value which allow us to do a syntax check first.
:param value:
The subject to set.
"""
self.do_syntax_check_first = value
return self
@property
def use_platform(self) -> bool:
"""
Provides the current value of the :code:`_use_platform` attribute.
"""
return self._use_platform
@use_platform.setter
def use_platform(self, value: bool) -> None:
"""
Sets the value which authorizes the usage of the platform.
:param value:
The value to set.
:param TypeError:
When the given :code:`value` is not a :py:class:`bool`.
"""
if not isinstance(value, bool):
raise TypeError(f"<value> should be {bool}, {type(value)} given.")
self._use_platform = self.params.use_platform = value
def set_use_platform(self, value: bool) -> "CheckerBase":
"""
Sets the value which authorizes the usage of the platform.
:param value:
The value to set.
"""
self.use_platform = value
return self
def guess_and_set_use_platform(self) -> "CheckerBase":
"""
Try to guess and set the value of the :code:`use_platform` attribute.
"""
if PyFunceble.facility.ConfigLoader.is_already_loaded():
if isinstance(PyFunceble.storage.CONFIGURATION.lookup.platform, bool):
self.use_platform = PyFunceble.storage.CONFIGURATION.lookup.platform
else:
self.use_platform = self.STD_USE_PLATFORM
else:
self.use_platform = self.STD_USE_PLATFORM
def subject_propagator(self) -> "CheckerBase":
"""
Propagate the currently set subject.
.. warning::
Be sure to use setup your status first.
"""
self.status.subject = self.subject
self.status.idna_subject = self.idna_subject
self.status.netloc = self.url2netloc.set_data_to_convert(
self.idna_subject
).get_converted()
self.status.status = None
return self.query_common_checker()
def query_common_checker(self) -> "CheckerBase":
"""
Queries the common checkers.
.. warning::
Be sure to use setup your status first.
"""
if not self.status.subject_kind:
cls_name = self.__class__.__name__.lower()
if (
hasattr(self.status, "ip_syntax") and self.status.ip_syntax
) or "ip" in cls_name:
self.status.subject_kind = "ip"
elif (
hasattr(self.status, "url_syntax") and self.status.url_syntax
) or "url" in cls_name:
self.status.subject_kind = "url"
elif (
hasattr(self.status, "domain_syntax") and self.status.domain_syntax
) or "domain" in cls_name:
self.status.subject_kind = "domain"
else:
self.status.subject_kind = "unknown"
return self
@ensure_subject_is_given
def is_valid(self) -> bool:
"""
Provides the result of the validation.
"""
raise NotImplementedError()
@ensure_subject_is_given
@update_status_date_after_query
def query_status(self) -> "CheckerBase":
"""
Queries the status.
"""
raise NotImplementedError()
@query_status_if_missing
def get_status(self) -> Optional[CheckerStatusBase]:
"""
Provides the current state of the status.
.. note::
This method will automatically query status using the
:meth:`PyFunceble.checker.base.CheckerBase.query_status` if
the
:attr:`PyFunceble.checker.status_base.CheckerStatusBase.status`
attribute is not set.
"""
return self.status
|
do_syntax_check_first
property
writable
Provides the current state of the :code:do_syntax_check_first
attribute.
idna_subject
property
writable
Provides the current state of the :code:_idna_subject
attribute.
subject
property
writable
Provides the current state of the :code:_subject
attribute.
Provides the current value of the :code:_use_platform
attribute.
ensure_subject_is_given(func)
Ensures that the subject is given before running the decorated method.
Raises:
Type |
Description |
TypeError
|
If the subject is not a string.
|
Source code in PyFunceble/checker/base.py
| def ensure_subject_is_given(func): # pylint: disable=no-self-argument
"""
Ensures that the subject is given before running the decorated method.
:raise TypeError:
If the subject is not a string.
"""
@functools.wraps(func)
def wrapper(self, *args, **kwargs): # pragma: no cover ## Safety!
if not isinstance(self.subject, str):
raise TypeError(
f"<self.subject> should be {str}, {type(self.subject)} given."
)
return func(self, *args, **kwargs) # pylint: disable=not-callable
return wrapper
|
get_status()
Provides the current state of the status.
.. note::
This method will automatically query status using the
:meth:PyFunceble.checker.base.CheckerBase.query_status
if
the
:attr:PyFunceble.checker.status_base.CheckerStatusBase.status
attribute is not set.
Source code in PyFunceble/checker/base.py
| @query_status_if_missing
def get_status(self) -> Optional[CheckerStatusBase]:
"""
Provides the current state of the status.
.. note::
This method will automatically query status using the
:meth:`PyFunceble.checker.base.CheckerBase.query_status` if
the
:attr:`PyFunceble.checker.status_base.CheckerStatusBase.status`
attribute is not set.
"""
return self.status
|
Try to guess and set the value of the :code:use_platform
attribute.
Source code in PyFunceble/checker/base.py
| def guess_and_set_use_platform(self) -> "CheckerBase":
"""
Try to guess and set the value of the :code:`use_platform` attribute.
"""
if PyFunceble.facility.ConfigLoader.is_already_loaded():
if isinstance(PyFunceble.storage.CONFIGURATION.lookup.platform, bool):
self.use_platform = PyFunceble.storage.CONFIGURATION.lookup.platform
else:
self.use_platform = self.STD_USE_PLATFORM
else:
self.use_platform = self.STD_USE_PLATFORM
|
is_valid()
Provides the result of the validation.
Source code in PyFunceble/checker/base.py
| @ensure_subject_is_given
def is_valid(self) -> bool:
"""
Provides the result of the validation.
"""
raise NotImplementedError()
|
propagate_subject(func)
Propagates the subject to the object that need it after launching
the decorated method.
Source code in PyFunceble/checker/base.py
| def propagate_subject(func): # pylint: disable=no-self-argument
"""
Propagates the subject to the object that need it after launching
the decorated method.
"""
@functools.wraps(func)
def wrapper(self, *args, **kwargs):
result = func(self, *args, **kwargs) # pylint: disable=not-callable
self.subject_propagator()
return result
return wrapper
|
query_common_checker()
Queries the common checkers.
.. warning::
Be sure to use setup your status first.
Source code in PyFunceble/checker/base.py
| def query_common_checker(self) -> "CheckerBase":
"""
Queries the common checkers.
.. warning::
Be sure to use setup your status first.
"""
if not self.status.subject_kind:
cls_name = self.__class__.__name__.lower()
if (
hasattr(self.status, "ip_syntax") and self.status.ip_syntax
) or "ip" in cls_name:
self.status.subject_kind = "ip"
elif (
hasattr(self.status, "url_syntax") and self.status.url_syntax
) or "url" in cls_name:
self.status.subject_kind = "url"
elif (
hasattr(self.status, "domain_syntax") and self.status.domain_syntax
) or "domain" in cls_name:
self.status.subject_kind = "domain"
else:
self.status.subject_kind = "unknown"
return self
|
query_status()
Queries the status.
Source code in PyFunceble/checker/base.py
| @ensure_subject_is_given
@update_status_date_after_query
def query_status(self) -> "CheckerBase":
"""
Queries the status.
"""
raise NotImplementedError()
|
query_status_if_missing(func)
Queries the status if it's missing.
Source code in PyFunceble/checker/base.py
| def query_status_if_missing(func): # pylint: disable=no-self-argument
"""
Queries the status if it's missing.
"""
@functools.wraps(func)
def wrapper(self, *args, **kwargs): # pragma: no cover ## Safety!
if not self.status.status or self.status.status is None:
self.query_status()
return func(self, *args, **kwargs) # pylint: disable=not-callable
return wrapper
|
set_do_syntax_check_first(value)
Sets the value which allow us to do a syntax check first.
Parameters:
Name |
Type |
Description |
Default |
value
|
bool
|
|
required
|
Source code in PyFunceble/checker/base.py
| def set_do_syntax_check_first(self, value: bool) -> "CheckerBase":
"""
Sets the value which allow us to do a syntax check first.
:param value:
The subject to set.
"""
self.do_syntax_check_first = value
return self
|
set_idna_subject(value)
Sets the subject to work with.
Parameters:
Name |
Type |
Description |
Default |
value
|
str
|
|
required
|
Source code in PyFunceble/checker/base.py
| def set_idna_subject(self, value: str) -> "CheckerBase":
"""
Sets the subject to work with.
:param value:
The subject to set.
"""
self.idna_subject = value
return self
|
set_subject(value)
Sets the subject to work with.
Parameters:
Name |
Type |
Description |
Default |
value
|
str
|
|
required
|
Source code in PyFunceble/checker/base.py
| def set_subject(self, value: str) -> "CheckerBase":
"""
Sets the subject to work with.
:param value:
The subject to set.
"""
self.subject = value
return self
|
Sets the value which authorizes the usage of the platform.
Parameters:
Name |
Type |
Description |
Default |
value
|
bool
|
|
required
|
Source code in PyFunceble/checker/base.py
| def set_use_platform(self, value: bool) -> "CheckerBase":
"""
Sets the value which authorizes the usage of the platform.
:param value:
The value to set.
"""
self.use_platform = value
return self
|
subject_propagator()
Propagate the currently set subject.
.. warning::
Be sure to use setup your status first.
Source code in PyFunceble/checker/base.py
| def subject_propagator(self) -> "CheckerBase":
"""
Propagate the currently set subject.
.. warning::
Be sure to use setup your status first.
"""
self.status.subject = self.subject
self.status.idna_subject = self.idna_subject
self.status.netloc = self.url2netloc.set_data_to_convert(
self.idna_subject
).get_converted()
self.status.status = None
return self.query_common_checker()
|
update_status_date_after_query(func)
Updates the status dates after running the decorated method.
Source code in PyFunceble/checker/base.py
| def update_status_date_after_query(func): # pylint: disable=no-self-argument
"""
Updates the status dates after running the decorated method.
"""
@functools.wraps(func)
def wrapper(self, *args, **kwargs): # pragma: no cover ## Safety!
result = func(self, *args, **kwargs) # pylint: disable=not-callable
self.status.tested_at = datetime.datetime.now(datetime.timezone.utc)
return result
return wrapper
|