ducktools-classbuilder 0.12.1__py3-none-any.whl

ducktools/classbuilder/__init__.pyi

@@ -0,0 +1,283 @@
+import sys
+import types
+import typing
+import typing_extensions
+
+
+from collections.abc import Callable
+from types import MappingProxyType
+
+if sys.version_info >= (3, 14):
+    import annotationlib
+
+    _py_type = annotationlib.ForwardRef | type | str
+else:
+    _py_type = type | str
+
+_CopiableMappings = dict[str, typing.Any] | MappingProxyType[str, typing.Any]
+
+__version__: str
+__version_tuple__: tuple[str | int, ...]
+INTERNALS_DICT: str
+META_GATHERER_NAME: str
+GATHERED_DATA: str
+
+def get_fields(cls: type, *, local: bool = False) -> dict[str, Field]: ...
+
+def get_flags(cls: type) -> dict[str, bool]: ...
+
+def get_methods(cls: type) -> types.MappingProxyType[str, MethodMaker]: ...
+
+def get_generated_code(cls: type) -> dict[str, GeneratedCode]: ...
+
+def print_generated_code(cls: type) -> None: ...
+
+def build_completed(ns: _CopiableMappings) -> bool: ...
+
+def _get_inst_fields(inst: typing.Any) -> dict[str, typing.Any]: ...
+
+class _NothingType:
+    def __init__(self, custom: str | None = ...) -> None: ...
+    def __repr__(self) -> str: ...
+NOTHING: _NothingType
+FIELD_NOTHING: _NothingType
+
+class _KW_ONLY_META(type):
+    def __repr__(self) -> str: ...
+
+class KW_ONLY(metaclass=_KW_ONLY_META): ...
+
+# Stub Only
+@typing.type_check_only
+class _CodegenType(typing.Protocol):
+    def __call__(self, cls: type, funcname: str = ...) -> GeneratedCode: ...
+
+class GeneratedCode:
+    __slots__: tuple[str, ...]
+    source_code: str
+    globs: dict[str, typing.Any]
+    annotations: dict[str, typing.Any]
+
+    def __init__(
+        self,
+        source_code: str,
+        globs: dict[str, typing.Any],
+        annotations: dict[str, typing.Any] | None = ...,
+    ) -> None: ...
+    def __repr__(self) -> str: ...
+
+class MethodMaker:
+    funcname: str
+    code_generator: _CodegenType
+    def __init__(self, funcname: str, code_generator: _CodegenType) -> None: ...
+    def __repr__(self) -> str: ...
+    def __get__(self, instance, cls) -> Callable: ...
+
+class _SignatureMaker:
+    def __get__(self, instance, cls=None) -> typing_extensions.Never: ...
+
+signature_maker: _SignatureMaker
+
+def get_init_generator(
+    null: _NothingType = NOTHING,
+    extra_code: None | list[str] = None
+) -> _CodegenType: ...
+
+def init_generator(cls: type, funcname: str="__init__") -> GeneratedCode: ...
+
+def get_repr_generator(
+    recursion_safe: bool = False,
+    eval_safe: bool = False
+) -> _CodegenType: ...
+def repr_generator(cls: type, funcname: str = "__repr__") -> GeneratedCode: ...
+def eq_generator(cls: type, funcname: str = "__eq__") -> GeneratedCode: ...
+def replace_generator(cls: type, funcname: str = "__replace__") -> GeneratedCode: ...
+
+def frozen_setattr_generator(cls: type, funcname: str = "__setattr__") -> GeneratedCode: ...
+
+def frozen_delattr_generator(cls: type, funcname: str = "__delattr__") -> GeneratedCode: ...
+
+init_maker: MethodMaker
+repr_maker: MethodMaker
+eq_maker: MethodMaker
+replace_maker: MethodMaker
+frozen_setattr_maker: MethodMaker
+frozen_delattr_maker: MethodMaker
+default_methods: frozenset[MethodMaker]
+
+_T = typing.TypeVar("_T")
+
+@typing.overload
+def builder(
+    cls: type[_T],
+    /,
+    *,
+    gatherer: Callable[[type], tuple[dict[str, Field], dict[str, typing.Any]]],
+    methods: frozenset[MethodMaker] | set[MethodMaker],
+    flags: dict[str, bool] | None = None,
+    fix_signature: bool = ...,
+) -> type[_T]: ...
+
+@typing.overload
+def builder(
+    cls: None = None,
+    /,
+    *,
+    gatherer: Callable[[type], tuple[dict[str, Field], dict[str, typing.Any]]],
+    methods: frozenset[MethodMaker] | set[MethodMaker],
+    flags: dict[str, bool] | None = None,
+    fix_signature: bool = ...,
+) -> Callable[[type[_T]], type[_T]]: ...
+
+
+class SlotFields(dict):
+    ...
+
+
+class SlotMakerMeta(type):
+    def __new__(
+        cls: type[_T],
+        name: str,
+        bases: tuple[type, ...],
+        ns: dict[str, typing.Any],
+        slots: bool = ...,
+        gatherer: Callable[[type], tuple[dict[str, Field], dict[str, typing.Any]]] | None = ...,
+        ignore_annotations: bool | None = ...,
+        **kwargs: typing.Any,
+    ) -> _T: ...
+
+
+class Field(metaclass=SlotMakerMeta):
+    default: _NothingType | typing.Any
+    default_factory: _NothingType | typing.Any
+    type: _NothingType | _py_type
+    doc: None | str
+    init: bool
+    repr: bool
+    compare: bool
+    kw_only: bool
+
+    __slots__: dict[str, str]
+    __classbuilder_internals__: dict
+    __signature__: _SignatureMaker
+
+    def __init__(
+        self,
+        *,
+        default: _NothingType | typing.Any = ...,
+        default_factory: _NothingType | typing.Any = ...,
+        type: _NothingType | _py_type = ...,
+        doc: None | str = ...,
+        init: bool = ...,
+        repr: bool = ...,
+        compare: bool = ...,
+        kw_only: bool = ...,
+    ) -> None: ...
+
+    def __init_subclass__(cls, frozen: bool = ..., ignore_annotations: bool = ...): ...
+    def __repr__(self) -> str: ...
+    def __eq__(self, other: Field | object) -> bool: ...
+    def validate_field(self) -> None: ...
+    @classmethod
+    def from_field(cls, fld: Field, /, **kwargs: typing.Any) -> Field: ...
+
+# type[Field] doesn't work due to metaclass
+# This is not really precise enough because isinstance is used
+_ReturnsField = Callable[..., Field]
+_FieldType = typing.TypeVar("_FieldType", bound=Field)
+
+@typing.overload
+def make_slot_gatherer(
+    field_type: type[_FieldType]
+) -> Callable[[type | _CopiableMappings], tuple[dict[str, _FieldType], dict[str, typing.Any]]]: ...
+
+@typing.overload
+def make_slot_gatherer(
+    field_type: _ReturnsField = Field
+) -> Callable[[type | _CopiableMappings], tuple[dict[str, Field], dict[str, typing.Any]]]: ...
+
+@typing.overload
+def make_annotation_gatherer(
+    field_type: type[_FieldType],
+    leave_default_values: bool = False,
+) -> Callable[[type | _CopiableMappings], tuple[dict[str, _FieldType], dict[str, typing.Any]]]: ...
+
+@typing.overload
+def make_annotation_gatherer(
+    field_type: _ReturnsField = Field,
+    leave_default_values: bool = False,
+) -> Callable[[type | _CopiableMappings], tuple[dict[str, Field], dict[str, typing.Any]]]: ...
+
+@typing.overload
+def make_field_gatherer(
+    field_type: type[_FieldType],
+    leave_default_values: bool = False,
+) -> Callable[[type | _CopiableMappings], tuple[dict[str, _FieldType], dict[str, typing.Any]]]: ...
+
+@typing.overload
+def make_field_gatherer(
+    field_type: _ReturnsField = Field,
+    leave_default_values: bool = False,
+) -> Callable[[type | _CopiableMappings], tuple[dict[str, Field], dict[str, typing.Any]]]: ...
+
+@typing.overload
+def make_unified_gatherer(
+    field_type: type[_FieldType],
+    leave_default_values: bool = ...,
+) -> Callable[[type | _CopiableMappings], tuple[dict[str, _FieldType], dict[str, typing.Any]]]: ...
+
+@typing.overload
+def make_unified_gatherer(
+    field_type: _ReturnsField = ...,
+    leave_default_values: bool = ...,
+) -> Callable[[type | _CopiableMappings], tuple[dict[str, Field], dict[str, typing.Any]]]: ...
+
+
+def slot_gatherer(cls_or_ns: type | _CopiableMappings) -> tuple[dict[str, Field], dict[str, typing.Any]]: ...
+def annotation_gatherer(
+    cls_or_ns: type | _CopiableMappings,
+    *,
+    cls_annotations: None | dict[str, typing.Any] = ...
+) -> tuple[dict[str, Field], dict[str, typing.Any]]: ...
+
+def unified_gatherer(cls_or_ns: type | _CopiableMappings) -> tuple[dict[str, Field], dict[str, typing.Any]]: ...
+
+
+def check_argument_order(cls: type) -> None: ...
+
+@typing.overload
+def slotclass(
+    cls: type[_T],
+    /,
+    *,
+    methods: frozenset[MethodMaker] | set[MethodMaker] = default_methods,
+    syntax_check: bool = True
+) -> type[_T]: ...
+
+@typing.overload
+def slotclass(
+    cls: None = None,
+    /,
+    *,
+    methods: frozenset[MethodMaker] | set[MethodMaker] = default_methods,
+    syntax_check: bool = True
+) -> Callable[[type[_T]], type[_T]]: ...
+
+
+_gatherer_type = Callable[[type | _CopiableMappings], tuple[dict[str, Field], dict[str, typing.Any]]]
+
+class GatheredFields:
+    __slots__: tuple[str, ...]
+
+    fields: dict[str, Field]
+    modifications: dict[str, typing.Any]
+
+    def __init__(
+        self,
+        fields: dict[str, Field],
+        modifications: dict[str, typing.Any]
+    ) -> None: ...
+
+    def __repr__(self) -> str: ...
+    def __eq__(self, other) -> bool: ...
+    def __call__(self, cls_dict: type | dict[str, typing.Any]) -> tuple[dict[str, Field], dict[str, typing.Any]]: ...

