Merge pull request #34 from DavidCEllis/dont_evaluate_annotations

Don't evaluate annotations in `get_ns_annotations`, remove AnnotationClass

Author: DavidCEllis

README.md

@@ -32,10 +32,12 @@ 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.
+* `SlotMakerMeta`
+  * A metaclass for creating other implementations using annotations, fields or slots.
+  * This metaclass will allow for creating `__slots__` correctly in subclasses.
+* `builder`
+  * This is the main tool used for constructing decorators and base classes to provide
+    generated methods.
 
 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.
@@ -65,8 +67,9 @@ This includes more customization including `__prefab_pre_init__` and `__prefab_p
 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__`
+
+`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__`:
@@ -110,7 +113,7 @@ 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`
+`@dataclass` has had to recreate the class from scratch while `Prefab`
 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 
@@ -125,7 +128,7 @@ functions.
 ```python
 import json
 from dataclasses import dataclass
-from ducktools.classbuilder import AnnotationClass, Field
+from ducktools.classbuilder.prefab import Prefab, attribute
 
 
 class _RegisterDescriptor:
@@ -168,10 +171,10 @@ class DataCoords:
         return {"x": self.x, "y": self.y}
 
 
-# slots=True is the default for AnnotationClass
-class BuilderCoords(AnnotationClass, slots=True):
+# slots=True is the default for Prefab
+class BuilderCoords(Prefab):
     x: float = 0.0
-    y: float = Field(default=0.0, doc="y coordinate")
+    y: float = attribute(default=0.0, doc="y coordinate")
 
     @register.register_method
     def to_json(self):
@@ -235,9 +238,6 @@ It will copy values provided as the `type` to `Field` into the
 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`.

docs/api.md

@@ -40,7 +40,3 @@
 ```{eval-rst}
 .. autofunction:: ducktools.classbuilder.annotations::make_annotation_gatherer
 ```
-
-```{eval-rst}
-.. autoclass:: ducktools.classbuilder.annotations::AnnotationClass
-```

docs/extension_examples.md

@@ -469,7 +469,8 @@ To implement this you need to create a new annotated_gatherer function.
 >       If you need to change the value of a field use Field.from_field(...) to make a new instance.
 
 ```python
-from __future__ import annotations
+# Don't use __future__ annotations with get_ns_annotations in this case 
+# as it doesn't evaluate string annotations.
 
 import types
 from typing import Annotated, Any, ClassVar, get_origin

docs/generated_code.md

@@ -7,11 +7,14 @@ There is a helper function `get_methods` that can be used to obtain the names an
 methods that have been attached to the class by the builder.
 
 ```python
-from ducktools.classbuilder import AnnotationClass, get_methods
+from ducktools.classbuilder import SlotFields, get_methods, slotclass
 
-class Example(AnnotationClass):
-    a: str = "a"
-    b: str = "b"
+@slotclass
+class Example:
+    __slots__ = SlotFields(
+        a='a',
+        b='b'
+    )
 
 print(get_methods(Example))
 ```
@@ -28,12 +31,15 @@ These can then be used to examine the generated source code and global variables
 to the `exec` function. This can be useful for debugging code generators.
 
 ```python
-from ducktools.classbuilder import AnnotationClass, get_methods
-
-class Example(AnnotationClass):
-    a: str = "a"
-    b: str = "b"
-
+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():

docs/index.md

@@ -65,15 +65,44 @@ ex = SlottedDC()
 print(ex)
 ```
 
-## Annotation Class Usage ##
+## Using Annotations ##
 
