value-object-pattern 0.1.0__py3-none-any.whl

value_object_pattern/usables/internet/aws_cloud_region_value_object.py

@@ -0,0 +1,77 @@
+"""
+AwsCloudRegionValueObject value object.
+"""
+
+from functools import lru_cache
+from re import DOTALL, findall
+from urllib.request import urlopen
+
+from value_object_pattern import process, validation
+from value_object_pattern.usables import NotEmptyStringValueObject, TrimmedStringValueObject
+
+
+@lru_cache(maxsize=1)
+def get_aws_cloud_regions() -> set[str]:
+    """
+    Get AWS cloud regions.
+
+    Returns:
+        set[str]: The AWS cloud regions.
+
+    References:
+        AWS Regions: https://docs.aws.amazon.com/global-infrastructure/latest/regions/aws-regions.html#available-regions
+    """
+    url = 'https://docs.aws.amazon.com/global-infrastructure/latest/regions/aws-regions.html#available-regions'
+    with urlopen(url=url) as response:  # noqa: S310
+        content = response.read().decode('utf-8')
+
+    pattern = r'<tr>\s*<td[^>]*tabindex="-1">(.*?)</td>\s*<td[^>]*tabindex="-1">.*?</td>\s*<td[^>]*tabindex="-1">.*?</td>\s*</tr>'  # noqa: E501
+    region_codes = findall(pattern=pattern, string=content, flags=DOTALL)
+
+    return {region_code.lower() for region_code in region_codes}
+
+
+class AwsCloudRegionValueObject(NotEmptyStringValueObject, TrimmedStringValueObject):
+    """
+    AwsCloudRegionValueObject value object ensures the provided value is a valid AWS cloud region.
+
+    References:
+        AWS Regions: https://docs.aws.amazon.com/global-infrastructure/latest/regions/aws-regions.html#available-regions
+
+    Example:
+    ```python
+    from value_object_pattern.usables.internet import AwsCloudRegionValueObject
+
+    key = AwsCloudRegionValueObject(value='us-east-1')
+
+    print(repr(key))
+    # >>> AwsCloudRegionValueObject(value=us-east-1)
+    ```
+    """
+
+    @process(order=0)
+    def _ensure_region_is_in_lowercase(self, value: str) -> str:
+        """
+        Ensure AWS region is in lowercase.
+
+        Args:
+            value (str): The region value.
+
+        Returns:
+            str: The region value in lowercase.
+        """
+        return value.lower()
+
+    @validation(order=0)
+    def _validate_region(self, value: str) -> None:
+        """
+        Validate AWS region.
+
+        Args:
+            value (str): The region value.
+
+        Raises:
+            ValueError: If the region does not exist.
+        """
+        if value.lower() not in get_aws_cloud_regions():
+            raise ValueError(f'AwsCloudRegionValueObject value <<<{value}>>> does not exist.')

value_object_pattern/usables/internet/domain_value_object.py

