ducktools-classbuilder 0.5.1__py3-none-any.whl → 0.6.1__py3-none-any.whl

ducktools/classbuilder/prefab.pyi

@@ -1,14 +1,19 @@
 import typing
+from types import MappingProxyType
 from typing_extensions import dataclass_transform
 
 from collections.abc import Callable
 
 from . import (
-    INTERNALS_DICT, NOTHING,
-    Field, MethodMaker, SlotFields as SlotFields,
-    builder, fieldclass, get_flags, get_fields, make_slot_gatherer
+    NOTHING,
+    Field,
+    GeneratedCode,
+    MethodMaker,
+    SlotMakerMeta,
 )
 
+from . import SlotFields as SlotFields, KW_ONLY as KW_ONLY
+
 # noinspection PyUnresolvedReferences
 from . import _NothingType
 
@@ -17,27 +22,15 @@ PREFAB_INIT_FUNC: str
 PRE_INIT_FUNC: str
 POST_INIT_FUNC: str
 
-
-# noinspection PyPep8Naming
-class _KW_ONLY_TYPE:
-    def __repr__(self) -> str: ...
-
-KW_ONLY: _KW_ONLY_TYPE
+_CopiableMappings = dict[str, typing.Any] | MappingProxyType[str, typing.Any]
 
 class PrefabError(Exception): ...
 
 def get_attributes(cls: type) -> dict[str, Attribute]: ...
 
-def get_init_maker(*, init_name: str="__init__") -> MethodMaker: ...
-
-def get_repr_maker(*, recursion_safe: bool = False) -> MethodMaker: ...
-
-def get_eq_maker() -> MethodMaker: ...
-
-def get_iter_maker() -> MethodMaker: ...
-
-def get_asdict_maker() -> MethodMaker: ...
-
+def init_generator(cls: type, funcname: str = "__init__") -> GeneratedCode: ...
+def iter_generator(cls: type, funcname: str = "__iter__") -> GeneratedCode: ...
+def as_dict_generator(cls: type, funcname: str = "as_dict") -> GeneratedCode: ...
 
 init_maker: MethodMaker
 prefab_init_maker: MethodMaker
@@ -50,13 +43,8 @@ asdict_maker: MethodMaker
 class Attribute(Field):
     __slots__: dict
 
-    init: bool
-    repr: bool
-    compare: bool
     iter: bool
-    kw_only: bool
     serialize: bool
-    exclude_field: bool
 
     def __init__(
         self,
@@ -71,7 +59,6 @@ class Attribute(Field):
         iter: bool = True,
         kw_only: bool = False,
         serialize: bool = True,
-        exclude_field: bool = False,
     ) -> None: ...
 
     def __repr__(self) -> str: ...
@@ -93,9 +80,7 @@ def attribute(
     exclude_field: bool = False,
 ) -> Attribute: ...
 
