Generics

.github/workflows/release.yml

@@ -1,7 +1,7 @@
 on:
   - workflow_dispatch
 
-name: Release packages
+name: Release Packages
 
 jobs:
   build:
@@ -15,39 +15,28 @@ jobs:
         with:
           python-version: "3.11"
 
-      - id: sdist
-        run: python setup.py sdist
+      - id: build
+        run: pip install hatch==1.6.3 && hatch build
 
       - id: version
         run: |
-          printf "::set-output name=version::%s\n" $(python -c "import runpy; print(runpy.run_path('strcs/version.py')['VERSION'])")
-          printf "::set-output name=versiondash::%s\n" $(python -c "import runpy; print(runpy.run_path('strcs/version.py')['VERSION'].replace('.', '-'))")
+          version=$(python -c "import runpy; print(runpy.run_path('strcs/version.py')['VERSION'])")
+          versiondash=$(python -c "import runpy; print(runpy.run_path('strcs/version.py')['VERSION'].replace('.', '-'))")
 
-      - id: package
-        run: >
-          printf "::set-output name=package::strcs-${{ steps.version.outputs.version}}.tar.gz"
-
-      - id: create_release
-        uses: actions/create-release@v1
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          echo "version=$version" >> $GITHUB_OUTPUT
+          echo "versiondash=$versiondash" >> $GITHUB_OUTPUT
 
+      - id: create-release
+        uses: softprops/action-gh-release@v1
         with:
-          tag_name: "release-${{ steps.version.outputs.version }}"
-          release_name: strcs ${{ steps.version.outputs.version }}
+          name: strcs ${{ steps.version.outputs.version }}
           body: "https://strcs.readthedocs.io/en/latest/strcs/changelog.html#release-${{ steps.version.outputs.versiondash }}"
+          tag_name: "release-${{ steps.version.outputs.version }}"
+          token: ${{ secrets.GITHUB_TOKEN }}
+          fail_on_unmatched_files: true
           draft: false
           prerelease: false
-
-      - id: upload-release-asset 
-        uses: actions/upload-release-asset@v1
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        with:
-          upload_url: ${{ steps.create_release.outputs.upload_url }}
-          asset_path: "dist/${{ steps.package.outputs.package }}"
-          asset_name: ${{ steps.package.outputs.package }}
-          asset_content_type: application/tar+gzip
+          files: "dist/*"
 
       - uses: pypa/gh-action-pypi-publish@v1.4.1
         with:

docs/conf.py

@@ -1,4 +1,14 @@
-extensions = ["sphinx.ext.autodoc", "sphinx_rtd_theme"]
+import pathlib
+import sys
+
+sys.path.append(str(pathlib.Path(__file__).parent))
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx_rtd_theme",
+    "sphinx_toolbox.more_autodoc.autoprotocol",
+    "strcs_sphinx_ext",
+]
 
 html_theme = "sphinx_rtd_theme"
 html_static_path = ["_static"]
@@ -16,3 +26,5 @@
 
 version = "0.1"
 release = "0.1"
+
+autodoc_preserve_defaults = True

docs/index.rst

@@ -7,6 +7,7 @@
    strcs/features/meta
    strcs/features/creators
    strcs/features/annotations
+   strcs/features/disassembled
 
 .. _strcs:
 
@@ -132,7 +133,7 @@ Here is a contrived example that shows a couple features. Read the
 
     # The meta object may also be given a custom cattrs Converter. In this case
     # we do not and a blank one is made for us.
-    meta = strcs.Meta({"renderer": renderer})
+    meta = reg.meta({"renderer": renderer})
 
     # First pass has no excluded authors
     images = reg.create(Images, configuration, meta=meta)

docs/strcs/changelog.rst

@@ -3,32 +3,44 @@
 Changelog
 ---------
 
+.. _release-0.3.0:
+
+0.3.0 - TBD
+    * Introduced a number of helpers for introspecting type annotations
+    * Introduced new ``strcs.Type`` class for representing types and creators
+      now take these objects.
+    * Can now create and use creators for generics so that when using the register
+      to create an object, the filled type vars of the provided type are
+      understood and respected.
+    * Updated dependencies
+    * Converted packaging to hatchling
+
 .. _release-0.2.0:
 
 0.2.0 - 30 October 2022
-   * Renamed toggle for auto resolution of string annotations
-   * Fixed structuring object as a type
+    * Renamed toggle for auto resolution of string annotations
+    * Fixed structuring object as a type
 
 .. _release-0.1.3:
 
 0.1.3 - 29 October 2022
-   * Improved error messages from creators failing
+    * Improved error messages from creators failing
 
 .. _release-0.1.2:
 
 0.1.2 - 29 October 2022
-   * Added py.typed file to the distribution
-   * Removed need for the recursed option
-   * Added resolution of string type annotations on attrs/dataclass/normal
-     classes
+    * Added py.typed file to the distribution
+    * Removed need for the recursed option
+    * Added resolution of string type annotations on attrs/dataclass/normal
+      classes
 
 .. _release-0.1.1:
 
 0.1.1 - 26 September 2022
-   * Fix a bunch of typing problems
+    * Fix a bunch of typing problems
 
 .. _release-0.1.0:
 
 0.1.0 - 21 August 2022
-   * Initial release
-   * Note this code is not actively used by anything yet
+    * Initial release
+    * Note this code is not actively used by anything yet

docs/strcs/features/annotations.rst