@@ -0,0 +1,149 @@
+"""
+DomainValueObject value object.
+"""
+
+from functools import lru_cache
+from re import Pattern, compile as re_compile
+from urllib.request import urlopen
+
+from value_object_pattern import process, validation
+from value_object_pattern.usables import NotEmptyStringValueObject, TrimmedStringValueObject
+
+
+@lru_cache(maxsize=1)
+def get_top_level_domains() -> set[str]:
+    """
+    Get top level domains from IANA.
+
+    Args:
+        url (str): The URL to get the top level domains.
+
+    Returns:
+        set[str]: The top level domains in lower case.
+
+    References:
+        https://data.iana.org/TLD/tlds-alpha-by-domain.txt
+    """
+    url = 'https://data.iana.org/TLD/tlds-alpha-by-domain.txt'
+    with urlopen(url=url) as response:  # noqa: S310
+        content = response.read().decode('utf-8')
+
+    return {line.strip().lower() for line in content.splitlines() if line and not line.startswith('#')}
+
+
+class DomainValueObject(NotEmptyStringValueObject, TrimmedStringValueObject):
+    """
+    DomainValueObject value object ensures the provided value is a valid domain.
+
+    References:
+        https://data.iana.org/TLD/tlds-alpha-by-domain.txt
+
+    Example:
+    ```python
+    from value_object_pattern.usables.internet import DomainValueObject
+
+    key = DomainValueObject(value='github.com')
+
+    print(repr(key))
+    # >>> DomainValueObject(value=github.com)
+    ```
+    """
+
+    __DOMAIN_VALUE_OBJECT_MIN_LABEL_LENGTH: int = 1
+    __DOMAIN_VALUE_OBJECT_MAX_LABEL_LENGTH: int = 63
+    __DOMAIN_VALUE_OBJECT_MAX_DOMAIN_LENGTH: int = 253
+    __DOMAIN_VALUE_OBJECT_REGEX: Pattern[str] = re_compile(pattern=r'^[a-zA-Z0-9-]+$')
+
+    @process(order=0)
+    def _ensure_domain_is_in_lowercase(self, value: str) -> str:
+        """
+        Ensure domain is in lowercase.
+
+        Args:
+            value (str): The domain value.
+
+        Returns:
+            str: The domain value in lowercase.
+        """
+        return value.lower()
+
+    @process(order=1)
+    def _ensure_domain_has_not_trailing_dot(self, value: str) -> str:
+        """
+        Ensure domain has not trailing dot.
+
+        Args:
+            value (str): The domain value.
+
+        Returns:
+            str: The domain value without trailing dot.
+        """
+        return value.rstrip('.')
+
+    @validation(order=0)
+    def _validate_top_level_domain(self, value: str) -> None:
+        """
+        Validate top level domain.
+
+        Args:
+            value (str): The domain value.
+
+        Raises:
+            ValueError: If domain value has not a valid top level domain.
+        """
+        if '.' not in value:
+            raise ValueError(f'DomainValueObject value <<<{value}>>> has not a valid top level domain.')
+
+        tdl = value.lower().rstrip('.').split(sep='.')[-1]
+        if tdl not in get_top_level_domains():
+            raise ValueError(f'DomainValueObject value <<<{value}>>> has not a valid top level domain <<<{tdl}>>>.')
+
+    @validation(order=1)
+    def _validate_domain_length(self, value: str) -> None:
+        """
+        Validate domain length.
+
+        Args:
+            value (str): The domain value.
+
+        Raises:
+            ValueError: If value length is longer than the maximum domain length.
+        """
+        if len(value) > self.__DOMAIN_VALUE_OBJECT_MAX_DOMAIN_LENGTH:
+            raise ValueError(f'DomainValueObject value <<<{value}>>> length is longer than <<<{self.__DOMAIN_VALUE_OBJECT_MAX_DOMAIN_LENGTH}>>> characters.')  # noqa: E501  # fmt: skip
+
+    @validation(order=2)
+    def _validate_domain_labels(self, value: str) -> None:
+        """
+        Validate each label (label) according to standard DNS rules.
+         - Label must be between 1 and 63 characters long.
+         - Label must only contain letters, digits, or hyphens.
+         - Label must not start or end with a hyphen.
+
+        Args:
+            value (str): The domain value.
+
+        Raises:
+            ValueError: If value has a label shorter than the minimum length.
+            ValueError: If value has a label longer than the maximum length.
+            ValueError: If value has a label starting with a hyphen.
+            ValueError: If value has a label ending with a hyphen.
+            ValueError: If value has a label containing invalid characters.
+        """
+        labels = value.lower().rstrip('.').split(sep='.')
+        labels = labels[:-1] if len(labels) > 1 else labels  # remove top level domain
+        for label in labels:
+            if len(label) < self.__DOMAIN_VALUE_OBJECT_MIN_LABEL_LENGTH:
+                raise ValueError(f'DomainValueObject value <<<{value}>>> has a label <<<{label}>>> shorter than <<<{self.__DOMAIN_VALUE_OBJECT_MIN_LABEL_LENGTH}>>> characters.')  # noqa: E501  # fmt: skip
+
+            if len(label) > self.__DOMAIN_VALUE_OBJECT_MAX_LABEL_LENGTH:
+                raise ValueError(f'DomainValueObject value <<<{value}>>> has a label <<<{label}>>> longer than <<<{self.__DOMAIN_VALUE_OBJECT_MAX_LABEL_LENGTH}>>> characters.')  # noqa: E501  # fmt: skip
+
+            if label[0] == '-':
+                raise ValueError(f'DomainValueObject value <<<{value}>>> has a label <<<{label}>>> that starts with a hyphen.')  # noqa: E501  # fmt: skip
+
+            if label[-1] == '-':
+                raise ValueError(f'DomainValueObject value <<<{value}>>> has a label <<<{label}>>> that ends with a hyphen.')  # noqa: E501  # fmt: skip
+
+            if not self.__DOMAIN_VALUE_OBJECT_REGEX.fullmatch(string=label.encode(encoding='idna').decode(encoding='utf-8')):  # noqa: E501  # fmt: skip
+                raise ValueError(f'DomainValueObject value <<<{value}>>> has a label <<<{label}>>> containing invalid characters. Only letters, digits, and hyphens are allowed.')  # noqa: E501  # fmt: skip

