Merge pull request #11 from DanCardin/dc/declarative

docs/source/api.rst

@@ -1,6 +1,20 @@
 API
 ===
 
+.. _model_factory:
+.. automodule:: sqlalchemy_model_factory
+    :members: ModelFactory
+
+
+Declarative
+-----------
+
+.. automodule:: sqlalchemy_model_factory.declarative
+    :members: declarative
+
+.. automodule:: sqlalchemy_model_factory.declarative
+    :members: DeclarativeMF
+
 
 Factory Utilities
 -----------------

docs/source/declarative.rst

@@ -0,0 +1,66 @@
+Declarative API
+===============
+There are a few benefits to declaratively specifying the factory function tree:
+
+- The vanilla ``@register_at`` decorator is dynamic and string based, which
+  leaves no direct import or path to trace back to the implementing function
+  from a ``ModelFactory`` instance.
+- There is, perhaps, an alternative declarative implementation which ensures
+  the yielded ``ModelFactory`` literally **is** the heirarchy specified.
+
+  - As is, if you're in a context in which you can type annotate the model
+    factory, then this enables typical LSP features like "Go to Definition".
+
+    In the most common cases, such as with ``pytest``, you'll be being handed
+    an untyped ``mf`` (:ref:`model_factory`) fixture instance. Here, you can
+    type annotate the argument as being your ``@declarative`` ly decorated
+    class.
+
+
+.. code-block:: python
+
+   # some_module.py
+   class other:
+       def new():
+           ...
+
+   # factory.py
+   from some_module import other
+
+   @declarative
+   class ModelFactory:
+       other = other
+
+       class namespace:
+           def example():
+               ...
+
+   # tests.py
+   from sqlalchemy_model_factory.pytest import create_registry_fixture
+   from factory import ModelFactory
+
+   mf_registry = create_registry_fixture(ModelFactory)
+
+   # `mf` being a sqlalchemy_model_factory-provided fixture.
+   def test_factory(mf: ModelFactory):
+      ...
+
+Alternatively, a registry can be provided to the decorator directly,
+ou have one pre-constructed.
+
+.. code-block:: python
+
+   registry = Registry()
+   
+   @declarative(registry=registry)
+   class ModelFactory:
+       def fn():
+           ...
+
+.. note::
+
+   interior classes to the decorator, including both the root class, as
+   well as any nested class or attributes which are raw types, will be
+   instantiated. This is notable, primarily in the event that an `__init__`
+   is defined on the class for whatever reason. Each class will be instantiated
+   once without arguments.

docs/source/index.rst

@@ -8,6 +8,7 @@ Welcome to SQLAlchemy Model Factory's documentation!
    Quickstart <quickstart>
    Testing (Pytest) <testing>
    Factories <factories>
+   Declarative <declarative>
    Options <options>
    API <api>
 

pyproject.toml

@@ -15,19 +15,13 @@ include = [
 ]
 
 [tool.poetry.dependencies]
-python = ">=3.6,<4"
+python = ">=3.6.2,<4"
 
 sqlalchemy = "*"
 pytest = {version = ">=1.0", optional = true}
 
-sphinx = {version = "*", optional = true}
-m2r = {version = "*", optional = true}
-sphinx_rtd_theme = {version = "*", optional = true}
-sphinx_autodoc_typehints = {version = "*", optional = true}
-sphinx-autobuild = {version = "*", optional = true}
-
 [tool.poetry.dev-dependencies]
-black = {version = "=>19.3b0", allow-prereleases = true, python = ">=3.6"}
+black = {version = "^21.11b1", allow-prereleases = true, python = ">=3.6"}
 coverage = ">=5"
 flake8 = "*"
 isort = ">=5"
@@ -38,7 +32,6 @@ sqlalchemy-stubs = "*"
 
 [tool.poetry.extras]
 pytest = ['pytest']
-docs = ['sphinx', 'm2r', 'sphinx_rtd_theme', 'sphinx-autobuild']
 
 [tool.poetry.plugins.pytest11]
 model_manager = "sqlalchemy_model_factory.pytest"

src/sqlalchemy_model_factory/__init__.py

@@ -1,2 +1,3 @@
-from sqlalchemy_model_factory.registry import register_at  # noqa
+from sqlalchemy_model_factory.declarative import declarative  # noqa
+from sqlalchemy_model_factory.registry import register_at, Registry, registry  # noqa
 from sqlalchemy_model_factory.utils import autoincrement, fluent, for_model  # noqa