@@ -3,22 +3,20 @@
 Annotations
 ===========
 
-Python has a ``typing.Annotated`` since Python 3.9 that lets the developer attach
-information to a type and ``strcs`` will understand these annotations to get
-an object it uses to modify the meta and/or creator:
+.. automodule:: strcs.annotations
 
 .. code-block:: python
 
-    from attrs import define, asdict
+    import attrs
     import typing as tp
     import strcs
 
     reg = strcs.CreateRegister()
     creator = reg.make_decorator()
 
 
-    @define(frozen=True)
-    class MathsAnnotation(strcs.MergedAnnotation):
+    @attrs.define(frozen=True)
+    class MathsAnnotation(strcs.MergedMetaAnnotation):
         addition: int | None = None
         multiplication: int | None = None
 
@@ -27,12 +25,12 @@ an object it uses to modify the meta and/or creator:
         return (value + addition) * multiplication
 
 
-    @define
+    @attrs.define
     class Thing:
         val: tp.Annotated[int, strcs.Ann(MathsAnnotation(addition=20), do_maths)]
 
 
-    @define
+    @attrs.define
     class Holder:
         once: Thing
         twice: tp.Annotated[Thing, MathsAnnotation(multiplication=2)]
@@ -55,111 +53,14 @@ an object it uses to modify the meta and/or creator:
 
     holder = reg.create(Holder, 33)
     assert isinstance(holder, Holder)
-    assert asdict(holder) == {"once": {"val": 53}, "twice": {"val": 106}, "thrice": {"val": 159}}
+    assert attrs.asdict(holder) == {"once": {"val": 53}, "twice": {"val": 106}, "thrice": {"val": 159}}
 
 .. note:: it is a good idea to set a default value when retrieving multiple values
    from meta that have the same type. In the example above ``addition`` and
    ``multiplication`` are both ints and to force ``strcs`` to match by name a
    default is specified. Otherwise if only addition or multiplication are in meta
    then they will both be set to the value of the one that is found.
 
-An annotation may either be an instance of ``strcs.Ann``, an instance of
-``strcs.Annotation`` or a callable object. When a value is supplied that isn't
-``strcs.Ann`` then one is created from that value.
+.. autoclass:: strcs.Ann
 
-So if an ``strcs.Annotation`` is provided then it will create
-``strcs.Ann(meta=found)``, otherwise if the value is a callable then
-``strcs.Ann(creator=found)``.
-
-``strcs`` will use the ``adjusted_meta`` and ``adjusted_creator`` on the ``Ann``
-object to find a new meta or new creator to use for that field.
-
-New Meta will persist for any transformation that occurs below that field, but
-a new creator will only be used for that field.
-
-When providing a meta object to ``Ann``, there are two default strategies to
-choose from: ``strcs.Annotation`` and ``strcs.MergedAnnotation``. A custom
-strategy may be provided by implementing ``adjusted_meta`` on the ``Annotation``.
-
-``strcs.Annotation``
-    Will return a cloned meta containing ``__call_defined_annotation__`` so that
-    the creator may retrieve the entire ``Annotation`` using the type of that
-    annotation.
-
-    For example:
-
-    .. code-block:: python
-
-        @define(frozen=True)
-        class MyAnnotation(strcs.Annotation):
-            one: int
-            two: int
-
-        @creator(MyKls)
-        def create_mykls(value: object, /, annotation: MyAnnotation) -> dict | None:
-            if not isinstance(value, str):
-                return None
-            return {"key": f"{value}-{annotation.one}-{annotation.two}"}
-
-``strcs.MergedAnnotation``
-    Will add the keys from the annotation into the meta. This would mean
-    the above example becomes:
-
-    .. code-block:: python
-
-        @define(frozen=True)
-        class MyAnnotation(strcs.MergedAnnotation):
-            one: int
-            two: int
-
-        @creator(MyKls)
-        def create_mykls(value: object, /, one: int = 0, two: int = 0) -> dict | None:
-            if not isinstance(value, str):
-                return None
-            return {"key": f"{value}-{one}-{two}"}
-
-    Optional keys are not added to meta if they are not set:
-
-    .. code-block:: python
-
-        @define(frozen=True)
-        class MyAnnotation(strcs.MergedAnnotation):
-            one: int | None = None
-            two: int | None = None
-
-        @creator(MyKls)
-        def create_mykls(value: object, /, one: int = 0, two: int = 0) -> dict | None:
-            if not isinstance(value, str):
-                return None
-            # one and two will be zero each instead of None when MyKls
-            # is annotated with either of those not set respectively
-            return {"key": f"{value}-{one}-{two}"}
-
-Injecting data from meta
-------------------------
-
-Sometimes it is desirable to set a value straight from what is found in the Meta
-object and this may be achieved via ``strcs.FromMeta``:
-
-.. code-block:: python
-
-    from attrs import define
-    import typing as tp
-    import strcs
-
-    reg = strcs.CreateRegister()
-    creator = reg.make_decorator()
-
-
-    class Magic:
-        def incantation(self) -> str:
-            return "abracadabra!"
-
-
-    @define
-    class Wizard:
-        magic: tp.Annotated[Magic, strcs.FromMeta("magic")]
-
-
-    wizard = reg.create(Wizard, meta=strcs.Meta({"magic": Magic()}))
-    assert wizard.magic.incantation() == "abracadabra!"
+.. autoclass:: strcs.FromMeta