ducktools-classbuilder 0.5.0__py3-none-any.whl → 0.6.0__py3-none-any.whl

ducktools/classbuilder/__init__.pyi

@@ -1,43 +1,70 @@
+import types
 import typing
+
 from collections.abc import Callable
+from types import MappingProxyType
+from typing_extensions import dataclass_transform
 
-_py_type = type  # Alias for type where it is used as a name
+_py_type = type | str  # Alias for type hint values
+_CopiableMappings = dict[str, typing.Any] | MappingProxyType[str, typing.Any]
 
 __version__: str
 INTERNALS_DICT: str
+META_GATHERER_NAME: str
 
 def get_fields(cls: type, *, local: bool = False) -> dict[str, Field]: ...
 
-def get_flags(cls:type) -> dict[str, bool]: ...
+def get_flags(cls: type) -> dict[str, bool]: ...
+
+def get_methods(cls: type) -> types.MappingProxyType[str, MethodMaker]: ...
 
 def _get_inst_fields(inst: typing.Any) -> dict[str, typing.Any]: ...
 
 class _NothingType:
-    ...
+    def __repr__(self) -> str: ...
 NOTHING: _NothingType
 
+# noinspection PyPep8Naming
+class _KW_ONLY_TYPE:
+    def __repr__(self) -> str: ...
+
+KW_ONLY: _KW_ONLY_TYPE
 # Stub Only
-_codegen_type = Callable[[type], tuple[str, dict[str, typing.Any]]]
+_codegen_type = Callable[[type], GeneratedCode]
+
+class GeneratedCode:
+    __slots__: tuple[str, str]
+    source_code: str
+    globs: dict[str, typing.Any]
+
+    def __init__(self, source_code: str, globs: dict[str, typing.Any]) -> None: ...
+    def __repr__(self) -> str: ...
+
 
 class MethodMaker:
     funcname: str
     code_generator: _codegen_type
     def __init__(self, funcname: str, code_generator: _codegen_type) -> None: ...
     def __repr__(self) -> str: ...
-    def __get__(self, instance, cls) -> Callable: ...
+    def __get__(self, instance, cls=None) -> Callable: ...
 
 def get_init_generator(
     null: _NothingType = NOTHING,
     extra_code: None | list[str] = None
-) -> Callable[[type], tuple[str, dict[str, typing.Any]]]: ...
+) -> Callable[[type], GeneratedCode]: ...
+
+def init_generator(cls: type) -> GeneratedCode: ...
 
-def init_generator(cls: type) -> tuple[str, dict[str, typing.Any]]: ...
-def repr_generator(cls: type) -> tuple[str, dict[str, typing.Any]]: ...
-def eq_generator(cls: type) -> tuple[str, dict[str, typing.Any]]: ...
+def get_repr_generator(
+    recursion_safe: bool = False,
+    eval_safe: bool = False
+) -> Callable[[type], GeneratedCode]: ...
+def repr_generator(cls: type) -> GeneratedCode: ...
+def eq_generator(cls: type) -> GeneratedCode: ...
 
-def frozen_setattr_generator(cls: type) -> tuple[str, dict[str, typing.Any]]: ...
+def frozen_setattr_generator(cls: type) -> GeneratedCode: ...
 
-def frozen_delattr_generator(cls: type) -> tuple[str, dict[str, typing.Any]]: ...
+def frozen_delattr_generator(cls: type) -> GeneratedCode: ...
 
 init_maker: MethodMaker
 repr_maker: MethodMaker
@@ -69,12 +96,32 @@ def builder(
 ) -> Callable[[type[_T]], type[_T]]: ...
 
 