ducktools/classbuilder/_version.py

@@ -0,0 +1,2 @@
+__version__ = "0.12.1"
+__version_tuple__ = (0, 12, 1)

ducktools/classbuilder/annotations/__init__.py

@@ -0,0 +1,63 @@
+# MIT License
+#
+# Copyright (c) 2024 David C Ellis
+#
+# 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.
+
+import sys
+
+if sys.version_info >= (3, 14):
+    from .annotations_314 import (
+        get_func_annotations,
+        get_ns_annotations,
+    )
+else:
+    from .annotations_pre_314 import (
+        get_func_annotations,
+        get_ns_annotations,
+    )
+
+
+__all__ = [
+    "get_func_annotations",
+    "get_ns_annotations",
+    "is_classvar",
+]
+
+
+def is_classvar(hint):
+    if isinstance(hint, str):
+        # String annotations, just check if the string 'ClassVar' is in there
+        # This is overly broad and could be smarter.
+        return "ClassVar" in hint
+    else:
+        _typing = sys.modules.get("typing")
+        if _typing:
+            _Annotated = _typing.Annotated
+            _get_origin = _typing.get_origin
+
+            if _Annotated and _get_origin(hint) is _Annotated:
+                hint = getattr(hint, "__origin__", None)
+
+            if (
+                hint is _typing.ClassVar
+                or getattr(hint, "__origin__", None) is _typing.ClassVar
+            ):
+                return True
+    return False

