Merge pull request #72 from DavidCEllis/add_order_comparisons

Add order comparisons

Author: DavidCEllis

README.md

@@ -17,29 +17,35 @@ Install from PyPI with:
 The classbuilder tools make up the core of this module and there is an implementation
 using these tools in the `prefab` submodule.
 
-There is also a minimal `@slotclass` example that can construct classes from a special
-mapping used in `__slots__`.
+The implementation provides both a base class `Prefab` that will also generate `__slots__`
+and a decorator `@prefab` which does not support `__slots__`.
 
 ```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",
-        ),
+from ducktools.classbuilder.prefab import Prefab, attribute
+
+class Slotted(Prefab):
+    the_answer: int = 42
+    the_question: str = attribute(
+        default="What do you get if you multiply six by nine?",
+        doc="Life the universe and everything",
     )
 
-ex = SlottedDC()
+ex = Slotted()
 print(ex)
+print(ex.__slots__)
+```
+
+The generated source code for the methods can be viewed using the `print_generated_code` helper function.
+
+```python
+from ducktools.classbuilder import print_generated_code
+
+print_generated_code(SlottedDC)
 ```
 
 ### Core ###
 
-The core of the module provides tools for creating a customized version of the `dataclass` concept.
+The base `ducktools.classbuilder` module provides tools for creating a customized version of the `dataclass` concept.
 
 * `MethodMaker`
   * This tool takes a function that generates source code and converts it into a descriptor
@@ -75,12 +81,6 @@ This prebuilt implementation is available from the `ducktools.classbuilder.prefa
 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.
-
-`Prefab` will generate `__slots__` by default.
-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
@@ -106,7 +106,7 @@ print(steam)
 #### Features ####
 
 `Prefab` and `@prefab` support many standard dataclass features along with
-a few extras.
+some extra features and some intentional differences in design.
 
 * All standard methods are generated on-demand
   * This makes the construction of classes much faster in general
@@ -132,20 +132,20 @@ a few extras.
   * `iter=True` will include the attribute in the iterable if `__iter__` is generated
   * `serialize=True` decides if the attribute is include in `as_dict`
   * `exclude_field` is short for `repr=False`, `compare=False`, `iter=False`, `serialize=False`
-  * `private` is short for `exclude_field=True` and `init=False` and requires a default/factory
+  * `private` is short for `exclude_field=True` and `init=False` and requires a default or factory
   * `doc` will add this string as the value in slotted classes, which appears in `help()`
 * `build_prefab` can be used to dynamically create classes and *does* support a slots argument
   * Unlike dataclasses, this does not create the class twice in order to provide slots
 
 There are also some intentionally missing features:
 
-* The `@prefab` decorator does not and will not support a `slots` argument
+* The `@prefab` decorator does not and will never support a `slots` argument
   * Use `Prefab` for slots.
 * `as_dict` and the generated `.as_dict` method **do not** recurse or deep copy
 * `unsafe_hash` is not provided
 * `weakref_slot` is not available as an argument
   * `__weakref__` can be added to slots by declaring it as if it were an attribute
-* There is no check for mutable defaults
+* There is no safety check for mutable defaults
   * You should still use `default_factory` as you would for dataclasses, not doing so
     is still incorrect
   * `dataclasses` uses hashability as a proxy for mutability, but technically this is
@@ -162,7 +162,7 @@ There are also some intentionally missing features:
 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
+When you use `@dataclass(slots=True)`[^1] 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*
@@ -305,8 +305,4 @@ with a specific feature, you can create or add it yourself.
 
 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`.
+[^1]: or `@attrs.define`.

docs/code_examples/docs_ex01_basic.py

@@ -1,17 +1,13 @@
-from ducktools.classbuilder import slotclass, Field, SlotFields
+from ducktools.classbuilder.prefab import Prefab, attribute
 
-
-@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",
-        ),
+class Slotted(Prefab):
+    the_answer: int = 42
+    the_question: str = attribute(
+        default="What do you get if you multiply six by nine?",
+        doc="Life the universe and everything",
     )
 
-
-ex = SlottedDC()
+ex = Slotted()
 print(ex)
-help(SlottedDC)
+print(ex.__slots__)
+help(Slotted)

docs/code_examples/outputs/docs_ex01_basic.output

@@ -1,23 +1,31 @@
-SlottedDC(the_answer=42, the_question='What do you get if you multiply six by nine?')
-Help on class SlottedDC in module __main__:
+Slotted(the_answer=42, the_question='What do you get if you multiply six by nine?')
+{'the_answer': None, 'the_question': 'Life the universe and everything'}
+Help on class Slotted in module __main__:
 
