pmd-net-addr 0.0.1__py3-none-any.whl

pmd_net_addr/__init__.py

@@ -0,0 +1,235 @@
+################################################################################
+##                                                                            ##
+##   PyTCP - Python TCP/IP stack                                              ##
+##   Copyright (C) 2020-present Sebastian Majewski                            ##
+##                                                                            ##
+##   This program is free software: you can redistribute it and/or modify     ##
+##   it under the terms of the GNU General Public License as published by     ##
+##   the Free Software Foundation, either version 3 of the License, or        ##
+##   (at your option) any later version.                                      ##
+##                                                                            ##
+##   This program is distributed in the hope that it will be useful,          ##
+##   but WITHOUT ANY WARRANTY; without even the implied warranty of           ##
+##   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the             ##
+##   GNU General Public License for more details.                             ##
+##                                                                            ##
+##   You should have received a copy of the GNU General Public License        ##
+##   along with this program. If not, see <https://www.gnu.org/licenses/>.    ##
+##                                                                            ##
+##   Author's email: ccie18643@gmail.com                                      ##
+##   Github repository: https://github.com/ccie18643/PyTCP                    ##
+##                                                                            ##
+################################################################################
+
+
+"""
+This package contains classes used to represent network addresses.
+
+pmd_net_addr/__init__.py
+
+ver 3.0.7
+"""
+
+from typing import TYPE_CHECKING
+
+from pmd_net_addr.errors import (
+    IfAddrError,
+    IfAddrFormatError,
+    IfAddrSanityError,
+    Ip4AddressError,
+    Ip4AddressFormatError,
+    Ip4AddressSanityError,
+    Ip4IfAddrError,
+    Ip4IfAddrFormatError,
+    Ip4IfAddrSanityError,
+    Ip4MaskError,
+    Ip4MaskFormatError,
+    Ip4NetworkError,
+    Ip4NetworkFormatError,
+    Ip4NetworkSanityError,
+    Ip4WildcardError,
+    Ip4WildcardFormatError,
+    Ip6AddressError,
+    Ip6AddressFormatError,
+    Ip6AddressSanityError,
+    Ip6IfAddrError,
+    Ip6IfAddrFormatError,
+    Ip6IfAddrSanityError,
+    Ip6MaskError,
+    Ip6MaskFormatError,
+    Ip6NetworkError,
+    Ip6NetworkFormatError,
+    Ip6NetworkSanityError,
+    Ip6WildcardError,
+    Ip6WildcardFormatError,
+    IpAddressError,
+    IpAddressFormatError,
+    IpAddressSanityError,
+    IpMaskError,
+    IpMaskFormatError,
+    IpNetworkError,
+    IpNetworkFormatError,
+    IpNetworkSanityError,
+    IpWildcardError,
+    IpWildcardFormatError,
+    MacAddressError,
+    MacAddressFormatError,
+    MacAddressSanityError,
+    NetAddrError,
+)
+from pmd_net_addr.ip4_address import IP4__ADDRESS_LEN, Ip4Address
+from pmd_net_addr.ip4_ifaddr import Ip4IfAddr
+from pmd_net_addr.ip4_mask import Ip4Mask
+from pmd_net_addr.ip4_network import Ip4Network
+from pmd_net_addr.ip4_wildcard import Ip4Wildcard
+from pmd_net_addr.ip6_address import IP6__ADDRESS_LEN, Ip6Address
+from pmd_net_addr.ip6_ifaddr import Ip6IfAddr
+from pmd_net_addr.ip6_mask import Ip6Mask
+from pmd_net_addr.ip6_network import Ip6Network
+from pmd_net_addr.ip6_wildcard import Ip6Wildcard
+from pmd_net_addr.ip_address import IpAddress
+from pmd_net_addr.ip_ifaddr import IfAddr
+from pmd_net_addr.ip_mask import IpMask
+from pmd_net_addr.ip_network import IpNetwork
+from pmd_net_addr.ip_version import IpVersion
+from pmd_net_addr.ip_wildcard import IpWildcard
+from pmd_net_addr.mac_address import MAC__ADDRESS_LEN, MacAddress
+
+# The 'click'-typed CLI helpers are an opt-in extra: importing
+# 'pmd_net_addr' (or any value type) must not drag in 'click'. The
+# names below are re-exported lazily via the module '__getattr__'
+# so 'from pmd_net_addr import ClickTypeIp4Address' still works but
+# imports 'click' only on first access. The TYPE_CHECKING block
+# gives static checkers (mypy strict, with no_implicit_reexport)
+# the real bindings, and listing the names in '__all__' marks
+# them as the explicit public surface.
+if TYPE_CHECKING:
+    from pmd_net_addr.click_types import (
+        ClickTypeIfAddr,
+        ClickTypeIp4Address,
+        ClickTypeIp4IfAddr,
+        ClickTypeIp4Network,
+        ClickTypeIp6Address,
+        ClickTypeIp6IfAddr,
+        ClickTypeIp6Network,
+        ClickTypeIpAddress,
+        ClickTypeIpNetwork,
+        ClickTypeMacAddress,
+    )
+
+_LAZY_CLICK_TYPES: frozenset[str] = frozenset(
+    {
+        "ClickTypeIfAddr",
+        "ClickTypeIp4Address",
+        "ClickTypeIp4IfAddr",
+        "ClickTypeIp4Network",
+        "ClickTypeIp6Address",
+        "ClickTypeIp6IfAddr",
+        "ClickTypeIp6Network",
+        "ClickTypeIpAddress",
+        "ClickTypeIpNetwork",
+        "ClickTypeMacAddress",
+    }
+)
+
+
+def __getattr__(name: str, /) -> object:
+    """
+    Lazily resolve the opt-in 'click'-typed CLI helpers so the
+    'click' import is deferred to first access.
+    """
+
+    if name in _LAZY_CLICK_TYPES:
+        from pmd_net_addr import click_types
+
+        return getattr(click_types, name)
+
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__() -> list[str]:
+    """
+    List the public names, including the lazily-exposed CLI
+    helpers.
+    """
+
+    return sorted(__all__)
+
+
+__version__: str = "0.0.1"
+
+__all__ = [
+    "ClickTypeIfAddr",
+    "ClickTypeIp4Address",
+    "ClickTypeIp4IfAddr",
+    "ClickTypeIp4Network",
+    "ClickTypeIp6Address",
+    "ClickTypeIp6IfAddr",
+    "ClickTypeIp6Network",
+    "ClickTypeIpAddress",
+    "ClickTypeIpNetwork",
+    "ClickTypeMacAddress",
+    "IP4__ADDRESS_LEN",
+    "IP6__ADDRESS_LEN",
+    "IfAddr",
+    "IfAddrError",
+    "IfAddrFormatError",
+    "IfAddrSanityError",
+    "Ip4Address",
+    "Ip4AddressError",
+    "Ip4AddressFormatError",
+    "Ip4AddressSanityError",
+    "Ip4IfAddr",
+    "Ip4IfAddrError",
+    "Ip4IfAddrFormatError",
+    "Ip4IfAddrSanityError",
+    "Ip4Mask",
+    "Ip4MaskError",
+    "Ip4MaskFormatError",
+    "Ip4Network",
+    "Ip4NetworkError",
+    "Ip4NetworkFormatError",
+    "Ip4NetworkSanityError",
+    "Ip4Wildcard",
+    "Ip4WildcardError",
+    "Ip4WildcardFormatError",
+    "Ip6Address",
+    "Ip6AddressError",
+    "Ip6AddressFormatError",
+    "Ip6AddressSanityError",
+    "Ip6IfAddr",
+    "Ip6IfAddrError",
+    "Ip6IfAddrFormatError",
+    "Ip6IfAddrSanityError",
+    "Ip6Mask",
+    "Ip6MaskError",
+    "Ip6MaskFormatError",
+    "Ip6Network",
+    "Ip6NetworkError",
+    "Ip6NetworkFormatError",
+    "Ip6NetworkSanityError",
+    "Ip6Wildcard",
+    "Ip6WildcardError",
+    "Ip6WildcardFormatError",
+    "IpAddress",
+    "IpAddressError",
+    "IpAddressFormatError",
+    "IpAddressSanityError",
+    "IpMask",
+    "IpMaskError",
+    "IpMaskFormatError",
+    "IpNetwork",
+    "IpNetworkError",
+    "IpNetworkFormatError",
+    "IpNetworkSanityError",
+    "IpVersion",
+    "IpWildcard",
+    "IpWildcardError",
+    "IpWildcardFormatError",
+    "MAC__ADDRESS_LEN",
+    "MacAddress",
+    "MacAddressError",
+    "MacAddressFormatError",
+    "MacAddressSanityError",
+    "NetAddrError",
+]

