feat: first version (#2)

Author: bdraco

README.md

@@ -35,6 +35,14 @@
 
 Cache construction of ipaddress objects
 
+## Design
+
+This module keeps a cache of IPAddress objects and caches the properties on them.
+
+It it useful when you frequently see the same ip addresses over and over and
+do not want to pay the overhead of constructing IPAddress objects over and over
+or checking their properties.
+
 ## Installation
 
 Install this via pip (or your favourite package manager):
@@ -43,10 +51,14 @@ Install this via pip (or your favourite package manager):
 
 ## Usage
 
-Start by importing it:
-
 ```python
-import cached_ipaddress
+from cached_ipaddress import cached_ip_addresses
+
+ip = cached_ip_addresses("127.0.0.1")
+assert ip.is_loopback is False
+
+invalid = cached_ip_addresses("invalid")
+assert invalid is None
 ```
 
 ## Contributors ✨

build_ext.py

@@ -0,0 +1,47 @@
+"""Build optional cython modules."""
+
+import logging
+import os
+from distutils.command.build_ext import build_ext
+from typing import Any
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class BuildExt(build_ext):
+    """BuildExt."""
+
+    def build_extensions(self) -> None:
+        """Build extensions."""
+        try:
+            super().build_extensions()
+        except Exception:
+            _LOGGER.debug("Failed to build extensions", exc_info=True)
+            pass
+
+
+def build(setup_kwargs: Any) -> None:
+    """Build optional cython modules."""
+    if os.environ.get("SKIP_CYTHON", False):
+        return
+    try:
+        from Cython.Build import cythonize
+
+        setup_kwargs.update(
+            {
+                "ext_modules": cythonize(
+                    [
+                        "src/cached_ipaddress/ipaddress.py",
+                    ],
+                    compiler_directives={"language_level": "3"},  # Python 3
+                ),
+                "cmdclass": {"build_ext": BuildExt},
+            }
+        )
+        setup_kwargs["exclude_package_data"] = {
+            pkg: ["*.c"] for pkg in setup_kwargs["packages"]
+        }
+    except Exception:
+        if os.environ.get("REQUIRE_CYTHON"):
+            raise
+        pass

pyproject.toml

@@ -21,6 +21,10 @@ packages = [
 "Bug Tracker" = "https://github.com/bdraco/cached-ipaddress/issues"
 "Changelog" = "https://github.com/bdraco/cached-ipaddress/blob/main/CHANGELOG.md"
 
+[tool.poetry.build]
+generate-setup-file = true
+script = "build_ext.py"
+
 [tool.poetry.dependencies]
 python = "^3.7"
 
@@ -125,5 +129,6 @@ module = "tests.*"
 allow_untyped_defs = true
 
 [build-system]
-requires = ["poetry-core>=1.0.0"]
+# 1.5.2 required for https://github.com/python-poetry/poetry/issues/7505
+requires = ['setuptools>=65.4.1', 'wheel', 'Cython>=3.0.5', "poetry-core>=1.5.2"]
 build-backend = "poetry.core.masonry.api"

setup.py

@@ -1 +1,5 @@
 __version__ = "0.0.1"
+
+from .ipaddress import cached_ip_addresses
+
+__all__ = ["cached_ip_addresses"]

src/cached_ipaddress/__init__.py

@@ -0,0 +1,82 @@
+"""Functools backports from standard lib."""
+from __future__ import annotations
+
+import sys
+import types
+from collections.abc import Callable
+from typing import Any, Generic, TypeVar, overload
+
+_T = TypeVar("_T")
+
+
+class cached_property(Generic[_T]):  # pylint: disable=invalid-name
+    """
+    Backport of Python 3.12's cached_property.
+
+    Includes https://github.com/python/cpython/pull/101890/files
+    """
+
+    def __init__(self, func: Callable[[Any], _T]) -> None:
+        """Initialize."""
+        self.func: Callable[[Any], _T] = func
+        self.attrname: str | None = None
+        self.__doc__ = func.__doc__
+
+    def __set_name__(self, owner: type[Any], name: str) -> None:
+        """Set name."""
+        if self.attrname is None:
+            self.attrname = name
+        elif name != self.attrname:
+            raise TypeError(
+                "Cannot assign the same cached_property to two different names "
+                f"({self.attrname!r} and {name!r})."
+            )
+
+    @overload
+    def __get__(self, instance: None, owner: type[Any] | None = None) -> Any:
+        ...
+
+    @overload
+    def __get__(self, instance: Any, owner: type[Any] | None = None) -> _T:
+        ...
+
+    def __get__(self, instance: Any | None, owner: type[Any] | None = None) -> _T | Any:
+        """Get."""
+        if instance is None:
+            return self
+        if self.attrname is None:
+            raise TypeError(
+                "Cannot use cached_property instance without "
+                "calling __set_name__ on it."
+            )
+        try:
+            cache = instance.__dict__
+        # not all objects have __dict__ (e.g. class defines slots)
+        except AttributeError:
+            msg = (
+                f"No '__dict__' attribute on {type(instance).__name__!r} "
+                f"instance to cache {self.attrname!r} property."
+            )
+            raise TypeError(msg) from None
+        val = self.func(instance)
+        try:
+            cache[self.attrname] = val
+        except TypeError:
+            msg = (
+                f"The '__dict__' attribute on {type(instance).__name__!r} instance "
+                f"does not support item assignment "
+                f"for caching {self.attrname!r} property."
+            )
+            raise TypeError(msg) from None
+        return val
+
+    if sys.version_info >= (3, 9):
+        __class_getitem__ = classmethod(types.GenericAlias)  # type: ignore
+    else:
+
+        def __class_getitem__(
+            cls: type[cached_property],
+            cls_item: Any,
+        ) -> type[cached_property]:
+            """Get item."""
+            return cls

src/cached_ipaddress/backports/__init__.py

@@ -0,0 +1,5 @@
+import cython
+
+cdef object cached_ip_addresses_wrapper
+cdef object AddressValueError
+cdef object NetmaskValueError

src/cached_ipaddress/backports/functools.py

@@ -0,0 +1,81 @@
+"""Base implementation."""
+
+from functools import lru_cache
+from ipaddress import AddressValueError, IPv4Address, IPv6Address, NetmaskValueError
+from typing import Optional, Union
+
+from .backports.functools import cached_property
+
+
+class CachedIPv4Address(IPv4Address):
+    def __str__(self) -> str:
+        """Return the string representation of the IPv4 address."""
+        return self._str
+
+    @cached_property
+    def _str(self) -> str:
+        """Return the string representation of the IPv4 address."""
+        return super().__str__()
+
+    @cached_property
+    def is_link_local(self) -> bool:  # type: ignore[override]
+        """Return True if this is a link-local address."""
+        return super().is_link_local
+
+    @cached_property
+    def is_unspecified(self) -> bool:  # type: ignore[override]
+        """Return True if this is an unspecified address."""
+        return super().is_unspecified
+
+    @cached_property
+    def is_loopback(self) -> bool:  # type: ignore[override]
+        """Return True if this is a loopback address."""
+        return super().is_loopback
+
+
+class CachedIPv6Address(IPv6Address):
+    def __str__(self) -> str:
+        """Return the string representation of the IPv6 address."""
+        return self._str
+
+    @cached_property
+    def _str(self) -> str:
+        """Return the string representation of the IPv6 address."""
+        return super().__str__()
+
+    @cached_property
+    def is_link_local(self) -> bool:  # type: ignore[override]
+        """Return True if this is a link-local address."""
+        return super().is_link_local
+
+    @cached_property
+    def is_unspecified(self) -> bool:  # type: ignore[override]
+        """Return True if this is an unspecified address."""
+        return super().is_unspecified
+
+    @cached_property
+    def is_loopback(self) -> bool:  # type: ignore[override]
+        """Return True if this is a loopback address."""
+        return super().is_loopback
+
+
+@lru_cache(maxsize=512)
+def _cached_ip_addresses(
+    address: Union[str, bytes, int]
+) -> Optional[Union[IPv4Address, IPv6Address]]:
+    """Cache IP addresses."""
+    try:
+        return CachedIPv4Address(address)
+    except (AddressValueError, NetmaskValueError):
+        pass
+
+    try:
+        return CachedIPv6Address(address)
+    except (AddressValueError, NetmaskValueError):
+        return None
+
+
+cached_ip_addresses_wrapper = _cached_ip_addresses
+cached_ip_addresses = cached_ip_addresses_wrapper
+
+__all__ = ("cached_ip_addresses",)

src/cached_ipaddress/ipaddress.pxd

@@ -0,0 +1,45 @@
+"""Unit tests for cached_ipaddress.ipaddress."""
+
+from cached_ipaddress import ipaddress
+
+
+def test_cached_ip_addresses_wrapper():
+    """Test the cached_ip_addresses_wrapper."""
+    assert ipaddress.cached_ip_addresses("") is None
+    assert ipaddress.cached_ip_addresses("foo") is None
+    assert (
+        str(
+            ipaddress.cached_ip_addresses(
+                b"&\x06(\x00\x02 \x00\x01\x02H\x18\x93%\xc8\x19F"
+            )
+        )
+        == "2606:2800:220:1:248:1893:25c8:1946"
+    )
+    assert ipaddress.cached_ip_addresses("::1") == ipaddress.IPv6Address("::1")
+
+    ipv4 = ipaddress.cached_ip_addresses("169.254.0.0")
+    assert ipv4 is not None
+    assert ipv4.is_link_local is True
+    assert ipv4.is_unspecified is False
+    assert ipv4.is_loopback is False
+    assert str(ipv4) == "169.254.0.0"
+    assert str(ipv4) == "169.254.0.0"
+
+    ipv4 = ipaddress.cached_ip_addresses("0.0.0.0")  # noqa: S104
+    assert ipv4 is not None
+    assert ipv4.is_link_local is False
+    assert ipv4.is_unspecified is True
+    assert ipv4.is_loopback is False
+
+    ipv6 = ipaddress.cached_ip_addresses("fe80::1")
+    assert ipv6 is not None
+    assert ipv6.is_link_local is True
+    assert ipv6.is_unspecified is False
+    assert ipv6.is_loopback is False
+
+    ipv6 = ipaddress.cached_ip_addresses("0:0:0:0:0:0:0:0")
+    assert ipv6 is not None
+    assert ipv6.is_link_local is False
+    assert ipv6.is_unspecified is True
+    assert ipv6.is_loopback is False
+    assert str(ipv6) == "::"