abcreg 0.1.0__py3-none-any.whl

abcreg/__init__.py

@@ -0,0 +1,3 @@
+from abcreg.annotated_abc import AnnotatedABC, AnnotatedABCMeta
+
+__all__ = ["AnnotatedABC", "AnnotatedABCMeta"]

abcreg/_annotations.py

@@ -0,0 +1,6 @@
+try:
+    from annotationlib import get_annotations
+except ImportError:
+    from inspect import get_annotations
+
+__all__ = ["get_annotations"]

abcreg/annotated_abc.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+import sys
+from abc import ABC, ABCMeta
+from collections.abc import Callable
+from typing import get_type_hints
+
+__all__ = ["AnnotatedABC", "AnnotatedABCMeta"]
+
+
+def _normalize_annotations(fn: Callable[..., object]) -> dict[str, object]:
+    module_name = getattr(fn, "__module__", None)
+    module = sys.modules.get(module_name) if module_name is not None else None
+    globalns = vars(module) if module is not None else {}
+    return get_type_hints(fn, globalns=globalns, localns=globalns)
+
+
+def _has_fn(
+    impl: type,
+    abc: type,
+    name: str,
+    expected: dict[str, object],
+) -> bool:
+    skip = set(abc.__mro__)
+    for base in impl.__mro__:
+        if base in skip:
+            continue
+        for key, value in base.__dict__.items():
+            if key == name and _normalize_annotations(value) == expected:
+                return True
+    return False
+
+
+class AnnotatedABCMeta(ABCMeta):
+    def register(cls, subclass: type) -> type:
+        cls._validate_implementation(subclass)
+        return super().register(subclass)
+
+    def _validate_implementation(cls, impl: type) -> None:
+        for name, expected in cls._abstract_annotations().items():
+            if not _has_fn(impl, cls, name, expected):
+                msg = (
+                    f"{impl!r} does not fully implement {cls.__name__!r}: "
+                    f"missing or mismatched {name!r}"
+                )
+                raise TypeError(msg)
+
+    def _abstract_annotations(cls) -> dict[str, dict[str, object]]:
+        methods: dict[str, dict[str, object]] = {}
+        for base in cls.__mro__:
+            if not isinstance(base, AnnotatedABCMeta):
+                continue
+            for name, value in base.__dict__.items():
+                if getattr(value, "__isabstractmethod__", False):
+                    methods[name] = _normalize_annotations(value)
+        return methods
+
+
+class AnnotatedABC(ABC, metaclass=AnnotatedABCMeta):
+    def __init_subclass__(cls, **kwargs: object) -> None:
+        super().__init_subclass__(**kwargs)
+        for base in cls.__bases__:
+            if isinstance(base, AnnotatedABCMeta):
+                base._validate_implementation(cls)

abcreg-0.1.0.dist-info/METADATA

@@ -0,0 +1,53 @@
+Metadata-Version: 2.4
+Name: abcreg
+Version: 0.1.0
+Summary: Add your description here
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# ABCReg
+
+ABCReg adds `AnnotatedABC` and `AnnotatedABCMeta`, which provide additional interface checking at registration time to ensure that registered virtual and ordinary subclasses are valid.
+
+Use ABCReg if you are designing a plugin API or any other interface that might be implemented by an end user.
+
+## Defining the Interface
+
+Use `AnnotatedABC` just like an ordinary `ABC`. Make sure to mark your API methods as abstract and provide type hints:
+
+```
+from abc import abstractmethod
+from abcreg import AnnotatedABC
+
+class Queryable(AnnotatedABC):
+    @abstractmethod
+    def query(self, **kwargs) -> str: ...
+```
+
+We recommend you use virtual inheritance:
+
+```
+@Queryable.register(VirtualQueryProvider)
+class VirtualQueryProvider:
+    def query(self, **kwargs) -> str:
+        return "query result"
+
+assert issubclass(VirtualQueryProvider, Queryable)
+assert isinstance(VirtualQueryProvider(), Queryable)
+```
+
+But, regular inheritance will also work:
+
+```
+class QueryProvider(Queryable):
+    def query(self, **kwargs) -> str:
+        return "query result"
+
+assert issubclass(QueryProvider, Queryable)
+```
+
+## Requirements and Usage
+
+Requries Python `3.10+`. With UV, require with `uv add abcreg`.

abcreg-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+abcreg/__init__.py,sha256=1JEWr2wq1tgplAefagpPIHuqpmALZp0FI1-WhhK01Cs,112
+abcreg/_annotations.py,sha256=XTx1JVn1GZvhMmX4470dszFkPiWHek0VabhFbRWuS_s,142
+abcreg/annotated_abc.py,sha256=3OCn0UVJBvhPUp50P1WreRgBygHNAX6qXSnSI01dLuk,2202
+abcreg-0.1.0.dist-info/METADATA,sha256=m4AzddYA0ht1YxFR0jf77_FJvYV_8lj6zr3csiY3Fq8,1398
+abcreg-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+abcreg-0.1.0.dist-info/licenses/LICENSE,sha256=oWN3hgCPpp69WEgHXOML1NEDCYdp6SRmvMTEl0XK9ko,1068
+abcreg-0.1.0.dist-info/RECORD,,

abcreg-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

abcreg-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Will Bowers
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.