ducktools-classbuilder 0.1.0__py3-none-any.whl

ducktools/classbuilder/prefab.pyi

@@ -0,0 +1,151 @@
+import typing
+from collections.abc import Callable
+
+from . import (
+    INTERNALS_DICT, NOTHING,
+    Field, MethodMaker, SlotFields as SlotFields,
+    builder, fieldclass, get_internals, slot_gatherer
+)
+
+PREFAB_FIELDS: str
+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
+
+class PrefabError(Exception): ...
+
+def _is_classvar(hint: type | str) -> bool: ...
+
+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_frozen_setattr_maker() -> MethodMaker: ...
+
+def get_frozen_delattr_maker() -> MethodMaker: ...
+
+def get_asdict_maker() -> MethodMaker: ...
+
+
+init_desc: MethodMaker
+prefab_init_desc: MethodMaker
+repr_desc: MethodMaker
+recursive_repr_desc: MethodMaker
+eq_desc: MethodMaker
+iter_desc: MethodMaker
+frozen_setattr_desc: MethodMaker
+frozen_delattr_desc: MethodMaker
+asdict_desc: MethodMaker
+
+class Attribute(Field):
+    __slots__: dict
+
+    init: bool
+    repr: bool
+    compare: bool
+    kw_only: bool
+    in_dict: bool
+    exclude_field: bool
+
+    def __init__(
+        self,
+        *,
+        default: typing.Any | NOTHING =NOTHING,
+        default_factory: typing.Any | NOTHING = NOTHING,
+        type: type | NOTHING = NOTHING,
+        doc: str | None = None,
+        init: bool = True,
+        repr: bool = True,
+        compare: 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 validate_field(self) -> None: ...
+
+def attribute(
+    *,
+    default: typing.Any | NOTHING = NOTHING,
+    default_factory: typing.Any | NOTHING = NOTHING,
+    type: type | NOTHING = NOTHING,
+    doc: str | None = None,
+    init: bool = True,
+    repr: bool = True,
+    compare: bool = True,
+    kw_only: bool = False,
+    in_dict: bool = True,
+    exclude_field: bool = False,
+) -> Attribute: ...
+
+def attribute_gatherer(cls: type) -> dict[str, Attribute]: ...
+
+def _make_prefab(
+    cls: type,
+    *,
+    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,
+) -> type: ...
+
+@typing.dataclass_transform
+def prefab(
+    cls: type | None = None,
+    *,
+    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,
+) -> type | Callable[[type], type]: ...
+
+def build_prefab(
+    class_name: str,
+    attributes: list[tuple[str, Attribute]],
+    *,
+    bases: tuple[type, ...] = (),
+    class_dict: dict[str, typing.Any] | None = None,
+    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,
+) -> type: ...
+
+def is_prefab(o: typing.Any) -> bool: ...
+
+def is_prefab_instance(o: object) -> bool: ...
+
+def as_dict(o) -> dict[str, typing.Any]: ...

ducktools/classbuilder/py.typed

@@ -0,0 +1 @@
+partial

ducktools_classbuilder-0.1.0.dist-info/LICENSE.md

@@ -0,0 +1,21 @@
+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.

ducktools_classbuilder-0.1.0.dist-info/METADATA

@@ -0,0 +1,179 @@
+Metadata-Version: 2.1
+Name: ducktools-classbuilder
+Version: 0.1.0
+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: testing
+Requires-Dist: pytest ; extra == 'testing'
+Requires-Dist: pytest-cov ; 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 be a dataclasses-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.
+
+## Slot Class Usage ##
+
+The building toolkit also includes a basic implementation that uses
+`__slots__` to define the fields by assigning a `SlotFields` instance.
+
+```python
+from ducktools.classbuilder import slotclass, Field, SlotFields
+
+@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)
+```
+
+## Why does the basic implementation use slots? ##
+
+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.
+
+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.
+
+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.
+
+For example these two classes would be roughly equivalent, except 
+`@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.
+
+> This example requires Python 3.10 as earlier versions of 
+> `dataclasses` did not support the `slots` argument.
+
+```python
+from dataclasses import dataclass
+from ducktools.classbuilder import slotclass, SlotFields
+
+class_register = {}
+
+
+def register(cls):
+    class_register[cls.__name__] = cls
+    return cls
+
+
+@dataclass(slots=True)
+@register
+class DataCoords:
+    x: float = 0.0
+    y: float = 0.0
+
+
+@slotclass
+@register
+class SlotCoords:
+    __slots__ = SlotFields(x=0.0, y=0.0)
+    # Type hints don't affect class construction, these are optional.
+    x: float
+    y: float
+
+
+print(DataCoords())
+print(SlotCoords())
+
+print(f"{DataCoords is class_register[DataCoords.__name__] = }")
+print(f"{SlotCoords is class_register[SlotCoords.__name__] = }")
+
+```
+
+## 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.
+
+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.
+
+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)

ducktools_classbuilder-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+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,,

ducktools_classbuilder-0.1.0.dist-info/WHEEL

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

ducktools_classbuilder-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+ducktools