ducktools-classbuilder 0.3.0__tar.gz → 0.4.0__tar.gz

{ducktools_classbuilder-0.3.0/src/ducktools_classbuilder.egg-info → ducktools_classbuilder-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: ducktools-classbuilder
-Version: 0.3.0
+Version: 0.4.0
 Summary: Toolkit for creating class boilerplate generators
 Author: David C Ellis
 License: MIT License
@@ -41,6 +41,7 @@ Provides-Extra: testing
 Requires-Dist: pytest; extra == "testing"
 Requires-Dist: pytest-cov; extra == "testing"
 Requires-Dist: mypy; extra == "testing"
+Requires-Dist: typing_extensions; python_version < "3.10" and extra == "testing"
 Provides-Extra: docs
 Requires-Dist: sphinx; extra == "docs"
 Requires-Dist: myst-parser; extra == "docs"
@@ -121,7 +122,7 @@ a similar manner to the `@dataclass` decorator from `dataclasses`.
 > be used directly. (The included version has some extra features).
 
 ```python
-from ducktools.classbuilder import Field, SlotFields
+from ducktools.classbuilder import Field, SlotFields, slotclass
 
 @slotclass
 class SlottedDC:
@@ -206,6 +207,25 @@ print(f"{DataCoords is class_register[DataCoords.__name__] = }")
 print(f"{SlotCoords is class_register[SlotCoords.__name__] = }")
 ```
 
+## Using annotations anyway ##
+
+For those that really want to use type annotations a basic `annotation_gatherer`
+function and `@annotationclass` decorator are also included. Slots are not generated
+in this case.
+
+```python
+from ducktools.classbuilder import annotationclass
+
+@annotationclass
+class AnnotatedDC:
+    the_answer: int = 42
+    the_question: str = "What do you get if you multiply six by nine?"
+
+    
+ex = AnnotatedDC()
+print(ex)
+```
+
 ## What features does this have? ##
 
 Included as an example implementation, the `slotclass` generator supports 
@@ -218,6 +238,10 @@ It will copy values provided as the `type` to `Field` into the
 Values provided to `doc` will be placed in the final `__slots__` 
 field so they are present on the class if `help(...)` is called.
 
+A fairly basic `annotations_gatherer` and `annotationclass` are included
+in `extras.py` which can be used to generate classbuilders that rely on 
+annotations.
+
 If you want something with more features you can look at the `prefab.py`
 implementation which provides a 'prebuilt' implementation.
 

{ducktools_classbuilder-0.3.0 → ducktools_classbuilder-0.4.0}/README.md

@@ -73,7 +73,7 @@ a similar manner to the `@dataclass` decorator from `dataclasses`.
 > be used directly. (The included version has some extra features).
 
 ```python
-from ducktools.classbuilder import Field, SlotFields
+from ducktools.classbuilder import Field, SlotFields, slotclass
 
 @slotclass
 class SlottedDC:
@@ -158,6 +158,25 @@ print(f"{DataCoords is class_register[DataCoords.__name__] = }")
 print(f"{SlotCoords is class_register[SlotCoords.__name__] = }")
 ```
 
+## Using annotations anyway ##
+
+For those that really want to use type annotations a basic `annotation_gatherer`
+function and `@annotationclass` decorator are also included. Slots are not generated
+in this case.
+
+```python
+from ducktools.classbuilder import annotationclass
+
+@annotationclass
+class AnnotatedDC:
+    the_answer: int = 42
+    the_question: str = "What do you get if you multiply six by nine?"
+
+    
+ex = AnnotatedDC()
+print(ex)
+```
+
 ## What features does this have? ##
 
 Included as an example implementation, the `slotclass` generator supports 
@@ -170,6 +189,10 @@ It will copy values provided as the `type` to `Field` into the
 Values provided to `doc` will be placed in the final `__slots__` 
 field so they are present on the class if `help(...)` is called.
 
+A fairly basic `annotations_gatherer` and `annotationclass` are included
+in `extras.py` which can be used to generate classbuilders that rely on 
+annotations.
+
 If you want something with more features you can look at the `prefab.py`
 implementation which provides a 'prebuilt' implementation.
 

{ducktools_classbuilder-0.3.0 → ducktools_classbuilder-0.4.0}/docs/extension_examples.md

@@ -156,6 +156,9 @@ how to perform the generation. A convenient decorator `@fieldclass` is provided
 to allow simple extension by adding additional slots. By using this decorator
 the `__init__`, `__repr__` and `__eq__` methods will be generated for you.
 
+> Note: Field classes will be frozen when running under pytest.
+>       They are not frozen normally for performance reasons.
+
 ```python
 from ducktools.classbuilder import Field, SlotFields, fieldclass
 
@@ -184,102 +187,26 @@ along with a 'globals' dictionary of any names the code needs to refer
 to, or an empty dictionary if none are needed. Many methods don't require
 any globals values, but it is essential for some.
 
-#### Iterable Classes ####
-
-Say you want to make the class iterable, so you want to add `__iter__`.
-
-```python
-from ducktools.classbuilder import (
-    default_methods, get_fields, slotclass, MethodMaker, SlotFields
-)
-
-
-def iter_maker(cls):
-    field_names = get_fields(cls).keys()
-    field_yield = "\n".join(f"    yield self.{f}" for f in field_names)
-    code = (
-        f"def __iter__(self):\n"
-        f"{field_yield}"
-    )
-    globs = {}
-    return code, globs
-
-
-iter_desc = MethodMaker("__iter__", iter_maker)
-new_methods = frozenset(default_methods | {iter_desc})
-
-
-def iterclass(cls=None, /):
-    return slotclass(cls, methods=new_methods)
-
-
-if __name__ == "__main__":
-    @iterclass
-    class IterDemo:
-        __slots__ = SlotFields(
-            a=1,
-            b=2,
-            c=3,
-            d=4,
-            e=5,
-        )
-
-
-    ex = IterDemo()
-    print([item for item in ex])
-```
-
-You could also choose to yield tuples of `name, value` pairs in your implementation.
-
 #### Frozen Classes ####
 
-Here's an example of frozen slotted classes that only allow assignment once
-(which happens in the `__init__` method generated).
+In order to make frozen classes you need to replace `__setattr__` and `__delattr__`
+
+The building blocks for this are actually already included as they're used to prevent 
+`fieldclass` instances from being mutated.
 
-> Note that these methods use `type(self).__name__` instead of `cls.__name__`
-> when generated so the name remains correct even if the class name is changed.
+These methods can be reused to make `slotclasses` 'frozen'.
 
 ```python
 from ducktools.classbuilder import (
     slotclass,
-    get_fields,
     SlotFields,
-    MethodMaker,
     default_methods,
+    frozen_setattr_desc,
+    frozen_delattr_desc,
 )
 
 
-def setattr_maker(cls):
-    globs = {
-        "object_setattr": object.__setattr__
-    }
-
-    field_names = set(get_fields(cls).keys())
-
-    code = (
-        f"def __setattr__(self, name, value):\n"
-        f"    fields = {field_names!r}\n"
-        f"    if name in fields and not hasattr(self, name):\n"
-        f"        object_setattr(self, name, value)\n"
-        f"    else:\n"
-        f'        raise TypeError(f"{{type(self).__name__!r}} object does not support attribute assignment")'
-    )
-    return code, globs
-
-
-def delattr_maker(cls):
-    code = (
-        f"def __delattr__(self, name):\n"
-        f'    raise TypeError(f"{{type(self).__name__!r}} object does not support attribute deletion")'
-    )
-    globs = {}
-    return code, globs
-
-
-setattr_desc = MethodMaker("__setattr__", setattr_maker)
-delattr_desc = MethodMaker("__delattr__", delattr_maker)
-
-new_methods = frozenset(default_methods | {setattr_desc, delattr_desc})
+new_methods = default_methods | {frozen_setattr_desc, frozen_delattr_desc}
 
 
 def frozen(cls, /):
@@ -315,6 +242,53 @@ if __name__ == "__main__":
         print(e)
 ```
 
+#### Iterable Classes ####
+
+Say you want to make the class iterable, so you want to add `__iter__`.
+
+```python
+from ducktools.classbuilder import (
+    default_methods, get_fields, slotclass, MethodMaker, SlotFields
+)
+
+
+def iter_maker(cls):
+    field_names = get_fields(cls).keys()
+    field_yield = "\n".join(f"    yield self.{f}" for f in field_names)
+    code = (
+        f"def __iter__(self):\n"
+        f"{field_yield}"
+    )
+    globs = {}
+    return code, globs
+
+
+iter_desc = MethodMaker("__iter__", iter_maker)
+new_methods = frozenset(default_methods | {iter_desc})
+
+
+def iterclass(cls=None, /):
+    return slotclass(cls, methods=new_methods)
+
+
+if __name__ == "__main__":
+    @iterclass
+    class IterDemo:
+        __slots__ = SlotFields(
+            a=1,
+            b=2,
+            c=3,
+            d=4,
+            e=5,
+        )
+
+
+    ex = IterDemo()
+    print([item for item in ex])
+```
+
+You could also choose to yield tuples of `name, value` pairs in your implementation.
+
 ### Extending Field ###
 
 #### Excluding Attributes ####
@@ -605,93 +579,15 @@ if __name__ == "__main__":
 ```
 
 ### Gatherers ###
-#### Using type hints/annotations instead of slots? ####
-
-Have you heard of [dataclasses](https://docs.python.org/3/library/dataclasses.html)?
-
-But we can also do that. These classes will not be slotted, however, 
-due to the issues mentioned in the readme.
-
-```python
-import sys
-from ducktools.classbuilder import builder, default_methods, Field, NOTHING
-
-
-def _is_classvar(hint):
-    # Avoid importing typing if it's not already used
-    _typing = sys.modules.get("typing")
-    if _typing:
-        if (
-            hint is _typing.ClassVar
-            or getattr(hint, "__origin__", None) is _typing.ClassVar
-        ):
-            return True
-        # String used as annotation
-        elif isinstance(hint, str) and "ClassVar" in hint:
-            return True
-    return False
-
-
-def annotation_gatherer(cls):
-    cls_annotations = cls.__dict__.get("__annotations__", {})
-    cls_fields = {}
-
-    for k, v in cls_annotations.items():
-        # Ignore ClassVar
-        if _is_classvar(v):
-            continue
-
-        attrib = getattr(cls, k, NOTHING)
-
-        if attrib is not NOTHING:
-            if isinstance(attrib, Field):
-                attrib.type = v
-            else:
-                attrib = Field(default=attrib)
-
-            # Remove the class variable
-            delattr(cls, k)
-
-        else:
-            attrib = Field()
-
-        cls_fields[k] = attrib
-
-    return cls_fields
-
-
-def annotation_class(cls=None, /, *, methods=default_methods):
-    return builder(cls, gatherer=annotation_gatherer, methods=methods)
-
-
-if __name__ == "__main__":
-    import typing
-
-    @annotation_class
-    class H2G2:
-        the_answer: int = 42
-        the_question: str = Field(
-            default="What do you get if you multiply six by nine?",
-        )
-        the_book: typing.ClassVar[str] = "The Hitchhiker's Guide to the Galaxy"
-        the_author: "typing.ClassVar[str]" = "Douglas Adams"
-
-    ex = H2G2()
-    print(ex)
-    ex2 = H2G2(
-        the_question="What is the ultimate answer to the meaning of life, the universe, and everything?"
-    )
-    print(ex2)
-
-    print(H2G2.the_book)
-    print(H2G2.the_author)
-```
-
 #### What about using annotations instead of `Field(init=False, ...)` ####
 
 This seems to be a feature people keep requesting for `dataclasses`.
 This is also doable.
 
+> Note: Field classes will be frozen when running under pytest.
+>       They should not be mutated by gatherers.
+>       If you need to change the value of a field use Field.from_field(...) to make a new instance.
+
 ```python
 import inspect
 from pprint import pp

{ducktools_classbuilder-0.3.0 → ducktools_classbuilder-0.4.0}/docs/index.md

@@ -63,6 +63,27 @@ ex = SlottedDC()
 print(ex)
 ```
 
+## Annotation Class Usage ##
+
+> Annotation based classes via 'extras' are only supported on Python 3.10 or later!
+
+Building classes based on annotations requires the `extras` submodule.
+This is separate because it relies on `inspect` to simplify the implementation
+but is a slow import.
+
+```python
+from ducktools.classbuilder import annotationclass
+
+@annotationclass
+class AnnotatedDC:
+    the_answer: int = 42
+    the_question: str = "What do you get if you multiply six by nine?"
+
+    
+ex = AnnotatedDC()
+print(ex)
+```
+
 ## Indices and tables ##
 
 * {ref}`genindex`

ducktools_classbuilder-0.4.0/docs/perf/performance_tests.md

@@ -0,0 +1,66 @@
+# Performance tests #
+
+Rough specs: 2023 Windows 10 Desktop: Intel i5-13600KF, Crucial P3 1TB PCIe M.2 2280 SSD
+
+## Import Times ##
+
+| Command | Mean [ms] | Min [ms] | Max [ms] | Relative |
+|:---|---:|---:|---:|---:|
+| `python -c "pass"` | 23.2 ± 0.8 | 21.8 | 25.3 | 1.00 |
+| `python -c "from ducktools.classbuilder import slotclass"` | 23.4 ± 1.8 | 22.3 | 32.8 | 1.01 ± 0.09 |
+| `python -c "from ducktools.classbuilder.prefab import prefab"` | 23.7 ± 0.9 | 22.8 | 27.6 | 1.02 ± 0.05 |
+| `python -c "from collections import namedtuple"` | 24.2 ± 0.8 | 23.3 | 27.5 | 1.04 ± 0.05 |
+| `python -c "from typing import NamedTuple"` | 32.2 ± 0.8 | 30.7 | 35.7 | 1.39 ± 0.06 |
+| `python -c "from dataclasses import dataclass"` | 39.6 ± 1.1 | 37.9 | 43.2 | 1.70 ± 0.08 |
+| `python -c "from attrs import define"` | 54.0 ± 1.8 | 51.4 | 60.1 | 2.32 ± 0.11 |
+| `python -c "from pydantic import BaseModel"` | 70.2 ± 1.2 | 68.3 | 72.7 | 3.02 ± 0.12 |
+
+
+
+## Loading a module with 100 classes defined ##
+
+| Command | Mean [ms] | Min [ms] | Max [ms] | Relative |
+|:---|---:|---:|---:|---:|
+| `python -c "pass"` | 22.9 ± 0.4 | 21.8 | 23.6 | 1.00 |
+| `python hyperfine_importers/native_classes_timer.py` | 24.2 ± 0.7 | 22.8 | 26.6 | 1.06 ± 0.04 |
+| `python hyperfine_importers/slotclasses_timer.py` | 24.9 ± 0.7 | 23.8 | 27.7 | 1.09 ± 0.04 |
+| `python hyperfine_importers/prefab_timer.py` | 25.8 ± 0.5 | 24.8 | 27.2 | 1.13 ± 0.03 |
+| `python hyperfine_importers/prefab_slots_timer.py` | 25.9 ± 0.6 | 24.9 | 27.5 | 1.13 ± 0.03 |
+| `python hyperfine_importers/prefab_eval_timer.py` | 35.1 ± 0.6 | 34.0 | 36.4 | 1.53 ± 0.04 |
+| `python hyperfine_importers/namedtuples_timer.py` | 28.3 ± 0.4 | 27.5 | 29.0 | 1.24 ± 0.03 |
+| `python hyperfine_importers/typed_namedtuples_timer.py` | 39.1 ± 0.9 | 37.4 | 41.8 | 1.71 ± 0.05 |
+| `python hyperfine_importers/dataclasses_timer.py` | 61.1 ± 2.1 | 58.1 | 69.1 | 2.67 ± 0.11 |
+| `python hyperfine_importers/attrs_noslots_timer.py` | 88.9 ± 2.2 | 86.7 | 98.3 | 3.88 ± 0.12 |
+| `python hyperfine_importers/attrs_slots_timer.py` | 90.9 ± 1.4 | 88.9 | 94.2 | 3.97 ± 0.10 |
+| `python hyperfine_importers/pydantic_timer.py` | 172.4 ± 5.3 | 164.5 | 181.5 | 7.53 ± 0.27 |
+
+
+
+## Class Generation time without imports ##
+
+From `perf_profile.py`.
+
+```
+Python Version: 3.12.2 (tags/v3.12.2:6abddd9, Feb  6 2024, 21:26:36) [MSC v.1937 64 bit (AMD64)]
+Classbuilder version: v0.4.0
+Platform: Windows-10-10.0.19045-SP0
+Time for 100 imports of 100 classes defined with 5 basic attributes
+```
+
+| Method | Total Time (seconds) |
+| --- | --- |
+| standard classes | 0.07 |
+| namedtuple | 0.33 |
+| NamedTuple | 0.50 |
+| dataclasses | 2.05 |
+| attrs 23.2.0 | 3.73 |
+| pydantic 2.7.1 | 4.19 |
+| dabeaz/cluegen | 0.10 |
+| dabeaz/cluegen_eval | 0.91 |
+| dabeaz/dataklasses | 0.10 |
+| dabeaz/dataklasses_eval | 0.10 |
+| slotclass v0.4.0 | 0.12 |
+| prefab_slots v0.4.0 | 0.16 |
+| prefab v0.4.0 | 0.18 |
+| prefab_attributes v0.4.0 | 0.16 |
+| prefab_eval v0.4.0 | 1.12 |

{ducktools_classbuilder-0.3.0 → ducktools_classbuilder-0.4.0}/pyproject.toml

@@ -33,7 +33,7 @@ where = ["src"]
 version = {attr = "ducktools.classbuilder.__version__"}
 
 [project.optional-dependencies]
-testing = ["pytest", "pytest-cov", "mypy"]
+testing = ["pytest", "pytest-cov", "mypy", "typing_extensions; python_version < '3.10'"]
 docs = ["sphinx", "myst-parser", "sphinx_rtd_theme"]
 
 [project.urls]