value_object_pattern/usables/internet/host_value_object.py

@@ -0,0 +1,143 @@
+"""
+HostValueObject value object.
+"""
+
+from value_object_pattern import process, validation
+from value_object_pattern.usables import NotEmptyStringValueObject, TrimmedStringValueObject
+
+from .domain_value_object import DomainValueObject
+from .ipv4_address_value_object import Ipv4AddressValueObject
+from .ipv6_address_value_object import Ipv6AddressValueObject
+
+
+class HostValueObject(NotEmptyStringValueObject, TrimmedStringValueObject):
+    """
+    HostValueObject value object ensures the provided value is a valid host.
+
+    Example:
+    ```python
+    from value_object_pattern.usables.internet import HostValueObject
+
+    key = HostValueObject(value='github.com')
+
+    print(repr(key))
+    # >>> HostValueObject(value=github.com)
+    ```
+    """
+
+    @process(order=0)
+    def _ensure_host_stored_respective_format(self, value: str) -> str:
+        """
+        Ensure host is stored in respective format, domain, IPv4 or IPv6 address.
+
+        Args:
+            value (str): The host value.
+
+        Returns:
+            str: The host value stored in respective format.
+        """
+        if self.is_domain(value=value):
+            return DomainValueObject(value=value).value
+
+        if self.is_ipv4_address(value=value):
+            return Ipv4AddressValueObject(value=value).value
+
+        return Ipv6AddressValueObject(value=value).value
+
+    @validation(order=0)
+    def _validate_host(self, value: str) -> None:
+        """
+        Validate that the host is a domain or an IPv4 or IPv6 address.
+
+        Args:
+            value (str): The host value.
+
+        Raises:
+            ValueError: If the host is not a domain or an IPv4 or IPv6 address.
+        """
+        if not (self.is_domain(value=value) or self.is_ipv4_address(value=value) or self.is_ipv6_address(value=value)):
+            raise ValueError(f'HostValueObject value <<<{value}>>> must be a domain or an IPv4 or IPv6 address.')
+
+    @classmethod
+    def is_domain(cls, *, value: str) -> bool:
+        """
+        Checks if a value is a domain.
+
+        Args:
+            value (str): Value.
+
+        Returns:
+            bool: True if the value is a host, False otherwise.
+
+        Example:
+        ```python
+        from value_object_pattern.usables.internet import HostValueObject
+
+        is_domain = HostValueObject.is_domain(value='github.com')
+
+        print(is_domain)
+        # >>> True
+        ```
+        """
+        try:
+            DomainValueObject(value=value)
+            return True
+
+        except (TypeError, ValueError):
+            return False
+
+    @classmethod
+    def is_ipv4_address(cls, *, value: str) -> bool:
+        """
+        Checks if a value is an IPv4 host.
+
+        Args:
+            value (str): Value.
+
+        Returns:
+            bool: True if the value is an IPv4 host, False otherwise.
+
+        Example:
+        ```python
+        from value_object_pattern.usables.internet import HostValueObject
+
+        is_ipv4 = HostValueObject.is_ipv4_address(value='1.1.1.1')
+
+        print(is_ipv4)
+        # >>> True
+        ```
+        """
+        try:
+            Ipv4AddressValueObject(value=value)
+            return True
+
+        except (TypeError, ValueError):
+            return False
+
+    @classmethod
+    def is_ipv6_address(cls, *, value: str) -> bool:
+        """
+        Checks if a value is an IPv6 host.
+
+        Args:
+            value (str): Value.
+
+        Returns:
+            bool: True if the value is an IPv6 host, False otherwise.
+
+        Example:
+        ```python
+        from value_object_pattern.usables.internet import HostValueObject
+
+        is_ipv6 = HostValueObject.is_ipv6_address(value='a1c4:c052:a98e:8da4:301a:bd2a:3b36:36b4')
+
+        print(is_ipv6)
+        # >>> True
+        ```
+        """
+        try:
+            Ipv6AddressValueObject(value=value)
+            return True
+
+        except (TypeError, ValueError):
+            return False