-class SlottedDC(builtins.object)
- |  SlottedDC(
- |      the_answer=42,
- |      the_question='What do you get if you multiply six by nine?'
- |  )
+class Slotted(ducktools.classbuilder.prefab.Prefab)
+ |  Slotted(
+ |      the_answer: int = 42,
+ |      the_question: str = 'What do you get if you multiply six by nine?'
+ |  ) -> None
+ |
+ |  Method resolution order:
+ |      Slotted
+ |      ducktools.classbuilder.prefab.Prefab
+ |      builtins.object
  |
  |  Methods defined here:
  |
- |  __eq__(self, other) from SlottedDC
+ |  __eq__(self, other) from Slotted
  |
  |  __init__(
  |      self,
- |      the_answer=42,
- |      the_question='What do you get if you multiply six by nine?'
- |  ) from SlottedDC
+ |      the_answer: int = 42,
+ |      the_question: str = 'What do you get if you multiply six by nine?'
+ |  ) -> None from Slotted
+ |
+ |  __replace__(self, /, **changes) from Slotted
  |
- |  __repr__(self) from SlottedDC
+ |  __repr__(self) from Slotted
  |
  |  __signature__
  |
@@ -27,12 +35,41 @@ class SlottedDC(builtins.object)
  |  the_answer
  |
  |  the_question
- |      Life, the Universe, and Everything
+ |      Life the universe and everything
  |
  |  ----------------------------------------------------------------------
  |  Data and other attributes defined here:
  |