-class Field:
+class SlotFields(dict):
+    ...
+
+
+class SlotMakerMeta(type):
+    def __new__(
+        cls: type[_T],
+        name: str,
+        bases: tuple[type, ...],
+        ns: dict[str, typing.Any],
+        slots: bool = True,
+        **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
 
     def __init__(
@@ -84,7 +131,13 @@ class Field:
         default_factory: _NothingType | typing.Any = NOTHING,
         type: _NothingType | _py_type = NOTHING,
         doc: None | str = None,
+        init: bool = True,
+        repr: bool = True,
+        compare: bool = True,
+        kw_only: bool = False,
     ) -> None: ...
+
+    def __init_subclass__(cls, frozen: bool = False): ...
     def __repr__(self) -> str: ...
     def __eq__(self, other: Field | object) -> bool: ...
     def validate_field(self) -> None: ...
@@ -92,24 +145,64 @@ class Field:
     def from_field(cls, fld: Field, /, **kwargs: typing.Any) -> Field: ...
 
 
-class SlotFields(dict):
-    ...
+# 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[Field] = Field
-) -> Callable[[type], tuple[dict[str, Field], dict[str, typing.Any]]]: ...
+    field_type: type[_FieldType]
+) -> Callable[[type | _CopiableMappings], tuple[dict[str, _FieldType], dict[str, typing.Any]]]: ...
 
-def slot_gatherer(cls: type) -> tuple[dict[str, Field], 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]]]: ...
 
-def is_classvar(hint: object) -> bool: ...
+@typing.overload
+def make_annotation_gatherer(
+    field_type: type[_FieldType],
+    leave_default_values: bool = True,
+) -> Callable[[type | _CopiableMappings], tuple[dict[str, _FieldType], dict[str, typing.Any]]]: ...
 
+@typing.overload
 def make_annotation_gatherer(
-    field_type: type[Field] = Field,
+    field_type: _ReturnsField = Field,
+    leave_default_values: bool = True,
+) -> 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 = True,
-) -> Callable[[type], tuple[dict[str, Field], dict[str, typing.Any]]]: ...
+) -> 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 = True,
+) -> 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 = True,
+) -> Callable[[type | _CopiableMappings], tuple[dict[str, _FieldType], dict[str, typing.Any]]]: ...
+
+@typing.overload
+def make_unified_gatherer(
+    field_type: _ReturnsField = Field,
+    leave_default_values: bool = True,
+) -> 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) -> 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 annotation_gatherer(cls: type) -> tuple[dict[str, Field], dict[str, typing.Any]]: ...
 
 def check_argument_order(cls: type) -> None: ...
 
@@ -131,24 +224,35 @@ def slotclass(
     syntax_check: bool = True
 ) -> Callable[[type[_T]], type[_T]]: ...
 
-@typing.overload
-def annotationclass(
-    cls: type[_T],
-    /,
-    *,
-    methods: frozenset[MethodMaker] | set[MethodMaker] = default_methods,
-) -> type[_T]: ...
 
-@typing.overload
-def annotationclass(
-        cls: None = None,
-        /,
-        *,
+_gatherer_type = Callable[[type | _CopiableMappings], tuple[dict[str, Field], dict[str, typing.Any]]]
+
+
+@dataclass_transform(field_specifiers=(Field,))
+class AnnotationClass(metaclass=SlotMakerMeta):
+    __slots__: dict
+
+    def __init_subclass__(
+        cls,
         methods: frozenset[MethodMaker] | set[MethodMaker] = default_methods,
-) -> Callable[[type[_T]], type[_T]]: ...
+        gatherer: _gatherer_type = make_unified_gatherer(leave_default_values=True),
+        **kwargs,
+    ) -> None: ...
 
-@typing.overload
-def fieldclass(cls: type[_T], /, *, frozen: bool = False) -> type[_T]: ...
+class GatheredFields:
+    __slots__: dict[str, None]
 
-@typing.overload
-def fieldclass(cls: None = None, /, *, frozen: bool = False) -> Callable[[type[_T]], type[_T]]: ...
+    fields: dict[str, Field]
+    modifications: dict[str, typing.Any]
+
+    __classbuilder_internals__: dict
+
+    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: type) -> tuple[dict[str, Field], dict[str, typing.Any]]: ...

ducktools/classbuilder/annotations.py

