ducktools-classbuilder 0.1.0__py3-none-any.whl → 0.1.1__py3-none-any.whl

ducktools/classbuilder/__init__.py

@@ -19,7 +19,7 @@
 # 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.
-__version__ = "v0.1.0"
+__version__ = "v0.1.1"
 
 # Change this name if you make heavy modifications
 INTERNALS_DICT = "__classbuilder_internals__"
@@ -415,4 +415,4 @@ def fieldclass(cls):
         methods=field_methods
     )
 
-    return cls
+    return cls

ducktools/classbuilder/__init__.pyi

@@ -1,6 +1,8 @@
 import typing
 from collections.abc import Callable
 
+_py_type = type  # Alias for type where it is used as a name
+
 __version__: str
 INTERNALS_DICT: str
 
@@ -38,14 +40,16 @@ repr_desc: MethodMaker
 eq_desc: MethodMaker
 default_methods: frozenset[MethodMaker]
 
+_T = typing.TypeVar("_T")
+
 @typing.overload
 def builder(
-    cls: type,
+    cls: type[_T],
     /,
     *,
     gatherer: Callable[[type], dict[str, Field]],
     methods: frozenset[MethodMaker] | set[MethodMaker]
-) -> typing.Any: ...
+) -> type[_T]: ...
 
 @typing.overload
 def builder(
@@ -54,35 +58,30 @@ def builder(
     *,
     gatherer: Callable[[type], dict[str, Field]],
     methods: frozenset[MethodMaker] | set[MethodMaker]
-) -> Callable[[type], type]: ...
-
+) -> Callable[[type[_T]], type[_T]]: ...
 
-_Self = typing.TypeVar("_Self", bound="Field")
 
 class Field:
     default: _NothingType | typing.Any
     default_factory: _NothingType | typing.Any
-    type: _NothingType | type
+    type: _NothingType | _py_type
     doc: None | str
 
+    __classbuilder_internals__: dict
+
     def __init__(
         self,
         *,
         default: _NothingType | typing.Any = NOTHING,
         default_factory: _NothingType | typing.Any = NOTHING,
-        type: _NothingType | type = NOTHING,
+        type: _NothingType | _py_type = NOTHING,
         doc: None | str = None,
     ) -> None: ...
-    @property
-    def _inherited_slots(self) -> list[str]: ...
     def __repr__(self) -> str: ...
-    @typing.overload
-    def __eq__(self, other: _Self) -> bool: ...
-    @typing.overload
-    def __eq__(self, other: object) -> NotImplemented: ...
+    def __eq__(self, other: Field | object) -> bool: ...
     def validate_field(self) -> None: ...
     @classmethod
-    def from_field(cls, fld: Field, **kwargs: typing.Any) -> _Self: ...
+    def from_field(cls, fld: Field, /, **kwargs: typing.Any) -> Field: ...
 
 
 class SlotFields(dict):
@@ -93,19 +92,20 @@ def slot_gatherer(cls: type) -> dict[str, Field]:
 
 @typing.overload
 def slotclass(
-    cls: type,
+    cls: type[_T],
     /,
     *,
     methods: frozenset[MethodMaker] | set[MethodMaker] = default_methods,
     syntax_check: bool = True
-) -> typing.Any: ...
+) -> type[_T]: ...
 
+@typing.overload
 def slotclass(
     cls: None = None,
     /,
     *,
     methods: frozenset[MethodMaker] | set[MethodMaker] = default_methods,
     syntax_check: bool = True
-) -> Callable[[type], type]: ...
+) -> Callable[[type[_T]], type[_T]]: ...
 
-def fieldclass(cls: type) -> typing.Any: ...
+def fieldclass(cls: type[_T]) -> type[_T]: ...

ducktools/classbuilder/prefab.py

@@ -319,12 +319,19 @@ def get_eq_maker():
 
 def get_iter_maker():
     def __iter__(cls: "type") -> "tuple[str, dict]":
-        field_names = get_attributes(cls).keys()
+        fields = get_attributes(cls)
 
