ducktools-classbuilder 0.9.1__tar.gz → 0.10.0__tar.gz

{ducktools_classbuilder-0.9.1 → ducktools_classbuilder-0.10.0}/.github/workflows/auto_test.yml

@@ -14,7 +14,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest]
-        python-version: ["3.14-dev", "3.13", "3.12", "3.11", "pypy-3.11", "3.10", "3.9", "3.8"]
+        python-version: ["3.14-dev", "3.13", "3.12", "3.11", "pypy-3.11", "3.10"]
 
     steps:
     - uses: actions/checkout@v4
@@ -25,7 +25,7 @@ jobs:
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        python -m pip install -e .[testing]
+        python -m pip install -e . --group dev
     - name: Test with pytest
       run: |
         pytest tests/ --cov=src/ --cov-report=term-missing
@@ -35,14 +35,14 @@ jobs:
 
     steps:
       - uses: actions/checkout@v4
-      - name: Set up Python 3.8
+      - name: Set up Python 3.10
         uses: actions/setup-python@v5
         with:
-          python-version: "3.8"
+          python-version: "3.10"
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          python -m pip install -e .[testing,type_checking]
+          python -m pip install -e . --group dev
       - name: Check type stub files
         run: |
           python -m mypy.stubtest ducktools.classbuilder

{ducktools_classbuilder-0.9.1 → ducktools_classbuilder-0.10.0}/.github/workflows/publish_to_pypi.yml

@@ -14,7 +14,7 @@ jobs:
     - name: Set up Python
       uses: actions/setup-python@v5
       with:
-        python-version: "3.8"
+        python-version: "3.10"
     - name: Install pypa/build
       run: >-
         python3 -m
@@ -69,7 +69,7 @@ jobs:
         name: python-package-distributions
         path: dist/
     - name: Sign the dists with Sigstore
-      uses: sigstore/gh-action-sigstore-python@v3.0.0
+      uses: sigstore/gh-action-sigstore-python@v3.0.1
       with:
         release-signing-artifacts: false
         inputs: >-

{ducktools_classbuilder-0.9.1 → ducktools_classbuilder-0.10.0}/.github/workflows/publish_to_testpypi.yml

@@ -15,7 +15,7 @@ jobs:
     - name: Set up Python
       uses: actions/setup-python@v5
       with:
-        python-version: "3.8"
+        python-version: "3.10"
     - name: Install pypa/build
       run: >-
         python3 -m
@@ -52,4 +52,4 @@ jobs:
     - name: Publish distribution 📦 to TestPyPI
       uses: pypa/gh-action-pypi-publish@release/v1
       with:
-        repository-url: https://test.pypi.org/legacy/
+        repository-url: https://test.pypi.org/legacy/

{ducktools_classbuilder-0.9.1 → ducktools_classbuilder-0.10.0}/PKG-INFO

@@ -1,12 +1,10 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: ducktools-classbuilder
-Version: 0.9.1
+Version: 0.10.0
 Summary: Toolkit for creating class boilerplate generators
 Author: David C Ellis
 Project-URL: Homepage, https://github.com/davidcellis/ducktools-classbuilder
 Classifier: Development Status :: 4 - Beta
-Classifier: Programming Language :: Python :: 3.8
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
@@ -14,22 +12,14 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Operating System :: OS Independent
 Classifier: License :: OSI Approved :: MIT License
-Requires-Python: >=3.8
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Provides-Extra: testing
-Requires-Dist: pytest>=8.2; extra == "testing"
-Requires-Dist: pytest-cov; extra == "testing"
-Requires-Dist: typing_extensions; extra == "testing"
-Provides-Extra: type-checking
-Requires-Dist: mypy; extra == "type-checking"
-Provides-Extra: performance-tests
-Requires-Dist: attrs; extra == "performance-tests"
-Requires-Dist: pydantic; extra == "performance-tests"
 Provides-Extra: docs