pmd_net_addr/address.py

@@ -0,0 +1,293 @@
+################################################################################
+##                                                                            ##
+##   PyTCP - Python TCP/IP stack                                              ##
+##   Copyright (C) 2020-present Sebastian Majewski                            ##
+##                                                                            ##
+##   This program is free software: you can redistribute it and/or modify     ##
+##   it under the terms of the GNU General Public License as published by     ##
+##   the Free Software Foundation, either version 3 of the License, or        ##
+##   (at your option) any later version.                                      ##
+##                                                                            ##
+##   This program is distributed in the hope that it will be useful,          ##
+##   but WITHOUT ANY WARRANTY; without even the implied warranty of           ##
+##   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the             ##
+##   GNU General Public License for more details.                             ##
+##                                                                            ##
+##   You should have received a copy of the GNU General Public License        ##
+##   along with this program. If not, see <https://www.gnu.org/licenses/>.    ##
+##                                                                            ##
+##   Author's email: ccie18643@gmail.com                                      ##
+##   Github repository: https://github.com/ccie18643/PyTCP                    ##
+##                                                                            ##
+################################################################################
+
+
+"""
+This module contains network address base class.
+
+pmd_net_addr/address.py
+
+ver 3.0.7
+"""
+
+from abc import ABC, abstractmethod
+from typing import ClassVar, Self, override
+
+from pmd_net_addr.base import Base
+from pmd_net_addr.errors import IpAddressSanityError, NetAddrError
+
+
+class Address(Base, ABC):
+    """
+    Network address support base class.
+    """
+
+    __slots__ = ("_address",)
+
+    _address: int
+
+    # The address-family width in bytes, bound once per concrete
+    # leaf (class-level constant, same pattern as '_version').
+    # Hot paths ('_with_offset', '__format__', 'max_prefixlen')
+    # read this instead of 'len(memoryview(self))', which would
+    # allocate a fresh bytearray + memoryview on every call.
+    _address_len: ClassVar[int]
+
+    # The concrete value type's free-message sanity error,
+    # raised for operation-precondition / invalid-argument
+    # failures (pmd_net_addr raises only NetAddrError subclasses).
+    # Every concrete subclass overrides this with its specific
+    # Sanity error; the default is a NetAddrError-subclass
+    # safety net so a subclass that omits the override still
+    # honours the §7.1 "no bare builtin escapes" contract
+    # rather than raising AttributeError.
+    _sanity_error: ClassVar[type[NetAddrError]] = IpAddressSanityError
+
+    @abstractmethod
+    def __init__(
+        self,
+        address: Self | str | bytes | bytearray | memoryview | int | None = None,
+        /,
+    ) -> None:
+        """
+        Initialize the network address object. Concrete
+        subclasses bind the accepted input forms.
+        """
+
+        raise NotImplementedError
+
+    def __int__(self) -> int:
+        """
+        Get the network address as integer.
+        """
+
+        return self._address
+
+    def _format_alt(self, format_spec: str, /) -> str | None:
+        """
+        Render a type-specific textual format code, or None if
+        the code is not recognised by this address type. The
+        base type recognises none.
+        """
+
+        return None
+
+    @override
+    def __format__(self, format_spec: str, /) -> str:
+        """
+        Format the address. A type-specific text code ('ex'
+        for the expanded IP form, 'hy' / 'ci' for MAC
+        notations) is rendered by '_format_alt'; 'b' / 'x' /
+        'X' yield the integer zero-padded to the
+        address-family bit width, accepting the '#' (radix
+        prefix) and '_' (4-digit grouping) modifiers; 'd'
+        (plain decimal) and 'n' (locale-aware decimal)
+        delegate verbatim to the stdlib integer formatter and
+        take no modifiers. Any other spec — including an empty
+        spec or a bare fill / align / width / precision with
+        no presentation code — is delegated to str(self), so
+        the canonical text form supports the full string
+        mini-language without a trailing 's'.
+        """
+
+        if not format_spec or format_spec[-1] == "s":
+            return format(str(self), format_spec)
+
+        alt = self._format_alt(format_spec)
+        if alt is not None:
+            return alt
+
+        code = format_spec[-1]
+        flags = format_spec[:-1]
+
+        if code in {"b", "x", "X", "d", "n"}:
+            # 'b' / 'x' / 'X' are the address-family-width
+            # zero-padded radix forms ('#' radix-prefix and '_'
+            # 4-digit grouping modifiers apply); 'd' / 'n'
+            # delegate verbatim to the stdlib integer formatter
+            # ('d' plain decimal, 'n' locale-aware decimal) and
+            # take no modifiers.
+            if not ((code in {"b", "x", "X"} and not (set(flags) - {"#", "_"})) or (code in {"d", "n"} and not flags)):
+                raise type(self)._sanity_error(
+                    f"Unknown format code {format_spec!r} for object of type {type(self).__name__!r}"
+                )
+
+            if code in {"d", "n"}:
+                return format(self._address, code)
+
+            bits = self._address_len * 8
+
+            digit_width = bits if code == "b" else bits // 4
+            digits = format(self._address, f"0{digit_width}{code}")
+
+            if "_" in flags:
+                digits = "_".join(digits[i : i + 4] for i in range(0, len(digits), 4))
+
+            if "#" in flags:
+                digits = ("0b" if code == "b" else "0x") + digits
+
+            return digits
+
+        # No recognised custom code: the spec is a
+        # string-presentation spec (bare fill / align / width /
+        # precision, no trailing 's' required). Delegate to
+        # str(self), converting the builtin ValueError that an
+        # unknown presentation code raises into this type's
+        # sanity error (pmd_net_addr.md §7.1 — no bare builtin
+        # escapes; chain the cause so the offending code is
+        # greppable in the traceback).
+        try:
+            return format(str(self), format_spec)
+        except ValueError as error:
+            raise type(self)._sanity_error(
+                f"Unknown format code {format_spec!r} for object of type {type(self).__name__!r}"
+            ) from error
+
+    @abstractmethod
+    def __buffer__(self, _: int) -> memoryview:
+        """
+        Get the network address as a memoryview.
+        """
+
+        raise NotImplementedError
+
+    @override
+    def __eq__(self, other: object, /) -> bool:
+        """
+        Compare the network address with another object.
+        """
+
+        return other is self or (isinstance(other, type(self)) and self._address == other._address)
+
+    @override
+    def __hash__(self) -> int:
+        """
+        Get the network address hash value.
+        """
+
+        return hash((type(self), self._address))
+
+    def __lt__(self, other: object, /) -> bool:
+        """
+        Order the network address by its integer value. Ordering
+        across address types (e.g. IPv4 vs IPv6) is undefined and
+        raises TypeError.
+        """
+
+        if not isinstance(other, type(self)):
+            return NotImplemented
+
+        return self._address < other._address
+
+    def __le__(self, other: object, /) -> bool:
+        """
+        Order the network address by its integer value. Ordering
+        across address types (e.g. IPv4 vs IPv6) is undefined and
+        raises TypeError.
+        """
+
+        if not isinstance(other, type(self)):
+            return NotImplemented
+
+        return self._address <= other._address
+
+    def __gt__(self, other: object, /) -> bool:
+        """
+        Order the network address by its integer value. Ordering
+        across address types (e.g. IPv4 vs IPv6) is undefined and
+        raises TypeError.
+        """
+
+        if not isinstance(other, type(self)):
+            return NotImplemented
+
+        return self._address > other._address
+
+    def __ge__(self, other: object, /) -> bool:
+        """
+        Order the network address by its integer value. Ordering
+        across address types (e.g. IPv4 vs IPv6) is undefined and
+        raises TypeError.
+        """
+
+        if not isinstance(other, type(self)):
+            return NotImplemented
+
+        return self._address >= other._address
+
+    def _with_offset(self, delta: int, /) -> Self:
+        """
+        Get this address shifted by an integer offset. An
+        out-of-range result is an invalid-operation outcome, not
+        a malformed literal, so it raises the address type's
+        sanity error naming the operation (pmd_net_addr.md §7.2).
+        """
+
+        result = self._address + delta
+
+        if not 0 <= result <= (1 << (self._address_len * 8)) - 1:
+            raise type(self)._sanity_error(
+                f"{type(self).__name__} offset out of range: " f"{self} {'+' if delta >= 0 else '-'} {abs(delta)}"
+            )
+
+        return type(self)(result)
+
+    def __add__(self, other: object, /) -> Self:
+        """
+        Get the network address advanced by an integer offset.
+        An out-of-range result raises the address-type sanity
+        error.
+        """
+
+        if not isinstance(other, int):
+            return NotImplemented
+
+        return self._with_offset(other)
+
+    def __sub__(self, other: object, /) -> Self:
+        """
+        Get the network address retreated by an integer offset.
+        An out-of-range result raises the address-type sanity
+        error.
+        """
+
+        if not isinstance(other, int):
+            return NotImplemented
+
+        return self._with_offset(-other)
+
+    @property
+    def unspecified(self) -> Self:
+        """
+        Get the unspecified network address.
+        """
+
+        return type(self)()
+
+    @property
+    def is_unspecified(self) -> bool:
+        """
+        Check if the network address is unspecified.
+        """
+
+        return self._address == 0