-        if field_names:
-            values = "\n".join(f"    yield self.{name} " for name in field_names)
-        else:
+        valid_fields = (
+            name for name, attrib in fields.items()
+            if attrib.iter and not attrib.exclude_field
+        )
+
+        values = "\n".join(f"    yield self.{name}" for name in valid_fields)
+
+        # if values is an empty string
+        if not values:
             values = "    yield from ()"
+
         code = f"def __iter__(self):\n{values}"
         globs = {}
         return code, globs
@@ -366,6 +373,7 @@ def get_frozen_setattr_maker():
 
 
 def get_frozen_delattr_maker():
+    # noinspection PyUnusedLocal
     def __delattr__(cls: "type") -> "tuple[str, dict]":
         body = (
             '    raise TypeError(\n'
@@ -415,6 +423,7 @@ class Attribute(Field):
         init=True,
         repr=True,
         compare=True,
+        iter=True,
         kw_only=False,
         in_dict=True,
         exclude_field=False,
@@ -436,6 +445,7 @@ def attribute(
     init=True,
     repr=True,
     compare=True,
+    iter=True,
     kw_only=False,
     in_dict=True,
     exclude_field=False,
@@ -443,8 +453,7 @@ def attribute(
     type=NOTHING,
 ):
     """
-    Additional definition for how to generate standard methods
-    for an instance attribute.
+    Get an object to define a prefab Attribute
 
     :param default: Default value for this attribute
     :param default_factory: 0 argument callable to give a default value
@@ -452,6 +461,7 @@ def attribute(
     :param init: Include this attribute in the __init__ parameters
     :param repr: Include this attribute in the class __repr__
     :param compare: Include this attribute in the class __eq__
+    :param iter: Include this attribute in the class __iter__ if generated
     :param kw_only: Make this argument keyword only in init
     :param in_dict: Include this attribute in methods that serialise to dict
     :param exclude_field: Exclude this field from all magic method generation
@@ -469,6 +479,7 @@ def attribute(
         init=init,
         repr=repr,
         compare=compare,
+        iter=iter,
         kw_only=kw_only,
         in_dict=in_dict,
         exclude_field=exclude_field,
@@ -706,7 +717,7 @@ def _make_prefab(
         if attrib.exclude_field:
             if name not in post_init_args:
                 raise PrefabError(
-                    f"{name} is an excluded attribute but is not passed to post_init"
+                    f"{name!r} is an excluded attribute but is not passed to post_init"
                 )
         else:
             valid_args.append(name)

ducktools/classbuilder/prefab.pyi

@@ -1,4 +1,6 @@
 import typing
+from typing_extensions import dataclass_transform
+
 from collections.abc import Callable
 
 from . import (
@@ -7,6 +9,9 @@ from . import (
     builder, fieldclass, get_internals, slot_gatherer
 )
 
+# noinspection PyUnresolvedReferences
+from . import _NothingType
+
 PREFAB_FIELDS: str
 PREFAB_INIT_FUNC: str
 PRE_INIT_FUNC: str
@@ -56,6 +61,7 @@ class Attribute(Field):
     init: bool
     repr: bool
     compare: bool
+    iter: bool
     kw_only: bool
     in_dict: bool
     exclude_field: bool
@@ -63,34 +69,33 @@ class Attribute(Field):
     def __init__(
         self,
         *,
-        default: typing.Any | NOTHING =NOTHING,
-        default_factory: typing.Any | NOTHING = NOTHING,
-        type: type | NOTHING = NOTHING,
+        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,
+        iter: bool = True,
         kw_only: bool = False,
         in_dict: bool = True,
         exclude_field: bool = False,
     ) -> None: ...
 
     def __repr__(self) -> str: ...
-    @typing.overload
-    def __eq__(self, other: Attribute) -> bool: ...
-    def __eq__(self, other: object) -> NotImplemented: ...
-
+    def __eq__(self, other: Attribute | object) -> bool: ...
     def validate_field(self) -> None: ...
 
 def attribute(
     *,
-    default: typing.Any | NOTHING = NOTHING,
-    default_factory: typing.Any | NOTHING = NOTHING,
-    type: type | NOTHING = NOTHING,
+    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,
+    iter: bool = True,
     kw_only: bool = False,
     in_dict: bool = True,
     exclude_field: bool = False,
@@ -112,9 +117,14 @@ def _make_prefab(
     recursive_repr: bool = False,
 ) -> type: ...
 
-@typing.dataclass_transform
+_T = typing.TypeVar("_T")
+
+
+# For some reason PyCharm can't see 'attribute'?!?
+# noinspection PyUnresolvedReferences
+@dataclass_transform(field_specifiers=(Attribute, attribute))
 def prefab(
-    cls: type | None = None,
+    cls: type[_T] | None = None,
     *,
     init: bool = True,
     repr: bool = True,
@@ -125,7 +135,7 @@ def prefab(
     frozen: bool = False,
     dict_method: bool = False,
     recursive_repr: bool = False,
-) -> type | Callable[[type], type]: ...
+) -> type[_T] | Callable[[type[_T]], type[_T]]: ...
 
 def build_prefab(
     class_name: str,

{ducktools_classbuilder-0.1.0.dist-info → ducktools_classbuilder-0.1.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: ducktools-classbuilder
-Version: 0.1.0
+Version: 0.1.1
 Summary: Toolkit for creating class boilerplate generators
 Author: David C Ellis
 License: MIT License
@@ -44,6 +44,7 @@ Requires-Dist: sphinx-rtd-theme ; extra == 'docs'
 Provides-Extra: testing
 Requires-Dist: pytest ; extra == 'testing'
 Requires-Dist: pytest-cov ; extra == 'testing'
+Requires-Dist: mypy ; extra == 'testing'
 
 # Ducktools: Class Builder #
 
@@ -53,19 +54,74 @@ of writing... functions... that will bring back the **joy** of writing classes.
 Maybe.
 
 While `attrs` and `dataclasses` are class boilerplate generators, 
-`ducktools.classbuilder` is intended to be a dataclasses-like generator.
+`ducktools.classbuilder` is intended to be a `@dataclass`-like generator.
 The goal is to handle some of the basic functions and to allow for flexible
 customization of both the field collection and the method generation.
 
 `ducktools.classbuilder.prefab` includes a prebuilt implementation using these tools.
 
+Install from PyPI with:
+`python -m pip install ducktools-classbuilder`
+
+## Usage: building a class decorator ##
+
+In order to create a class decorator using `ducktools.classbuilder` there are
+a few things you need to prepare.
+
+1. A field gathering function to analyse the class and collect valid `Field`s.
+   * An example `slot_gatherer` is included.
+2. Code generators that can make use of the gathered `Field`s to create magic method
+   source code.
+   * Example `init_maker`, `repr_maker` and `eq_maker` generators are included.
+3. A function that calls the `builder` function to apply both of these steps.
+
+A field gathering function needs to take the original class as an argument and 
+return a dictionary of `{key: Field(...)}` pairs.
+
+> [!NOTE]
+> The `builder` will handle inheritance so do not collect fields from parent classes.
+
+The code generators take the class as the only argument and return a tuple 
+of method source code and globals to be provided to `exec(code, globs)` in order 
+to generate the actual method. 
+
+The provided `slot_gatherer` looks for `__slots__` being assigned a `SlotFields` 
+class[^1] where keyword arguments define the names and values for the fields. 
+
+Code generator functions need to be converted to descriptors before being used. 
+This is done using the provided `MethodMaker` descriptor class. 
+ex: `init_desc = MethodMaker("__init__", init_maker)`
+
+These parts can then be used to make a basic class boilerplate generator by 
+providing them to the `builder` function.
+
+```python
+from ducktools.classbuilder import (
+    builder, 
+    slot_gatherer, 
+    init_maker, eq_maker, repr_maker,
+    MethodMaker,
+)
+
+init_desc = MethodMaker("__init__", init_maker)
+repr_desc = MethodMaker("__repr__", repr_maker)
+eq_desc = MethodMaker("__eq__", eq_maker)
+
+def slotclass(cls):
+    return builder(cls, gatherer=slot_gatherer, methods={init_desc, repr_desc, eq_desc})
+```
+
 ## Slot Class Usage ##
 
-The building toolkit also includes a basic implementation that uses
-`__slots__` to define the fields by assigning a `SlotFields` instance.
+This created `slotclass` function can then be used as a decorator to generate classes in 
+a similar manner to the `@dataclass` decorator from `dataclasses`. 
+
+> [!NOTE] 
+> `ducktools.classbuilder` includes a premade version of `slotclass` that can
+> be used directly. (The included version has some extra features).
 
 ```python
-from ducktools.classbuilder import slotclass, Field, SlotFields
+from ducktools.classbuilder import Field, SlotFields
 
 @slotclass
 class SlottedDC:
@@ -81,28 +137,36 @@ ex = SlottedDC()
 print(ex)
 ```
 
-## Why does the basic implementation use slots? ##
+> [!TIP]
+> For more information and examples of creating class generators with additional 
+> features using the builder see 
+> [the docs](https://ducktools-classbuilder.readthedocs.io/en/latest/extension_examples.html)
+
+## Why does your example use `__slots__` instead of annotations? ##
 
-Dataclasses has a problem when you use `@dataclass(slots=True)`, 
-although this is not unique to dataclasses but inherent to the way both
-`__slots__` and decorators work.
+If you want to use `__slots__` in order to save memory you have to declare
+them when the class is originally created as you can't add them later.
 
-In order for this to *appear* to work, dataclasses has to make a new class 
-and attempt to copy over everything from the original. This is because 
-decorators operate on classes *after they have been created* while slots 
-need to be declared beforehand. While you can change the value of `__slots__` 
-after a class has been created, this will have no effect on the internal
-structure of the class.
+When you use `@dataclass(slots=True)`[^2] with `dataclasses` in order for 
+this to work, `dataclasses` has to make a new class and attempt to
+copy over everything from the original. 
+This is because decorators operate on classes *after they have been created* 
+while slots need to be declared beforehand. 
+While you can change the value of `__slots__` after a class has been created, 
+this will have no effect on the internal structure of the class.
 
 By declaring the class using `__slots__` on the other hand, we can take
 advantage of the fact that it accepts a mapping, where the keys will be
 used as the attributes to create as slots. The values can then be used as
-the default values equivalently to how type hints are used in dataclasses.
+the default values equivalently to how type hints are used in `dataclasses`.
 
-For example these two classes would be roughly equivalent, except 
+For example these two classes would be roughly equivalent, except that
 `@dataclass` has had to recreate the class from scratch while `@slotclass`
-has simply added the methods on to the original class. This is easy to 
-demonstrate using another decorator.
+has added the methods on to the original class. 
+This means that any references stored to the original class *before*
+`@dataclass` has rebuilt the class will not be pointing towards the 
+correct class. 
+This can be demonstrated using a simple class register decorator.
 
 > This example requires Python 3.10 as earlier versions of 
 > `dataclasses` did not support the `slots` argument.
@@ -140,7 +204,6 @@ print(SlotCoords())
 
 print(f"{DataCoords is class_register[DataCoords.__name__] = }")
 print(f"{SlotCoords is class_register[SlotCoords.__name__] = }")
-
 ```
 
 ## What features does this have? ##
@@ -158,9 +221,6 @@ field so they are present on the class if `help(...)` is called.
 If you want something with more features you can look at the `prefab.py`
 implementation which provides a 'prebuilt' implementation.
 
-For more information on creating class generators using the builder
-see [the docs](https://ducktools-classbuilder.readthedocs.io/en/latest/extension_examples.html)
-
 ## Will you add \<feature\> to `classbuilder.prefab`? ##
 
 No. Not unless it's something I need or find interesting.
@@ -177,3 +237,9 @@ with a specific feature, you can create or add it yourself.
 ## Credit ##
 
 Heavily inspired by [David Beazley's Cluegen](https://github.com/dabeaz/cluegen)
+
+[^1]: `SlotFields` is actually just a subclassed `dict` with no changes. `__slots__`
+      works with dictionaries using the values of the keys, while fields are normally
+      used for documentation.
+
+[^2]: or `@attrs.define`.

ducktools_classbuilder-0.1.1.dist-info/RECORD

@@ -0,0 +1,10 @@
+ducktools/classbuilder/__init__.py,sha256=EgrlCh0ue3DkIhafEC0YCanuCiE9t47XrIsk09GOUFk,12951
+ducktools/classbuilder/__init__.pyi,sha256=Oy2c-yBT3E7UNECjpeqmnv2VJdlgu_MfIDmdjJYXIFo,2744
+ducktools/classbuilder/prefab.py,sha256=KPovgZte2hfOuCOCZwQ5_3v9Y7O_vk2JpQTNG6EgJbE,29675
+ducktools/classbuilder/prefab.pyi,sha256=TIT9OxYJXPbqcAiUELaWoSNIQks4pbeQy9KWYphm1YA,3897
+ducktools/classbuilder/py.typed,sha256=la67KBlbjXN-_-DfGNcdOcjYumVpKG_Tkw-8n5dnGB4,8
+ducktools_classbuilder-0.1.1.dist-info/LICENSE.md,sha256=6Thz9Dbw8R4fWInl6sGl8Rj3UnKnRbDwrc6jZerpugQ,1070
+ducktools_classbuilder-0.1.1.dist-info/METADATA,sha256=oCGG72wG2iT_hOr8ezdbbyinzBXf95WXmB9n9rul-Iw,9280
+ducktools_classbuilder-0.1.1.dist-info/WHEEL,sha256=GJ7t_kWBFywbagK5eo9IoUwLW6oyOeTKmQ-9iHFVNxQ,92
+ducktools_classbuilder-0.1.1.dist-info/top_level.txt,sha256=uSDLtio3ZFqdwcsMJ2O5yhjB4Q3ytbBWbA8rJREganc,10
+ducktools_classbuilder-0.1.1.dist-info/RECORD,,

ducktools_classbuilder-0.1.0.dist-info/RECORD

@@ -1,10 +0,0 @@
-ducktools/classbuilder/__init__.py,sha256=oEdcQdMEqaQjUfbPkHpe55iCiPssDQxf4zxoAMdsTt8,12950
-ducktools/classbuilder/__init__.pyi,sha256=BlpHmxIL4dAiVKgqElRR3wVs7aw73qyJRaSvr-Tuyc0,2770
-ducktools/classbuilder/prefab.py,sha256=qQJzN4ys6Av6s9NaabzSqRKE5BXDfhidt3EtGZ0HAxQ,29405
-ducktools/classbuilder/prefab.pyi,sha256=wrq8NKwy9TsQ6fpnMyTf4DaGtCOK_90NHeU61CfNOo4,3589
-ducktools/classbuilder/py.typed,sha256=la67KBlbjXN-_-DfGNcdOcjYumVpKG_Tkw-8n5dnGB4,8
-ducktools_classbuilder-0.1.0.dist-info/LICENSE.md,sha256=6Thz9Dbw8R4fWInl6sGl8Rj3UnKnRbDwrc6jZerpugQ,1070
-ducktools_classbuilder-0.1.0.dist-info/METADATA,sha256=FHgeLZx-RfcvY2ty1l6O19z449So-UQZIcBinJ8n5xU,6675
-ducktools_classbuilder-0.1.0.dist-info/WHEEL,sha256=GJ7t_kWBFywbagK5eo9IoUwLW6oyOeTKmQ-9iHFVNxQ,92
-ducktools_classbuilder-0.1.0.dist-info/top_level.txt,sha256=uSDLtio3ZFqdwcsMJ2O5yhjB4Q3ytbBWbA8rJREganc,10
-ducktools_classbuilder-0.1.0.dist-info/RECORD,,