+ |  PREFAB_FIELDS = ['the_answer', 'the_question']
+ |
+ |  __classbuilder_gathered_fields__ = ({'the_answer': Attribute(default=4...
+ |
  |  __classbuilder_internals__ = {'build_complete': True, 'fields': {'the_...
  |
  |  __hash__ = None
+ |
+ |  __match_args__ = ('the_answer', 'the_question')
+ |
+ |  ----------------------------------------------------------------------
+ |  Class methods inherited from ducktools.classbuilder.prefab.Prefab:
+ |
+ |  __init_subclass__(**kwargs)
+ |      Generate boilerplate code for dunder methods in a class.
+ |
+ |      Use as a base class, slotted by default
+ |
+ |      :param init: generates __init__ if true or __prefab_init__ if false
+ |      :param repr: generate __repr__
+ |      :param eq: generate __eq__
+ |      :param iter: generate __iter__
+ |      :param match_args: generate __match_args__
+ |      :param kw_only: make all attributes keyword only
+ |      :param frozen: Prevent attribute values from being changed once defined
+ |                  (This does not prevent the modification of mutable attributes such as lists)
+ |      :param replace: generate a __replace__ method
+ |      :param dict_method: Include an as_dict method for faster dictionary creation
+ |      :param recursive_repr: Safely handle repr in case of recursion
+ |      :param ignore_annotations: Ignore type annotations when gathering fields, only look for
+ |                              slots or attribute(...) values
+ |      :param slots: automatically generate slots for this class's attributes
 

docs/generated_code.md

@@ -3,45 +3,75 @@
 If you wish to see the source code generated by a constructed class you need to access the
 `MethodMaker` instances on that class.
 
-There is a helper function `get_methods` that can be used to obtain the names and respective
-methods that have been attached to the class by the builder.
+There are helper functions that will do this for you and also retrieve the source code the
+`MethodMaker` objects would generate.
+
+`print_generated_code` will print the source code for all methods along with any necessary globals
+and annotations associated with the method being generated.
+
+`get_generated_code` will retrieve the `GeneratedCode` objects that will be used to create the
+class methods. These have `source_code`, `globs` and `annotations` attributes.
+
+You can also directly access the MethodMakers with the `get_methods` function
 
 ```python
-from ducktools.classbuilder import SlotFields, get_methods, slotclass
+from pathlib import Path
+from pprint import pp
 
-@slotclass
-class Example:
-    __slots__ = SlotFields(
-        a='a',
-        b='b'
-    )
+from ducktools.classbuilder import get_generated_code, print_generated_code
+from ducktools.classbuilder.prefab import attribute, Prefab
 
-print(get_methods(Example))
-```
 
+class Example(Prefab):
+    a: int
+    b: int = 42
+    c: list = attribute(default_factory=list)
+    p: Path = Path("/usr/bin/python")
+
+generated_code = get_generated_code(Example)
+
+pp(generated_code)
 ```
-{
-  '__init__': <MethodMaker for '__init__' method>, 
-  '__repr__': <MethodMaker for '__repr__' method>, 
-  '__eq__': <MethodMaker for '__eq__' method>
-}
+
+Output:
+
+```python
+{'__init__': GeneratorOutput(source_code='def __init__(self, a, b=42, c=None, p=_p_default): ...', globs={'_c_factory': <class 'list'>, '_p_default': PosixPath('/usr/bin/python')}, annotations={'a': <class 'int'>, 'b': <class 'int'>, 'c': <class 'list'>, 'p': <class 'pathlib.Path'>, 'return': None}),
+ '__eq__': GeneratorOutput(source_code='def __eq__(self, other): ...', globs={}, annotations=None),
+ '__repr__': GeneratorOutput(source_code='def __repr__(self): ...', globs={}, annotations=None),
+ '__replace__': GeneratorOutput(source_code='def __replace__(self, /, **changes): ...', globs={}, annotations=None)}
 ```
 
-These can then be used to examine the generated source code and global variables provided
-to the `exec` function. This can be useful for debugging code generators.
+`print_generated_code(Example)` cleans up the output to be more presentable and readable
 
 ```python
-from ducktools.classbuilder import SlotFields, get_methods, slotclass
-
-@slotclass
-class Example:
-    __slots__ = SlotFields(
-        a='a',
-        b='b',
-    )
-    
-methods = get_methods(Example)
-
-for method in methods.values():
-    print(method.code_generator(Example))
+Source:
+    def __eq__(self, other):
+        return (
+            self.a == other.a
+            and self.b == other.b
+            and self.c == other.c
+            and self.p == other.p
+        ) if self.__class__ is other.__class__ else NotImplemented
+
+    def __init__(self, a, b=42, c=None, p=_p_default):
+        self.a = a
+        self.b = b
+        self.c = c if c is not None else _c_factory()
+        self.p = p
+
+    def __replace__(self, /, **changes):
+        new_kwargs = {'a': self.a, 'b': self.b, 'c': self.c, 'p': self.p}
+        new_kwargs |= changes
+        return self.__class__(**new_kwargs)
+
+    def __repr__(self):
+        return f'{type(self).__qualname__}(a={self.a!r}, b={self.b!r}, c={self.c!r}, p={self.p!r})'
+
+
+Globals:
+    __init__: {'_c_factory': <class 'list'>, '_p_default': PosixPath('/usr/bin/python')}
+
+Annotations:
+    __init__: {'a': <class 'int'>, 'b': <class 'int'>, 'c': <class 'list'>, 'p': <class 'pathlib.Path'>, 'return': None}
 ```

src/ducktools/classbuilder/__init__.py

@@ -136,7 +136,7 @@ def print_generated_code(cls):
     globs_list = []
     annotation_list = []
 
-    for name, method in source.items():
+    for name, method in sorted(source.items()):
         source_list.append(method.source_code)
         if method.globs:
             globs_list.append(f"{name}: {method.globs}")
@@ -484,6 +484,38 @@ def eq_generator(cls, funcname="__eq__"):
     return GeneratedCode(code, globs)
 
 
+def get_order_generator(cls, funcname, *, operator):
+    field_names = [
+        name
+        for name, attrib in get_fields(cls).items()
+        if attrib.compare
+    ]
+
+    self_tuple = ", ".join(f"self.{name}" for name in field_names)
+    other_tuple = self_tuple.replace("self.", "other.")
+
+    code = (
+        f"def {funcname}(self, other):\n"
+        f"    if self.__class__ is other.__class__:\n"
+        f"        return ({self_tuple}) {operator} ({other_tuple})\n"
+        f"    return NotImplemented\n"
+    )
+    globs = {}
+    return GeneratedCode(code, globs)
+
+def lt_generator(cls, funcname="__lt__"):
+    return get_order_generator(cls, funcname, operator="<")
+
+def le_generator(cls, funcname="__le__"):
+    return get_order_generator(cls, funcname, operator="<=")
+
+def gt_generator(cls, funcname="__gt__"):
+    return get_order_generator(cls, funcname, operator=">")
+
+def ge_generator(cls, funcname="__ge__"):
+    return get_order_generator(cls, funcname, operator=">=")
+
+
 def replace_generator(cls, funcname="__replace__"):
     # Generate the replace method for built classes
     # unlike the dataclasses implementation this is generated
@@ -556,6 +588,10 @@ def frozen_delattr_generator(cls, funcname="__delattr__"):
 init_maker = MethodMaker("__init__", init_generator)
 repr_maker = MethodMaker("__repr__", repr_generator)
 eq_maker = MethodMaker("__eq__", eq_generator)
+lt_maker = MethodMaker("__lt__", lt_generator)
+le_maker = MethodMaker("__le__", le_generator)
+gt_maker = MethodMaker("__gt__", gt_generator)
+ge_maker = MethodMaker("__ge__", ge_generator)
 replace_maker = MethodMaker("__replace__", replace_generator)
 frozen_setattr_maker = MethodMaker("__setattr__", frozen_setattr_generator)
 frozen_delattr_maker = MethodMaker("__delattr__", frozen_delattr_generator)