pmd_net_addr/base.py

@@ -0,0 +1,79 @@
+################################################################################
+##                                                                            ##
+##   PyTCP - Python TCP/IP stack                                              ##
+##   Copyright (C) 2020-present Sebastian Majewski                            ##
+##                                                                            ##
+##   This program is free software: you can redistribute it and/or modify     ##
+##   it under the terms of the GNU General Public License as published by     ##
+##   the Free Software Foundation, either version 3 of the License, or        ##
+##   (at your option) any later version.                                      ##
+##                                                                            ##
+##   This program is distributed in the hope that it will be useful,          ##
+##   but WITHOUT ANY WARRANTY; without even the implied warranty of           ##
+##   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the             ##
+##   GNU General Public License for more details.                             ##
+##                                                                            ##
+##   You should have received a copy of the GNU General Public License        ##
+##   along with this program. If not, see <https://www.gnu.org/licenses/>.    ##
+##                                                                            ##
+##   Author's email: ccie18643@gmail.com                                      ##
+##   Github repository: https://github.com/ccie18643/PyTCP                    ##
+##                                                                            ##
+################################################################################
+
+
+"""
+This module contains the base class for all NetAddr objects.
+
+pmd_net_addr/base.py
+
+ver 3.0.7
+"""
+
+from abc import ABC, abstractmethod
+from typing import override
+
+
+class Base(ABC):
+    """
+    NetAddr base class.
+    """
+
+    __slots__ = ()
+
+    @override
+    @abstractmethod
+    def __str__(self) -> str:
+        """
+        Get the network object log string.
+        """
+
+        raise NotImplementedError
+
+    @override
+    def __repr__(self) -> str:
+        """
+        Get the network object representation string.
+        """
+
+        return f"{type(self).__name__}({str(self)!r})"
+
+    @override
+    @abstractmethod
+    def __eq__(self, other: object, /) -> bool:
+        """
+        Check if two network objects are equal.
+        """
+
+        raise NotImplementedError
+
+    @override
+    @abstractmethod
+    def __hash__(self) -> int:
+        """
+        Get the network object hash value. Concrete value types
+        define this consistently with their own '__eq__' (every
+        subclass overrides it).
+        """
+
+        raise NotImplementedError