-Requires-Dist: sphinx; extra == "docs"
-Requires-Dist: myst-parser; extra == "docs"
-Requires-Dist: sphinx_rtd_theme; extra == "docs"
+Requires-Dist: sphinx>=8.1; extra == "docs"
+Requires-Dist: myst-parser>=4.0; extra == "docs"
+Requires-Dist: sphinx_rtd_theme>=3.0; extra == "docs"
+Dynamic: license-file
 
 # Ducktools: Class Builder #
 

{ducktools_classbuilder-0.9.1 → ducktools_classbuilder-0.10.0}/docs/tutorial.md

@@ -191,14 +191,13 @@ def reportclass(cls):
 slot_gatherer = dtbuild.make_slot_gatherer(CustomField)
 
 
-class ReportClass(metaclass=dtbuild.SlotMakerMeta):
+class ReportClass(metaclass=dtbuild.SlotMakerMeta, gatherer=fields_attribute_gatherer):
     __slots__ = {}
-    _meta_gatherer = fields_attribute_gatherer
-
+    
     def __init_subclass__(cls):
-        # Check if the metaclass has generated slots
-        meta_slotted = '__slots__' in vars(cls) and isinstance(cls.__slots__, dtbuild.SlotFields)
-        gatherer = slot_gatherer if meta_slotted else fields_attribute_gatherer
+        # Check if the metaclass has pre-gathered data
+        pre_gathered = dtbuild.GATHERED_DATA in vars(cls)
+        gatherer = dtbuild.pre_gathered_gatherer if pre_gathered else fields_attribute_gatherer
         methods = {
             dtbuild.eq_maker,
             dtbuild.repr_maker,

{ducktools_classbuilder-0.9.1 → ducktools_classbuilder-0.10.0}/docs_code/docs_ex9_annotated.py

@@ -6,9 +6,10 @@ from ducktools.classbuilder import (
     default_methods,
     get_fields,
     get_methods,
-    slot_gatherer,
+    pre_gathered_gatherer,
     Field,
     SlotMakerMeta,
+    GATHERED_DATA,
     NOTHING,
 )
 
@@ -110,16 +111,15 @@ def annotatedclass(cls=None, *, kw_only=False):
 
 
 # As a base class with slots
-class AnnotatedClass(metaclass=SlotMakerMeta):
-    # This attribute tells the slotmaker to use this gatherer
-    _meta_gatherer = annotated_gatherer
-
+class AnnotatedClass(metaclass=SlotMakerMeta, gatherer=annotated_gatherer):
+    
     def __init_subclass__(cls, kw_only=False, **kwargs):
+        pre_gathered = GATHERED_DATA in cls.__dict__
         slots = "__slots__" in cls.__dict__
 
         # if slots is True then fields will already be present in __slots__
         # Use the slot_gatherer for this case
-        gatherer = slot_gatherer if slots else annotated_gatherer
+        gatherer = pre_gathered_gatherer if pre_gathered else annotated_gatherer
 
         builder(
             cls,
@@ -139,10 +139,10 @@ if __name__ == "__main__":
     class X:
         x: str
         y: ClassVar[str] = "This should be ignored"
-        z: Annotated[ClassVar[str], "Should be ignored"] = "This should also be ignored"
-        a: Annotated[int, NO_INIT] = "Not In __init__ signature"
+        z: Annotated[ClassVar[str], "Should be ignored"] = "This should also be ignored"  # type: ignore
+        a: Annotated[int, NO_INIT] = "Not In __init__ signature"  # type: ignore
         b: Annotated[str, NO_REPR] = "Not In Repr"
-        c: Annotated[list[str], NO_COMPARE] = Field(default_factory=list)
+        c: Annotated[list[str], NO_COMPARE] = Field(default_factory=list)  # type: ignore
         d: Annotated[str, IGNORE_ALL] = "Not Anywhere"
         e: Annotated[str, KW_ONLY, NO_COMPARE]
 
@@ -150,23 +150,23 @@ if __name__ == "__main__":
     class Y(AnnotatedClass):
         x: str
         y: ClassVar[str] = "This should be ignored"
-        z: Annotated[ClassVar[str], "Should be ignored"] = "This should also be ignored"
-        a: Annotated[int, NO_INIT] = "Not In __init__ signature"
+        z: Annotated[ClassVar[str], "Should be ignored"] = "This should also be ignored"  # type: ignore
+        a: Annotated[int, NO_INIT] = "Not In __init__ signature"  # type: ignore
         b: Annotated[str, NO_REPR] = "Not In Repr"
-        c: Annotated[list[str], NO_COMPARE] = Field(default_factory=list)
+        c: Annotated[list[str], NO_COMPARE] = Field(default_factory=list)  # type: ignore
         d: Annotated[str, IGNORE_ALL] = "Not Anywhere"
         e: Annotated[str, KW_ONLY, NO_COMPARE]
 
 
     # Unslotted Demo
-    ex = X("Value of x", e="Value of e")
+    ex = X("Value of x", e="Value of e")  # type: ignore
     print(ex, "\n")
 
     pp(get_fields(X))
     print("\n")
 
     # Slotted Demo
-    ex = Y("Value of x", e="Value of e")
+    ex = Y("Value of x", e="Value of e")  # type: ignore
     print(ex, "\n")
 
     print(f"Slots: {Y.__dict__.get('__slots__')}")

{ducktools_classbuilder-0.9.1 → ducktools_classbuilder-0.10.0}/docs_code/tutorial_code.py

@@ -115,14 +115,13 @@ def reportclass(cls):
 slot_gatherer = dtbuild.make_slot_gatherer(CustomField)
 
 
-class ReportClass(metaclass=dtbuild.SlotMakerMeta):
+class ReportClass(metaclass=dtbuild.SlotMakerMeta, gatherer=fields_attribute_gatherer):
     __slots__ = {}
-    _meta_gatherer = fields_attribute_gatherer
-
+    
     def __init_subclass__(cls):
-        # Check if the metaclass has generated slots
-        meta_slotted = '__slots__' in vars(cls) and isinstance(cls.__slots__, dtbuild.SlotFields)
-        gatherer = slot_gatherer if meta_slotted else fields_attribute_gatherer
+        # Check if the metaclass has pre-gathered data
+        pre_gathered = dtbuild.GATHERED_DATA in vars(cls)
+        gatherer = dtbuild.pre_gathered_gatherer if pre_gathered else fields_attribute_gatherer
         methods = {
             dtbuild.eq_maker,
             dtbuild.repr_maker,
@@ -130,7 +129,6 @@ class ReportClass(metaclass=dtbuild.SlotMakerMeta):
             report_maker
         }
 
-        # The class may still have slots unrelated to code generation
         slotted = "__slots__" in vars(cls)
         flags = {"slotted": slotted}
 

{ducktools_classbuilder-0.9.1 → ducktools_classbuilder-0.10.0}/pyproject.toml

@@ -12,11 +12,9 @@ authors = [
   { name="David C Ellis" },
 ]
 readme="README.md"
-requires-python = ">=3.8"
+requires-python = ">=3.10"
 classifiers = [
     "Development Status :: 4 - Beta",
-    "Programming Language :: Python :: 3.8",
-    "Programming Language :: Python :: 3.9",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
@@ -28,10 +26,23 @@ classifiers = [
 dynamic = ['version']
 
 [project.optional-dependencies]
-testing = ["pytest>=8.2", "pytest-cov", "typing_extensions"]
-type_checking = ["mypy"]
-performance_tests = ["attrs", "pydantic"]
-docs = ["sphinx", "myst-parser", "sphinx_rtd_theme"]
+# Needed for the current readthedocs.yaml
+docs = [
+    "sphinx>=8.1", 
+    "myst-parser>=4.0", 
+    "sphinx_rtd_theme>=3.0",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.4",
+    "pytest-cov>=6.1",
+    "mypy>=1.16",
+]
+performance = [
+    "attrs>=25.0",
+    "pydantic>=2.11",
+]
 
 [tool.setuptools.packages.find]
 where = ["src"]
@@ -51,3 +62,8 @@ addopts= "--cov=src/ --cov-report=term-missing"
 testpaths = [
     "tests",
 ]
+
+[tool.mypy]
+# A combination of types in stubs and tests using dataclass syntax
+# means that there are a number of annotations in otherwise unannotated areas
+disable_error_code = ["annotation-unchecked"]

{ducktools_classbuilder-0.9.1 → ducktools_classbuilder-0.10.0}/src/ducktools/classbuilder/__init__.py

@@ -38,7 +38,7 @@ from ._version import __version__, __version_tuple__  # noqa: F401
 # Change this name if you make heavy modifications
 INTERNALS_DICT = "__classbuilder_internals__"
 META_GATHERER_NAME = "_meta_gatherer"
-
+GATHERED_DATA = "__classbuilder_gathered_fields__"
 
 # If testing, make Field classes frozen to make sure attributes are not
 # overwritten. When running this is a performance penalty so it is not required.
@@ -114,12 +114,16 @@ FIELD_NOTHING = _NothingType("FIELD")
 # KW_ONLY sentinel 'type' to use to indicate all subsequent attributes are
 # keyword only
 # noinspection PyPep8Naming
-class _KW_ONLY_TYPE:
+class _KW_ONLY_META(type):
     def __repr__(self):
-        return "<KW_ONLY Sentinel Object>"
+        return "<KW_ONLY Sentinel>"
 
 
-KW_ONLY = _KW_ONLY_TYPE()
+class KW_ONLY(metaclass=_KW_ONLY_META):
+    """
+    Sentinel Class to indicate that variables declared after
+    this sentinel are to be converted to KW_ONLY arguments.
+    """
 
 
 class GeneratedCode:
@@ -571,21 +575,25 @@ class SlotMakerMeta(type):
 
     Will not convert `ClassVar` hinted values.
     """
-    def __new__(cls, name, bases, ns, slots=True, **kwargs):
+    def __new__(cls, name, bases, ns, slots=True, gatherer=None, **kwargs):
         # This should only run if slots=True is declared
         # and __slots__ have not already been defined
-        if slots and "__slots__" not in ns:
+        if slots and "__slots__" not in ns:            
             # Check if a different gatherer has been set in any base classes
             # Default to unified gatherer
-            gatherer = ns.get(META_GATHERER_NAME, None)
-            if not gatherer:
-                for base in bases:
-                    if g := getattr(base, META_GATHERER_NAME, None):
-                        gatherer = g
-                        break
+            if gatherer is None:
+                gatherer = ns.get(META_GATHERER_NAME, None)
+                if not gatherer:
+                    for base in bases:
+                        if g := getattr(base, META_GATHERER_NAME, None):
+                            gatherer = g
+                            break
+
+                if not gatherer:
+                    gatherer = unified_gatherer
 
-            if not gatherer:
-                gatherer = unified_gatherer
+            # Set the gatherer in the namespace
+            ns[META_GATHERER_NAME] = gatherer
 
             # Obtain slots from annotations or attributes
             cls_fields, cls_modifications = gatherer(ns)
@@ -595,14 +603,54 @@ class SlotMakerMeta(type):
                 else:
                     ns[k] = v
 
+            slots = {}
+            fields = {}
+
+            for k, v in cls_fields.items():
+                slots[k] = v.doc
+                if k not in {"__weakref__", "__dict__"}:
+                    fields[k] = v
+
             # Place slots *after* everything else to be safe
-            ns["__slots__"] = SlotFields(cls_fields)
+            ns["__slots__"] = slots
+
+            # Place pre-gathered field data - modifications are already applied
+            modifications = {}
+            ns[GATHERED_DATA] = fields, modifications
+        
+        else:
+            if gatherer is not None:
+                ns[META_GATHERER_NAME] = gatherer
 
         new_cls = super().__new__(cls, name, bases, ns, **kwargs)
 
         return new_cls
 
 
+# This class is set up before fields as it will be used to generate the Fields
+# for Field itself so Field can have generated __eq__, __repr__ and other methods
+class GatheredFields:
+    """
+    Helper class to store gathered field data
+    """
+    __slots__ = ("fields", "modifications")
+
+    def __init__(self, fields, modifications):
+        self.fields = fields
+        self.modifications = modifications
+
+    def __eq__(self, other):
+        if type(self) is type(other):
+            return self.fields == other.fields and self.modifications == other.modifications
+        
+    def __repr__(self):
+        return f"{type(self).__name__}(fields={self.fields!r}, modifications={self.modifications!r})"
+
+    def __call__(self, cls_dict):
+        # cls_dict will be provided, but isn't needed
+        return self.fields, self.modifications
+
+
 # The Field class can finally be defined.
 # The __init__ method has to be written manually so Fields can be created
 # However after this, the other methods can be generated.
@@ -628,17 +676,18 @@ class Field(metaclass=SlotMakerMeta):
     :param compare: Include in the class __eq__.
     :param kw_only: Make this a keyword only parameter in __init__.
     """
-    # If this base class did not define __slots__ the metaclass would break it.
-    # This will be replaced by the builder.
-    __slots__ = SlotFields(
-        default=NOTHING,
-        default_factory=NOTHING,
-        type=NOTHING,
-        doc=None,
-        init=True,
-        repr=True,
-        compare=True,
-        kw_only=False,
+
+    # Plain slots are required as part of bootstrapping
+    # This prevents SlotMakerMeta from trying to generate 'Field's
+    __slots__ = (
+        "default",
+        "default_factory",
+        "type",
+        "doc",
+        "init",
+        "repr",
+        "compare",
+        "kw_only",
     )
 
     # noinspection PyShadowingBuiltins
@@ -672,6 +721,7 @@ class Field(metaclass=SlotMakerMeta):
         self.validate_field()
 
     def __init_subclass__(cls, frozen=False):
+        # Subclasses of Field can be created as if they are dataclasses
         field_methods = {_field_init_maker, repr_maker, eq_maker}
         if frozen or _UNDER_TESTING:
             field_methods.update({frozen_setattr_maker, frozen_delattr_maker})
@@ -707,6 +757,66 @@ class Field(metaclass=SlotMakerMeta):
         return cls(**argument_dict)
 
 
+def _build_field():
+    # Complete the construction of the Field class
+    field_docs = {
+        "default": "Standard default value to be used for attributes with this field.",
+        "default_factory": 
+            "A zero-argument function to be called to generate a default value, "
+            "useful for mutable obects like lists.",
+        "type": "The type of the attribute to be assigned by this field.",
+        "doc": 
+            "The documentation for the attribute that appears when calling "
+            "help(...) on the class. (Only in slotted classes).",
+        "init": "Include this attribute in the class __init__ parameters.",
+        "repr": "Include this attribute in the class __repr__",
+        "compare": "Include this attribute in the class __eq__ method",
+        "kw_only": "Make this a keyword only parameter in __init__",
+    }
+
+    fields = {
+        "default": Field(default=NOTHING, doc=field_docs["default"]),
+        "default_factory": Field(default=NOTHING, doc=field_docs["default_factory"]),
+        "type": Field(default=NOTHING, doc=field_docs["type"]),
+        "doc": Field(default=None, doc=field_docs["doc"]),
+        "init": Field(default=True, doc=field_docs["init"]),
+        "repr": Field(default=True, doc=field_docs["repr"]),
+        "compare": Field(default=True, doc=field_docs["compare"]),
+        "kw_only": Field(default=False, doc=field_docs["kw_only"])
+    }
+    modifications = {"__slots__": field_docs}
+
+    field_methods = {repr_maker, eq_maker}
+    if _UNDER_TESTING:
+        field_methods.update({frozen_setattr_maker, frozen_delattr_maker})
+
+    builder(
+        Field,
+        gatherer=GatheredFields(fields, modifications),
+        methods=field_methods,
+        flags={"slotted": True, "kw_only": True},
+    )
+
+
+_build_field()
+del _build_field
+
+
+def pre_gathered_gatherer(cls_or_ns):
+    """
+    Retrieve fields previously gathered by SlotMakerMeta
+
+    :param cls_or_ns: Class to gather field information from (or class namespace)
+    :return: dict of field_name: Field(...) and modifications to be performed by the builder
+    """
+    if isinstance(cls_or_ns, (_MappingProxyType, dict)):
+        cls_dict = cls_or_ns
+    else:
+        cls_dict = cls_or_ns.__dict__
+    
+    return cls_dict[GATHERED_DATA]
+
+
 def make_slot_gatherer(field_type=Field):
     """
     Create a new annotation gatherer that will work with `Field` instances
@@ -721,7 +831,7 @@ def make_slot_gatherer(field_type=Field):
         Gather field information for class generation based on __slots__
 
         :param cls_or_ns: Class to gather field information from (or class namespace)
-        :return: dict of field_name: Field(...)
+        :return: dict of field_name: Field(...) and modifications to be performed by the builder
         """
         if isinstance(cls_or_ns, (_MappingProxyType, dict)):
             cls_dict = cls_or_ns
@@ -883,6 +993,7 @@ def make_field_gatherer(
 def make_unified_gatherer(
     field_type=Field,
     leave_default_values=False,
+    ignore_annotations=False,
 ):
     """
     Create a gatherer that will work via first slots, then
@@ -891,6 +1002,7 @@ def make_unified_gatherer(
 
     :param field_type: The field class to use for gathering
     :param leave_default_values: leave default values in place
+    :param ignore_annotations: don't attempt to read annotations
     :return: gatherer function
     """
     slot_g = make_slot_gatherer(field_type)
@@ -903,27 +1015,35 @@ def make_unified_gatherer(
         else:
             cls_dict = cls_or_ns.__dict__
 
+        cls_gathered = cls_dict.get(GATHERED_DATA)
+        if cls_gathered:
+            return pre_gathered_gatherer(cls_dict)
+
         cls_slots = cls_dict.get("__slots__")
 
         if isinstance(cls_slots, SlotFields):
             return slot_g(cls_dict)
 
-        # To choose between annotation and attribute gatherers
-        # compare sets of names.
-        # Don't bother evaluating string annotations, as we only need names
-        cls_annotations = get_ns_annotations(cls_dict)
-        cls_attributes = {
-            k: v for k, v in cls_dict.items() if isinstance(v, field_type)
-        }
+        if ignore_annotations:
+            return attrib_g(cls_dict)
+        else:
+            # To choose between annotation and attribute gatherers
+            # compare sets of names.
+            # Don't bother evaluating string annotations, as we only need names
+            cls_annotations = get_ns_annotations(cls_dict)
+            cls_attributes = {
+                k: v for k, v in cls_dict.items() if isinstance(v, field_type)
+            }
 
-        cls_annotation_names = cls_annotations.keys()
-        cls_attribute_names = cls_attributes.keys()
+            cls_annotation_names = cls_annotations.keys()
+            cls_attribute_names = cls_attributes.keys()
 
-        if set(cls_annotation_names).issuperset(set(cls_attribute_names)):
-            # All `Field` values have annotations, so use annotation gatherer
-            return anno_g(cls_dict)
+            if set(cls_annotation_names).issuperset(set(cls_attribute_names)):
+                # All `Field` values have annotations, so use annotation gatherer
+                return anno_g(cls_dict)
 
-        return attrib_g(cls_dict)
+            return attrib_g(cls_dict)
+        
     return field_unified_gatherer
 
 
@@ -935,19 +1055,6 @@ annotation_gatherer = make_annotation_gatherer()
 unified_gatherer = make_unified_gatherer()
 
 
-# Now the gatherers have been defined, add __repr__ and __eq__ to Field.
-_field_methods = {repr_maker, eq_maker}
-if _UNDER_TESTING:
-    _field_methods.update({frozen_setattr_maker, frozen_delattr_maker})
-
-builder(
-    Field,
-    gatherer=slot_gatherer,
-    methods=_field_methods,
-    flags={"slotted": True, "kw_only": True},
-)
-
-
 def check_argument_order(cls):
     """
     Raise a SyntaxError if the argument order will be invalid for a generated
@@ -990,17 +1097,3 @@ def slotclass(cls=None, /, *, methods=default_methods, syntax_check=True):
         check_argument_order(cls)
 
     return cls
-
-
-@slotclass
-class GatheredFields:
-    """
-    A helper gatherer for fields that have been gathered externally.
-    """
-    __slots__ = SlotFields(
-        fields=Field(),
-        modifications=Field(),
-    )
-
-    def __call__(self, cls):
-        return self.fields, self.modifications