@@ -0,0 +1,173 @@
+# 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
+import builtins
+
+
+class _StringGlobs(dict):
+    """
+    Based on the fake globals dictionary used for annotations
+    from 3.14. This allows us to evaluate containers which
+    include forward references.
+
+    It's just a dictionary that returns the key if the key
+    is not found.
+    """
+    def __missing__(self, key):
+        return key
+
+    def __repr__(self):
+        cls_name = self.__class__.__name__
+        dict_repr = super().__repr__()
+        return f"{cls_name}({dict_repr})"
+
+
+def eval_hint(hint, context=None, *, recursion_limit=2):
+    """
+    Attempt to evaluate a string type hint in the given
+    context.
+
+    If this raises an exception, return the last string.
+
+    If the recursion limit is hit or a previous value returns
+    on evaluation, return the original hint string.
+
+    Example::
+        import builtins
+        from typing import ClassVar
+
+        from ducktools.classbuilder.annotations import eval_hint
+
+        foo = "foo"
+
+        context = {**vars(builtins), **globals(), **locals()}
+        eval_hint("foo", context)  # returns 'foo'
+
+        eval_hint("ClassVar[str]", context)  # returns typing.ClassVar[str]
+        eval_hint("ClassVar[forwardref]", context)  # returns typing.ClassVar[ForwardRef('forwardref')]
+
+    :param hint: The existing type hint
+    :param context: merged context
+    :param recursion_limit: maximum number of evaluation loops before
+                            returning the original string.
+    :return: evaluated hint, or string if it could not evaluate
+    """
+    if context is not None:
+        context = _StringGlobs(context)
+
+    original_hint = hint
+
+    # Using a set would require the hint always be hashable
+    # This is only going to be 2 items at most usually
+    seen = []
+    i = 0
+    while isinstance(hint, str):
+        seen.append(hint)
+
+        # noinspection PyBroadException
+        try:
+            hint = eval(hint, context)
+        except Exception:
+            break
+
+        if hint in seen or i >= recursion_limit:
+            hint = original_hint
+            break
+
+        i += 1
+
+    return hint
+
+
+def get_ns_annotations(ns, eval_str=True):
+    """
+    Given a class namespace, attempt to retrieve the
+    annotations dictionary and evaluate strings.
+
+    Note: This only evaluates in the context of module level globals
+    and values in the class namespace. Non-local variables will not
+    be evaluated.
+
+    :param ns: Class namespace (eg cls.__dict__)
+    :param eval_str: Attempt to evaluate string annotations (default to True)
+    :return: dictionary of evaluated annotations
+    """
+    raw_annotations = ns.get("__annotations__", {})
+
+    if not eval_str:
+        return raw_annotations.copy()
+
+    try:
+        obj_modulename = ns["__module__"]
+    except KeyError:
+        obj_module = None
+    else:
+        obj_module = sys.modules.get(obj_modulename, None)
+
+    if obj_module:
+        obj_globals = vars(obj_module)
+    else:
+        obj_globals = {}
+
+    # Type parameters should be usable in hints without breaking
+    # This is for Python 3.12+
+    type_params = {
+        repr(param): param
+        for param in ns.get("__type_params__", ())
+    }
+
+    context = {**vars(builtins), **obj_globals, **type_params, **ns}
+
+    return {
+        k: eval_hint(v, context)
+        for k, v in raw_annotations.items()
+    }
+
+
+def is_classvar(hint):
+    _typing = sys.modules.get("typing")
+    if _typing:
+        # Annotated is a nightmare I'm never waking up from
+        # 3.8 and 3.9 need Annotated from typing_extensions
+        # 3.8 also needs get_origin from typing_extensions
+        if sys.version_info < (3, 10):
+            _typing_extensions = sys.modules.get("typing_extensions")
+            if _typing_extensions:
+                _Annotated = _typing_extensions.Annotated
+                _get_origin = _typing_extensions.get_origin
+            else:
+                _Annotated, _get_origin = None, None
+        else:
+            _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.pyi

@@ -0,0 +1,26 @@
+import typing
+import types
+
+_T = typing.TypeVar("_T")
+_CopiableMappings = dict[str, typing.Any] | types.MappingProxyType[str, typing.Any]
+
+class _StringGlobs:
+    def __missing__(self, key: _T) -> _T: ...
+
+
+def eval_hint(
+    hint: type | str,
+    context: None | dict[str, typing.Any] = None,
+    *,
+    recursion_limit: int = 2
+) -> type | str: ...
+
+
+def get_ns_annotations(
+    ns: _CopiableMappings,
+    eval_str: bool = True,
+) -> dict[str, typing.Any]: ...
+
+def is_classvar(
+    hint: object,
+) -> bool: ...