value_object_pattern/usables/internet/ipv4_address_value_object.py

@@ -0,0 +1,305 @@
+# ruff: noqa: N802
+"""
+Ipv4AddressValueObject value object.
+"""
+
+from __future__ import annotations
+
+from ipaddress import AddressValueError, IPv4Address
+
+from value_object_pattern.decorators import process, validation
+from value_object_pattern.usables import NotEmptyStringValueObject, TrimmedStringValueObject
+
+
+class Ipv4AddressValueObject(NotEmptyStringValueObject, TrimmedStringValueObject):
+    """
+    Ipv4AddressValueObject value object ensures the provided value is a valid IPv4 address.
+
+    Example:
+    ```python
+    from value_object_pattern.usables.internet import Ipv4AddressValueObject
+
+    ip = Ipv4AddressValueObject(value='66.162.207.81')
+
+    print(repr(ip))
+    # >>> Ipv4AddressValueObject(value=66.162.207.81)
+    ```
+    """
+
+    @process(order=0)
+    def _ensure_value_is_normalized(self, value: str) -> str:
+        """
+        Ensures the value object value is normalized IPv4 address.
+
+        Args:
+            value (str): Value.
+
+        Returns:
+            str: Value with the normalized IPv4 address.
+        """
+        value = self._ipv4_address_normalize(value=value)
+        return str(object=IPv4Address(address=value))
+
+    @validation(order=0)
+    def _ensure_value_is_valid_ipv4_address(self, value: str) -> None:
+        """
+        Ensures the value object value is a valid IPv4 address.
+
+        Args:
+            value (str): Value.
+
+        Raises:
+            ValueError: If the value is not a valid IPv4 address.
+        """
+        value = self._ipv4_address_normalize(value=value)
+        self._ipv4_address_validate(value=value)
+
+    @classmethod
+    def _ipv4_address_normalize(cls, value: str) -> str:
+        """
+        Normalizes the given IPv4 address.
+
+        Args:
+            value (str): IPv4 address.
+
+        Returns:
+            str: Normalized IPv4 address.
+        """
+        if '/' in value and value.endswith('/32'):
+            value = value[:-3]
+
+        return value
+
+    @classmethod
+    def _ipv4_address_validate(cls, value: str) -> IPv4Address:
+        """
+        Validates the given IPv4 address.
+
+        Args:
+            value (str): IPv4 address.
+
+        Raises:
+            ValueError: If the value is not a valid IPv4 address.
+
+        Returns:
+            IPv4Address: IPv4 address.
+        """
+        try:
+            return IPv4Address(address=value)
+
+        except AddressValueError as error:
+            raise ValueError(f'Ipv4AddressValueObject value <<<{value}>>> is not a valid IPv4 address.') from error
+
+    def is_reserved(self) -> bool:
+        """
+        Checks if the given IPv4 address is reserved.
+
+        Args:
+            value (str): IPv4 address.
+
+        Returns:
+            bool: True if the given IPv4 address is reserved, False otherwise.
+
+        Example:
+        ```python
+        from value_object_pattern.usables.internet import Ipv4AddressValueObject
+
+        is_reserved = Ipv4AddressValueObject(value='240.0.0.0').is_reserved()
+
+        print(is_reserved)
+        # >>> True
+        ```
+        """
+        return self._ipv4_address_validate(value=self.value).is_reserved
+
+    def is_private(self) -> bool:
+        """
+        Checks if the given IPv4 address is private.
+
+        Args:
+            value (str): IPv4 address.
+
+        Returns:
+            bool: True if the given IPv4 address is private, False otherwise.
+
+        Example:
+        ```python
+        from value_object_pattern.usables.internet import Ipv4AddressValueObject
+
+        is_private = Ipv4AddressValueObject(value='192.168.10.4').is_private()
+
+        print(is_private)
+        # >>> True
+        ```
+        """
+        return self._ipv4_address_validate(value=self.value).is_private
+
+    def is_global(self) -> bool:
+        """
+        Checks if the given IPv4 address is global.
+
+        Args:
+            value (str): IPv4 address.
+
+        Returns:
+            bool: True if the given IPv4 address is global, False otherwise.
+
+        Example:
+        ```python
+        from value_object_pattern.usables.internet import Ipv4AddressValueObject
+
+        is_global = Ipv4AddressValueObject(value='66.162.207.81').is_global()
+
+        print(is_global)
+        # >>> True
+        ```
+        """
+        return self._ipv4_address_validate(value=self.value).is_global
+
+    def is_multicast(self) -> bool:
+        """
+        Checks if the given IPv4 address is multicast.
+
+        Args:
+            value (str): IPv4 address.
+
+        Returns:
+            bool: True if the given IPv4 address is multicast, False otherwise.
+
+        Example:
+        ```python
+        from value_object_pattern.usables.internet import Ipv4AddressValueObject
+
+        is_multicast = Ipv4AddressValueObject(value='224.0.0.1').is_multicast()
+
+        print(is_multicast)
+        # >>> True
+        ```
+        """
+        return self._ipv4_address_validate(value=self.value).is_multicast
+
+    def is_unspecified(self) -> bool:
+        """
+        Checks if the given IPv4 address is unspecified.
+
+        Args:
+            value (str): IPv4 address.
+
+        Returns:
+            bool: True if the given IPv4 address is unspecified, False otherwise.
+
+        Example:
+        ```python
+        from value_object_pattern.usables.internet import Ipv4AddressValueObject
+
+        is_unspecified = Ipv4AddressValueObject(value='0.0.0.0').is_unspecified()
+
+        print(is_unspecified)
+        # >>> True
+        ```
+        """
+        return self._ipv4_address_validate(value=self.value).is_unspecified
+
+    def is_loopback(self) -> bool:
+        """
+        Checks if the given IPv4 address is loopback.
+
+        Args:
+            value (str): IPv4 address.
+
+        Returns:
+            bool: True if the given IPv4 address is loopback, False otherwise.
+
+        Example:
+        ```python
+        from value_object_pattern.usables.internet import Ipv4AddressValueObject
+
+        is_loopback = Ipv4AddressValueObject(value='127.0.0.1').is_loopback()
+
+        print(is_loopback)
+        # >>> True
+        ```
+        """
+        return self._ipv4_address_validate(value=self.value).is_loopback
+
+    def is_link_local(self) -> bool:
+        """
+        Checks if the given IPv4 address is link-local.
+
+        Args:
+            value (str): IPv4 address.
+
+        Returns:
+            bool: True if the given IPv4 address is link-local, False otherwise.
+
+        Example:
+        ```python
+        from value_object_pattern.usables.internet import Ipv4AddressValueObject
+
+        is_link_local = Ipv4AddressValueObject(value='169.254.0.0').is_link_local()
+
+        print(is_link_local)
+        # >>> True
+        ```
+        """
+        return self._ipv4_address_validate(value=self.value).is_link_local
+
+    @classmethod
+    def UNSPECIFIED(cls) -> Ipv4AddressValueObject:
+        """
+        Returns the unspecified IPv4 address (0.0.0.0).
+
+        Returns:
+            Ipv4AddressValueObject: Unspecified IPv4 address.
+
+        Example:
+        ```python
+        from value_object_pattern.usables.internet import Ipv4AddressValueObject
+
+        ip = Ipv4AddressValueObject.UNSPECIFIED()
+
+        print(repr(ip))
+        # >>> Ipv4AddressValueObject(value=0.0.0.0)
+        ```
+        """
+        return cls(value='0.0.0.0')  # noqa: S104
+
+    @classmethod
+    def LOOPBACK(cls) -> Ipv4AddressValueObject:
+        """
+        Returns the loopback IPv4 address (127.0.0.1).
+
+        Returns:
+            Ipv4AddressValueObject: Loopback IPv4 address.
+
+        Example:
+        ```python
+        from value_object_pattern.usables.internet import Ipv4AddressValueObject
+
+        ip = Ipv4AddressValueObject.LOOPBACK()
+
+        print(repr(ip))
+        # >>> Ipv4AddressValueObject(value=127.0.0.1)
+        ```
+        """
+        return cls(value='127.0.0.1')
+
+    @classmethod
+    def BROADCAST(cls) -> Ipv4AddressValueObject:
+        """
+        Returns the broadcast IPv4 address (255.255.255.255).
+
+        Returns:
+            Ipv4AddressValueObject: Broadcast IPv4 address.
+
+        Example:
+        ```python
+        from value_object_pattern.usables.internet import Ipv4AddressValueObject
+
+        ip = Ipv4AddressValueObject.BROADCAST()
+
+        print(repr(ip))
+        # >>> Ipv4AddressValueObject(value=255.255.255.255)
+        ```
+        """
+        return cls(value='255.255.255.255')