ducktools/classbuilder/annotations/annotations_314.py

@@ -0,0 +1,104 @@
+# MIT License
+#
+# Copyright (c) 2024 David C Ellis
+#
+# 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.
+
+"""
+Python 3.14 has new annotations methods, but does not provide any correct way to handle VALUE
+annotation generation for new __init__ methods.
+
+The approach taken here is to try to use VALUE annotations, if those fail it falls back to
+STRING annotations, as if __future__ annotations actually arrived.
+
+Hopefully in a future version of Python we will have complete, correct, performant annotations
+so we can use a more standard format.
+"""
+
+class _LazyAnnotationLib:
+    def __getattr__(self, item):
+        global _lazy_annotationlib
+        import annotationlib  # type: ignore
+        _lazy_annotationlib = annotationlib
+        return getattr(annotationlib, item)
+
+
+_lazy_annotationlib = _LazyAnnotationLib()
+
+
+def get_func_annotations(func, use_forwardref=False):
+    """
+    Given a function, return the annotations dictionary
+
+    :param func: function object
+    :return: dictionary of annotations
+    """
+    # Try to get `__annotations__` for VALUE annotations first
+    try:
+        raw_annotations = func.__annotations__
+    except Exception:
+        fmt = (
+            _lazy_annotationlib.Format.FORWARDREF
+            if use_forwardref
+            else _lazy_annotationlib.Format.STRING
+        )
+        annotations = _lazy_annotationlib.get_annotations(func, format=fmt)
+    else:
+        annotations = raw_annotations.copy()
+
+    return annotations
+
+
+def get_ns_annotations(ns, cls=None, use_forwardref=False):
+    """
+    Given a class namespace, attempt to retrieve the
+    annotations dictionary.
+
+    :param ns: Class namespace (eg cls.__dict__)
+    :param cls: Class if available
+    :param use_forwardref: Use FORWARDREF instead of STRING if VALUE fails
+    :return: dictionary of annotations
+    """
+
+    annotations = ns.get("__annotations__")
+    if annotations is not None:
+        annotations = annotations.copy()
+    else:
+        # See if we're using PEP-649 annotations
+        annotate = _lazy_annotationlib.get_annotate_from_class_namespace(ns)
+        if annotate:
+            try:
+                annotations = annotate(_lazy_annotationlib.Format.VALUE)
+            except Exception:
+                fmt = (
+                    _lazy_annotationlib.Format.FORWARDREF
+                    if use_forwardref
+                    else _lazy_annotationlib.Format.STRING
+                )
+
+                annotations = _lazy_annotationlib.call_annotate_function(
+                    annotate,
+                    format=fmt,
+                    owner=cls
+                )
+
+    if annotations is None:
+        annotations = {}
+
+    return annotations