-There is an additional AnnotationClass base class that allows creating slotted classes
-using annotations. This has to be a base class with a specific metaclass in order to 
-create the `__slots__` field *before* the class has been generated in order to work
-correctly.
+It is possible to create slotted classes using Annotations.
+There is a `Prefab` base class in the `prefab` submodule that does this,
+but it also easy to implement using the provided tools.
+
+In order to correctly implement `__slots__` this needs to be done
+using a metaclass as `__slots__` must be defined before the **class**
+is created.
 
 ```python
-from ducktools.classbuilder import AnnotationClass
+from ducktools.classbuilder import (
+    SlotMakerMeta, 
+    annotation_gatherer,
+    builder,
+    check_argument_order,
+    default_methods,
+)
+
+
+class AnnotationClass(metaclass=SlotMakerMeta):
+    __slots__ = {}
+
+    def __init_subclass__(
+            cls,
+            methods=default_methods,
+            gatherer=annotation_gatherer,
+            **kwargs
+    ):
+        # Check class dict otherwise this will always be True as this base
+        # class uses slots.
+        slots = "__slots__" in cls.__dict__
+
+        builder(cls, gatherer=gatherer, methods=methods, flags={"slotted": slots})
+        check_argument_order(cls)
+        super().__init_subclass__(**kwargs)
+
+
 
 class AnnotatedDC(AnnotationClass):
     the_answer: int = 42

docs/tutorial.md

@@ -146,9 +146,15 @@ def report_generator(cls, funcname="report"):
 report_maker = dtbuild.MethodMaker("report", report_generator)
 ```
 
-We can take a quick look at what this generates by applying it to an `AnnotationClass`:
+We can take a quick look at what this generates by applying it to a `slotclass`:
 ```python
-class CodegenDemo(dtbuild.AnnotationClass):
+@dtbuild.slotclass
+class CodegenDemo:
+    __slots__ = dtbuild.SlotFields(
+        field_1="Field one",
+        field_2="Field two",
+        field_3="Field three",       
+    )
     field_1: str = "Field one"
     field_2: str = "Field two"
     field_3: str = "Field three"

docs_code/docs_ex9_annotated.py

@@ -1,5 +1,3 @@
-from __future__ import annotations
-
 import types
 from typing import Annotated, Any, ClassVar, get_origin
 

docs_code/index_example.py

@@ -0,0 +1,34 @@
+from ducktools.classbuilder import (
+    SlotMakerMeta,
+    builder,
+    check_argument_order,
+    default_methods,
+    unified_gatherer,
+)
+
+
+class AnnotationClass(metaclass=SlotMakerMeta):
+    __slots__ = {}
+
+    def __init_subclass__(
+            cls,
+            methods=default_methods,
+            gatherer=unified_gatherer,
+            **kwargs
+    ):
+        # Check class dict otherwise this will always be True as this base
+        # class uses slots.
+        slots = "__slots__" in cls.__dict__
+
+        builder(cls, gatherer=gatherer, methods=methods, flags={"slotted": slots})
+        check_argument_order(cls)
+        super().__init_subclass__(**kwargs)
+
+
+class AnnotatedDC(AnnotationClass):
+    the_answer: int = 42
+    the_question: str = "What do you get if you multiply six by nine?"
+
+
+ex = AnnotatedDC()
+print(ex)

docs_code/tutorial_code.py

@@ -81,10 +81,13 @@ def report_generator(cls, funcname="report"):
 
 
 # View the generated code by testing on a demo class
-class CodegenDemo(dtbuild.AnnotationClass):
-    field_1: str = "Field one"
-    field_2: str = "Field two"
-    field_3: str = "Field three"
+@dtbuild.slotclass
+class CodegenDemo:
+    __slots__ = dtbuild.SlotFields(
+        field_1="Field one",
+        field_2="Field two",
+        field_3="Field three",
+    )
 
 
 print(report_generator(CodegenDemo).source_code)

src/ducktools/classbuilder/__init__.py

@@ -769,7 +769,7 @@ def field_annotation_gatherer(cls_or_ns):
             if is_classvar(v):
                 continue
 
-            if v is KW_ONLY:
+            if v is KW_ONLY or (isinstance(v, str) and v == "KW_ONLY"):
                 if kw_flag:
                     raise SyntaxError("KW_ONLY sentinel may only appear once.")
                 kw_flag = True
@@ -868,7 +868,7 @@ def field_unified_gatherer(cls_or_ns):
         # To choose between annotation and attribute gatherers
         # compare sets of names.
         # Don't bother evaluating string annotations, as we only need names
-        cls_annotations = get_ns_annotations(cls_dict, eval_str=False)
+        cls_annotations = get_ns_annotations(cls_dict)
         cls_attributes = {
             k: v for k, v in cls_dict.items() if isinstance(v, field_type)
         }