ducktools-classbuilder 0.8.1__tar.gz → 0.8.2__tar.gz

{ducktools_classbuilder-0.8.1 → ducktools_classbuilder-0.8.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: ducktools-classbuilder
-Version: 0.8.1
+Version: 0.8.2
 Summary: Toolkit for creating class boilerplate generators
 Author: David C Ellis
 Project-URL: Homepage, https://github.com/davidcellis/ducktools-classbuilder

{ducktools_classbuilder-0.8.1 → ducktools_classbuilder-0.8.2}/docs/extension_examples.md

@@ -116,6 +116,25 @@ You could also choose to yield tuples of `name, value` pairs in your implementat
 
 ### Extending Field ###
 
+The `Field` class can also be extended as if it is a slotclass, with annotations or
+with `Field` declarations.
+
+One notable caveat - if you want to use a `default_factory` in extending `Field` you
+need to declare `default=FIELD_NOTHING` also in order for default to be ignored. This
+is a special case for `Field` and is not needed in general.
+
+```python
+from ducktools.classbuilder import Field, FIELD_NOTHING
+
+class MetadataField(Field):
+    metadata: dict = Field(default=FIELD_NOTHING, default_factory=dict)
+```
+
+In regular classes the `__init__` function generator considers `NOTHING` to be an 
+ignored value, but for `Field` subclasses it is a valid value so `FIELD_NOTHING` is
+the ignored term. This is all because `None` *is* a valid value and can't be used
+as a sentinel for Fields (otherwise `Field(default=None)` couldn't work).
+
 #### Positional Only Arguments? ####
 
 This is possible, but a little longer as we also need to modify multiple methods

{ducktools_classbuilder-0.8.1 → ducktools_classbuilder-0.8.2}/src/ducktools/classbuilder/__init__.py

@@ -99,11 +99,16 @@ def _get_inst_fields(inst):
 # As 'None' can be a meaningful value we need a sentinel value
 # to use to show no value has been provided.
 class _NothingType:
+    def __init__(self, custom=None):
+        self.custom = custom
     def __repr__(self):
+        if self.custom:
+            return f"<{self.custom} NOTHING OBJECT>"
         return "<NOTHING OBJECT>"
 
 
 NOTHING = _NothingType()
+FIELD_NOTHING = _NothingType("FIELD")
 
 
 # KW_ONLY sentinel 'type' to use to indicate all subsequent attributes are
@@ -432,11 +437,11 @@ frozen_setattr_maker = MethodMaker("__setattr__", frozen_setattr_generator)
 frozen_delattr_maker = MethodMaker("__delattr__", frozen_delattr_generator)
 default_methods = frozenset({init_maker, repr_maker, eq_maker})
 
-# Special `__init__` maker for 'Field' subclasses
+# Special `__init__` maker for 'Field' subclasses - needs its own NOTHING option
 _field_init_maker = MethodMaker(
     funcname="__init__",
     code_generator=get_init_generator(
-        null=_NothingType(),
+        null=FIELD_NOTHING,
         extra_code=["self.validate_field()"],
     )
 )
@@ -649,7 +654,7 @@ class Field(metaclass=SlotMakerMeta):
 
     def validate_field(self):
         cls_name = self.__class__.__name__
-        if self.default is not NOTHING and self.default_factory is not NOTHING:
+        if type(self.default) is not _NothingType and type(self.default_factory) is not _NothingType:
             raise AttributeError(
                 f"{cls_name} cannot define both a default value and a default factory."
             )
@@ -807,6 +812,7 @@ def make_annotation_gatherer(
 def make_field_gatherer(
     field_type=Field,
     leave_default_values=False,
+    assign_types=True,
 ):
     def field_attribute_gatherer(cls_or_ns):
         if isinstance(cls_or_ns, (_MappingProxyType, dict)):
@@ -819,7 +825,11 @@ def make_field_gatherer(
             for k, v in cls_dict.items()
             if isinstance(v, field_type)
         }
-        cls_annotations = get_ns_annotations(cls_dict)
+
+        if assign_types:
+            cls_annotations = get_ns_annotations(cls_dict)
+        else:
+            cls_annotations = {}
 
         cls_modifications = {}
 
@@ -830,7 +840,7 @@ def make_field_gatherer(
             else:
                 cls_modifications[name] = NOTHING
 
-            if (anno := cls_annotations.get(name, NOTHING)) is not NOTHING:
+            if assign_types and (anno := cls_annotations.get(name, NOTHING)) is not NOTHING:
                 cls_attributes[name] = field_type.from_field(attrib, type=anno)
 
         return cls_attributes, cls_modifications

{ducktools_classbuilder-0.8.1 → ducktools_classbuilder-0.8.2}/src/ducktools/classbuilder/__init__.pyi

@@ -24,8 +24,10 @@ def get_methods(cls: type) -> types.MappingProxyType[str, MethodMaker]: ...
 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
 
 # noinspection PyPep8Naming
 class _KW_ONLY_TYPE:
@@ -191,6 +193,7 @@ def make_annotation_gatherer(
 def make_field_gatherer(
     field_type: type[_FieldType],
     leave_default_values: bool = False,
+    assign_types: bool = True,
 ) -> Callable[[type | _CopiableMappings], tuple[dict[str, _FieldType], dict[str, typing.Any]]]: ...
 
 @typing.overload

ducktools_classbuilder-0.8.2/src/ducktools/classbuilder/_version.py

@@ -0,0 +1,2 @@
+__version__ = "0.8.2"
+__version_tuple__ = (0, 8, 2)

{ducktools_classbuilder-0.8.1 → ducktools_classbuilder-0.8.2}/src/ducktools/classbuilder/annotations.py

@@ -22,6 +22,44 @@
 import sys
 
 
+class _LazyAnnotationLib:
+    def __init__(self):
+        if sys.version_info < (3, 14):
+            self.annotationlib_unavailable = True
+        else:
+            self.annotationlib_unavailable = None
+
+    def __getattr__(self, item):
+        if self.annotationlib_unavailable:
+            raise ImportError("'annotationlib' is not available")
+
+        try:
+            import annotationlib
+        except ImportError:
+            self.annotationlib_unavailable = True
+            raise ImportError("'annotationlib' is not available")
+        else:
+            self.Format = annotationlib.Format
+            self.call_annotate_function = annotationlib.call_annotate_function
+
+            # This function keeps getting changed and renamed
+            get_ns_annotate = getattr(annotationlib, "get_annotate_from_class_namespace", None)
+            if get_ns_annotate is None:
+                get_ns_annotate = getattr(annotationlib, "get_annotate_function")
+            self.get_ns_annotate = get_ns_annotate
+
+            if item == "Format":
+                return self.Format
+            elif item == "call_annotate_function":
+                return self.call_annotate_function
+            elif item == "get_ns_annotate":
+                return get_ns_annotate
+
+        raise AttributeError(f"{item!r} is not available from this lazy importer")
+
+_lazy_annotationlib = _LazyAnnotationLib()
+
+
 def get_ns_annotations(ns):
     """
     Given a class namespace, attempt to retrieve the
@@ -35,19 +73,18 @@ def get_ns_annotations(ns):
     if annotations is not None:
         annotations = annotations.copy()
     else:
-        # See if we're using PEP-649 annotations
-        # Guarding this with a try/except instead of a version check
-        # In case there's a change and PEP-649 somehow doesn't make 3.14
         try:
-            from annotationlib import Format, call_annotate_function, get_annotate_function
-        except ImportError:
-            pass
-        else:
-            annotate = ns.get("__annotate__")  # Works in the alphas, but may break
+            # See if we're using PEP-649 annotations
+            annotate = ns.get("__annotate__")  # Works in the early alphas
             if not annotate:
-                annotate = get_annotate_function(ns)
+                annotate = _lazy_annotationlib.get_ns_annotate(ns)
             if annotate:
-                annotations = call_annotate_function(annotate, format=Format.FORWARDREF)
+                annotations = _lazy_annotationlib.call_annotate_function(
+                    annotate,
+                    format=_lazy_annotationlib.Format.FORWARDREF
+                )
+        except ImportError:
+            pass
 
     if annotations is None:
         annotations = {}

{ducktools_classbuilder-0.8.1 → ducktools_classbuilder-0.8.2}/src/ducktools/classbuilder/prefab.py

@@ -26,7 +26,7 @@ A 'prebuilt' implementation of class generation.
 Includes pre and post init functions along with other methods.
 """
 from . import (
-    INTERNALS_DICT, NOTHING,
+    INTERNALS_DICT, NOTHING, FIELD_NOTHING,
     Field, MethodMaker, GatheredFields, GeneratedCode, SlotMakerMeta,
     builder, get_flags, get_fields,
     make_unified_gatherer,
@@ -289,10 +289,12 @@ class Attribute(Field):
     :param kw_only: Make this argument keyword only in init
     :param serialize: Include this attribute in methods that serialize to dict
     :param doc: Parameter documentation for slotted classes
+    :param metadata: Additional non-construction related metadata
     :param type: Type of this attribute (for slotted classes)
     """
     iter: bool = True
     serialize: bool = True
+    metadata: dict = Field(default=FIELD_NOTHING, default_factory=dict)
 
 
 # noinspection PyShadowingBuiltins
@@ -309,6 +311,7 @@ def attribute(
     exclude_field=False,
     private=False,
     doc=None,
+    metadata=None,
     type=NOTHING,
 ):
     """
@@ -326,6 +329,7 @@ def attribute(
     :param exclude_field: Shorthand for setting repr, compare, iter and serialize to False
     :param private: Short for init, repr, compare, iter, serialize = False, must have default or factory
     :param doc: Parameter documentation for slotted classes
+    :param metadata: Dictionary for additional non-construction metadata
     :param type: Type of this attribute (for slotted classes)
 
     :return: Attribute generated with these parameters.
@@ -356,6 +360,7 @@ def attribute(
         serialize=serialize,
         doc=doc,
         type=type,
+        metadata=metadata,
     )
 
 

{ducktools_classbuilder-0.8.1 → ducktools_classbuilder-0.8.2}/src/ducktools/classbuilder/prefab.pyi

@@ -50,6 +50,7 @@ class Attribute(Field):
 
     iter: bool
     serialize: bool
+    metadata: dict
 
     def __init__(
         self,
@@ -64,6 +65,7 @@ class Attribute(Field):
         iter: bool = True,
         kw_only: bool = False,
         serialize: bool = True,
+        metadata: dict | None = None,
     ) -> None: ...
 
     def __repr__(self) -> str: ...
@@ -74,8 +76,6 @@ def attribute(
     *,
     default: typing.Any | _NothingType = NOTHING,
     default_factory: typing.Any | _NothingType = NOTHING,
-    type: type | _NothingType = NOTHING,
-    doc: str | None = None,
     init: bool = True,
     repr: bool = True,
     compare: bool = True,
@@ -84,6 +84,9 @@ def attribute(
     serialize: bool = True,
     exclude_field: bool = False,
     private: bool = False,
+    doc: str | None = None,
+    metadata: dict | None = None,
+    type: type | _NothingType = NOTHING,
 ) -> Attribute: ...
 
 def prefab_gatherer(cls_or_ns: type | MappingProxyType) -> tuple[dict[str, Attribute], dict[str, typing.Any]]: ...

{ducktools_classbuilder-0.8.1 → ducktools_classbuilder-0.8.2}/src/ducktools_classbuilder.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: ducktools-classbuilder
-Version: 0.8.1
+Version: 0.8.2
 Summary: Toolkit for creating class boilerplate generators
 Author: David C Ellis
 Project-URL: Homepage, https://github.com/davidcellis/ducktools-classbuilder

ducktools_classbuilder-0.8.1/src/ducktools/classbuilder/_version.py

@@ -1,2 +0,0 @@
-__version__ = "0.8.1"
-__version_tuple__ = (0, 8, 1)