-def slot_prefab_gatherer(cls: type) -> tuple[dict[str, Attribute], dict[str, typing.Any]]: ...
-
-def attribute_gatherer(cls: type) -> tuple[dict[str, Attribute], dict[str, typing.Any]]: ...
+def prefab_gatherer(cls_or_ns: type | MappingProxyType) -> tuple[dict[str, Attribute], dict[str, typing.Any]]: ...
 
 def _make_prefab(
     cls: type,
@@ -114,6 +99,23 @@ def _make_prefab(
 
 _T = typing.TypeVar("_T")
 
+# noinspection PyUnresolvedReferences
+@dataclass_transform(field_specifiers=(Attribute, attribute))
+class Prefab(metaclass=SlotMakerMeta):
+    _meta_gatherer: Callable[[type | _CopiableMappings], tuple[dict[str, Field], dict[str, typing.Any]]]
+    def __init_subclass__(
+        cls,
+        init: bool = True,
+        repr: bool = True,
+        eq: bool = True,
+        iter: bool = False,
+        match_args: bool = True,
+        kw_only: bool = False,
+        frozen: bool = False,
+        dict_method: bool = False,
+        recursive_repr: bool = False,
+    ) -> None: ...
+
 
 # For some reason PyCharm can't see 'attribute'?!?
 # noinspection PyUnresolvedReferences

ducktools_classbuilder-0.6.1.dist-info/METADATA

@@ -0,0 +1,318 @@
+Metadata-Version: 2.1
+Name: ducktools-classbuilder
+Version: 0.6.1
+Summary: Toolkit for creating class boilerplate generators
+Author: David C Ellis
+License: 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.
+        
+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
+Classifier: Operating System :: OS Independent
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Provides-Extra: docs
+Requires-Dist: sphinx ; extra == 'docs'
+Requires-Dist: myst-parser ; extra == 'docs'
+Requires-Dist: sphinx-rtd-theme ; extra == 'docs'
+Provides-Extra: performance_tests
+Requires-Dist: attrs ; extra == 'performance_tests'
+Requires-Dist: pydantic ; extra == 'performance_tests'
+Provides-Extra: testing
+Requires-Dist: pytest ; extra == 'testing'
+Requires-Dist: pytest-cov ; extra == 'testing'
+Requires-Dist: mypy ; extra == 'testing'
+Requires-Dist: typing-extensions ; extra == 'testing'
+
+# Ducktools: Class Builder #
+
+`ducktools-classbuilder` is *the* Python package that will bring you the **joy**
+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 provide the tools to help make a customized
+version of the same concept.
+
+Install from PyPI with:
+`python -m pip install ducktools-classbuilder`
+
+## Included Implementations ##
+
+There are 2 different implementations provided with the module each of which offers
+a subclass based and decorator based option.
+
+> [!TIP]
+> For more information on using these tools to create your own implementations 
+> using the builder see
+> [the tutorial](https://ducktools-classbuilder.readthedocs.io/en/latest/tutorial.html)
+> for a full tutorial and 
+> [extension_examples](https://ducktools-classbuilder.readthedocs.io/en/latest/extension_examples.html)
+> for other customizations.
+
+### Core ###
+
+These tools are available from the main `ducktools.classbuilder` module.
+
+* `@slotclass`
+  * A decorator based implementation that uses a special dict subclass assigned
+     to `__slots__` to describe the fields for method generation.
+* `AnnotationClass`
+  * A subclass based implementation that works with `__slots__`, type annotations
+    or `Field(...)` attributes to describe the fields for method generation.
+  * If `__slots__` isn't used to declare fields, it will be generated by a metaclass.
+
+Each of these forms of class generation will result in the same methods being 
+attached to the class after the field information has been obtained.
+
+```python
+from ducktools.classbuilder import Field, SlotFields, slotclass
+
+@slotclass
+class SlottedDC:
+    __slots__ = SlotFields(
+        the_answer=42,
+        the_question=Field(
+            default="What do you get if you multiply six by nine?",
+            doc="Life, the Universe, and Everything",
+        ),
+    )
+    
+ex = SlottedDC()
+print(ex)
+```
+
+### Prefab ###
+
+This is available from the `ducktools.classbuilder.prefab` submodule.
+
+This includes more customization including `__prefab_pre_init__` and `__prefab_post_init__`
+functions for subclass customization.
+
+A `@prefab` decorator and `Prefab` base class are provided. 
+Similar to `AnnotationClass`, `Prefab` will generate `__slots__` by default.
+However decorated classes with `@prefab` that do not declare fields using `__slots__`
+will **not** be slotted and there is no `slots` argument to apply this.
+
+Here is an example of applying a conversion in `__post_init__`:
+```python
+from pathlib import Path
+from ducktools.classbuilder.prefab import Prefab
+
+class AppDetails(Prefab, frozen=True):
+    app_name: str
+    app_path: Path
+
+    def __prefab_post_init__(self, app_path: str | Path):
+        # frozen in `Prefab` is implemented as a 'set-once' __setattr__ function.
+        # So we do not need to use `object.__setattr__` here
+        self.app_path = Path(app_path)
+
+steam = AppDetails(
+    "Steam",
+    r"C:\Program Files (x86)\Steam\steam.exe"
+)
+
+print(steam)
+```
+
+
+## What is the issue with generating `__slots__` with a decorator ##
+
+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.
+
+When you use `@dataclass(slots=True)`[^2] with `dataclasses`, the function 
+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 using a metaclass or by declaring fields using `__slots__` however,
+the fields can be set *before* the class is constructed, so the class
+will work correctly without needing to be rebuilt.
+
+For example these two classes would be roughly equivalent, except that
+`@dataclass` has had to recreate the class from scratch while `AnnotationClass`
+has created `__slots__` and 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.
+
+Here's a demonstration of the issue using a registry for serialization 
+functions.
+
+> This example requires Python 3.10 or later as earlier versions of 
+> `dataclasses` did not support the `slots` argument.
+
+```python
+import json
+from dataclasses import dataclass
+from ducktools.classbuilder import AnnotationClass, Field
+
+
+class _RegisterDescriptor:
+    def __init__(self, func, registry):
+        self.func = func
+        self.registry = registry
+
+    def __set_name__(self, owner, name):
+        self.registry.register(owner, self.func)
+        setattr(owner, name, self.func)
+
+
+class SerializeRegister:
+    def __init__(self):
+        self.serializers = {}
+
+    def register(self, cls, func):
+        self.serializers[cls] = func
+
+    def register_method(self, method):
+        return _RegisterDescriptor(method, self)
+
+    def default(self, o):
+        try:
+            return self.serializers[type(o)](o)
+        except KeyError:
+            raise TypeError(f"Object of type {type(o).__name__} is not JSON serializable")
+
+
+register = SerializeRegister()
+
+
+@dataclass(slots=True)
+class DataCoords:
+    x: float = 0.0
+    y: float = 0.0
+
+    @register.register_method
+    def to_json(self):
+        return {"x": self.x, "y": self.y}
+
+
+# slots=True is the default for AnnotationClass
+class BuilderCoords(AnnotationClass, slots=True):
+    x: float = 0.0
+    y: float = Field(default=0.0, doc="y coordinate")
+
+    @register.register_method
+    def to_json(self):
+        return {"x": self.x, "y": self.y}
+
+
+# In both cases __slots__ have been defined
+print(f"{DataCoords.__slots__ = }")
+print(f"{BuilderCoords.__slots__ = }\n")
+
+data_ex = DataCoords()
+builder_ex = BuilderCoords()
+
+objs = [data_ex, builder_ex]
+
+print(data_ex)
+print(builder_ex)
+print()
+
+# Demonstrate you can not set values not defined in slots
+for obj in objs:
+    try:
+        obj.z = 1.0
+    except AttributeError as e:
+        print(e)
+print()
+
+print("Attempt to serialize:")
+for obj in objs:
+    try:
+        print(f"{type(obj).__name__}: {json.dumps(obj, default=register.default)}")
+    except TypeError as e:
+        print(f"{type(obj).__name__}: {e!r}")
+```
+
+Output (Python 3.12):
+```
+DataCoords.__slots__ = ('x', 'y')
+BuilderCoords.__slots__ = {'x': None, 'y': 'y coordinate'}
+
+DataCoords(x=0.0, y=0.0)
+BuilderCoords(x=0.0, y=0.0)
+
+'DataCoords' object has no attribute 'z'
+'BuilderCoords' object has no attribute 'z'
+
+Attempt to serialize:
+DataCoords: TypeError('Object of type DataCoords is not JSON serializable')
+BuilderCoords: {"x": 0.0, "y": 0.0}
+```
+
+## What features does this have? ##
+
+Included as an example implementation, the `slotclass` generator supports 
+`default_factory` for creating mutable defaults like lists, dicts etc.
+It also supports default values that are not builtins (try this on 
+[Cluegen](https://github.com/dabeaz/cluegen)).
+
+It will copy values provided as the `type` to `Field` into the 
+`__annotations__` dictionary of the class. 
+Values provided to `doc` will be placed in the final `__slots__` 
+field so they are present on the class if `help(...)` is called.
+
+`AnnotationClass` offers the same features with additional methods of gathering
+fields.
+
+If you want something with more features you can look at the `prefab`
+submodule which provides more specific features that differ further from the 
+behaviour of `dataclasses`.
+
+## Will you add \<feature\> to `classbuilder.prefab`? ##
+
+No. Not unless it's something I need or find interesting.
+
+The original version of `prefab_classes` was intended to have every feature
+anybody could possibly require, but this is no longer the case with this
+rebuilt version.
+
+I will fix bugs (assuming they're not actually intended behaviour).
+
+However the whole goal of this module is if you want to have a class generator
+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.6.1.dist-info/RECORD

@@ -0,0 +1,12 @@
+ducktools/classbuilder/__init__.py,sha256=i0NqVICBsMUBQtxX_2UsnETE9y0X15cwTSoSlE6_fJI,30820
+ducktools/classbuilder/__init__.pyi,sha256=tdYtI5Wqn-iur-MGGSpk4EbQTtl91F_MOGHXwYf4BYo,7656
+ducktools/classbuilder/annotations.py,sha256=17g1WnWfyMWBHKQp2HD_hvV-n7CKXy_zv8NTODpOsuU,5437
+ducktools/classbuilder/annotations.pyi,sha256=cTZQ-pp2IkfdvwHiU3pIySUzzBKxfOtO-e5PkA8TNwo,520
+ducktools/classbuilder/prefab.py,sha256=LCrnS2zKADX5FS0SdzCYLF4n5yR43CIlv2QLL6PDjl4,23292
+ducktools/classbuilder/prefab.pyi,sha256=1YkrSSTcjzhNn_AXSYiGIaX7kLm3DFckCR_zytFp0PE,4307
+ducktools/classbuilder/py.typed,sha256=la67KBlbjXN-_-DfGNcdOcjYumVpKG_Tkw-8n5dnGB4,8
+ducktools_classbuilder-0.6.1.dist-info/LICENSE.md,sha256=6Thz9Dbw8R4fWInl6sGl8Rj3UnKnRbDwrc6jZerpugQ,1070
+ducktools_classbuilder-0.6.1.dist-info/METADATA,sha256=7sRGN_m6jeEKYCdajAu8NN-7cs3U4E7s6YUdEj643m4,10911
+ducktools_classbuilder-0.6.1.dist-info/WHEEL,sha256=cpQTJ5IWu9CdaPViMhC9YzF8gZuS5-vlfoFihTBC86A,91
+ducktools_classbuilder-0.6.1.dist-info/top_level.txt,sha256=uSDLtio3ZFqdwcsMJ2O5yhjB4Q3ytbBWbA8rJREganc,10
+ducktools_classbuilder-0.6.1.dist-info/RECORD,,

{ducktools_classbuilder-0.5.1.dist-info → ducktools_classbuilder-0.6.1.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: bdist_wheel (0.43.0)
+Generator: setuptools (70.1.0)
 Root-Is-Purelib: true
 Tag: py3-none-any