ducktools-classbuilder 0.1.0__tar.gz → 0.2.0__tar.gz

ducktools_classbuilder-0.2.0/MANIFEST.in

@@ -0,0 +1,9 @@
+graft src
+graft tests
+graft docs
+
+prune */build
+prune */dist
+prune */.pytest_cache
+
+global-exclude *~ *.py[cod] *.so

{ducktools-classbuilder-0.1.0 → ducktools_classbuilder-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: ducktools-classbuilder
-Version: 0.1.0
+Version: 0.2.0
 Summary: Toolkit for creating class boilerplate generators
 Author: David C Ellis
 License: MIT License
@@ -40,6 +40,7 @@ License-File: LICENSE.md
 Provides-Extra: testing
 Requires-Dist: pytest; extra == "testing"
 Requires-Dist: pytest-cov; extra == "testing"
+Requires-Dist: mypy; extra == "testing"
 Provides-Extra: docs
 Requires-Dist: sphinx; extra == "docs"
 Requires-Dist: myst-parser; extra == "docs"
@@ -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.2.0/README.md

@@ -0,0 +1,197 @@
+# 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 `@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 ##
+
+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 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)
+```
+
+> [!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? ##
+
+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` 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`.
+
+For example these two classes would be roughly equivalent, except that
+`@dataclass` has had to recreate the class from scratch while `@slotclass`
+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.
+
+```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.
+
+## 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.2.0/docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

ducktools_classbuilder-0.2.0/docs/api.md

@@ -0,0 +1,41 @@
+# Builder API Autodocs #
+
+## Slotclass example functions and classes ##
+
+```{eval-rst}
+.. autoclass:: ducktools.classbuilder::Field
+```
+
+```{eval-rst}
+.. autoclass:: ducktools.classbuilder::SlotFields
+```
+
+```{eval-rst}
+.. autofunction:: ducktools.classbuilder::slotclass
+```
+
+## Builder functions and classes ##
+
+```{eval-rst}
+.. autofunction:: ducktools.classbuilder::builder
+```
+
+```{eval-rst}
+.. autofunction:: ducktools.classbuilder::get_fields
+```
+
+```{eval-rst}
+.. autofunction:: ducktools.classbuilder::get_flags
+```
+
+```{eval-rst}
+.. autoclass:: ducktools.classbuilder::MethodMaker
+```
+
+```{eval-rst}
+.. autofunction:: ducktools.classbuilder::slot_gatherer
+```
+
+```{eval-rst}
+.. autofunction:: ducktools.classbuilder::fieldclass
+```

ducktools_classbuilder-0.2.0/docs/approach_vs_tool.md

@@ -0,0 +1,16 @@
+# Approaches and tools #
+
+As this module's code generation is inspired by the workings of [David Beazley's Cluegen](https://github.com/dabeaz/cluegen)
+I thought it was briefly worth discussing his note on learning an approach vs using a tool.
+
+I think that learning an approach is valuable, this module would not exist without the
+example given by `cluegen`. It also wouldn't exist if I hadn't needed to extend `cluegen`
+for some basic features (try using `Path` default values with `cluegen`).
+
+In the general spirit though, this module intends to provide some basic tools to help 
+build your own custom class generators.
+The generator included in the base module is intended to be used to help 'bootstrap' a 
+modified generator with features that work how **you** want them to work.
+
+The `prefab` module is the more fully featured powertool *I* built with these tools. 
+However, much like a prefabricated building, it may not be what you desire.

ducktools_classbuilder-0.2.0/docs/conf.py

@@ -0,0 +1,29 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'ducktools-classbuilder'
+copyright = '2024, David C Ellis'
+author = 'David C Ellis'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = ["myst_parser", "sphinx.ext.autodoc", "sphinx_rtd_theme"]
+
+autodoc_typehints = "description"
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+autoclass_content = "both"
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static']