ducktools/classbuilder/annotations/annotations_pre_314.py

@@ -0,0 +1,42 @@
+# MIT License
+#
+# Copyright (c) 2024 David C Ellis
+#
+# 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.
+
+def get_func_annotations(func, use_forwardref=False):
+    """
+    Given a function, return the annotations dictionary
+
+    :param func: function object
+    :return: dictionary of annotations
+    """
+    annotations = func.__annotations__
+    return annotations
+
+
+# This is simplified under 3.13 or earlier
+def get_ns_annotations(ns, cls=None, use_forwardref=False):
+    annotations = ns.get("__annotations__")
+    if annotations is not None:
+        annotations = annotations.copy()
+    else:
+        annotations = {}
+    return annotations
+

ducktools/classbuilder/annotations.pyi

@@ -0,0 +1,21 @@
+from collections.abc import Callable
+import typing
+import types
+import sys
+
+_CopiableMappings = dict[str, typing.Any] | types.MappingProxyType[str, typing.Any]
+
+def get_func_annotations(
+    func: types.FunctionType,
+    use_forwardref: bool = ...,
+) -> dict[str, typing.Any]: ...
+
+def get_ns_annotations(
+    ns: _CopiableMappings,
+    cls: type | None = ...,
+    use_forwardref: bool = ...,
+) -> dict[str, typing.Any]: ...
+
+def is_classvar(
+    hint: object,
+) -> bool: ...