Add documentation

Author: jdkandersson

docs/source/examples/index.rst

@@ -18,3 +18,4 @@ Examples
    all_of
    inheritance
    json
+   mixins

docs/source/examples/mixins.rst

@@ -0,0 +1,37 @@
+Mixin Classes
+=============
+
+SQLAlchemy supports mixin classes for models to add functionality. OpenAlchemy
+supports this through the :samp:`x-mixins` extension property that may define
+one or more importable class to mix into the model class.
+
+.. seealso::
+
+    :ref:`mixins`
+      OpenAlchemy documentation for the :samp:`x-mixins` value.
+
+The following example adds the :samp:`sqlalchemy_mixins.TimestampsMixin` to
+the :samp:`Employee` model:
+
+.. literalinclude:: ../../../examples/mixins/example-spec.yml
+    :language: yaml
+    :linenos:
+
+The following file uses OpenAlchemy to generate the SQLAlchemy models:
+
+.. literalinclude:: ../../../examples/mixins/models.py
+    :language: python
+    :linenos:
+
+The SQLAlchemy models generated by OpenAlchemy are equivalent to the following
+traditional models file:
+
+.. literalinclude:: ../../../examples/mixins/models_traditional.py
+    :language: python
+    :linenos:
+
+OpenAlchemy will generate the following typed models:
+
+.. literalinclude:: ../../../examples/mixins/models_auto.py
+    :language: python
+    :linenos:

docs/source/index.rst

@@ -360,6 +360,8 @@ the documentation:
 +------------------------------+----------------------------------------------------+
 | :samp:`x-foreign-key-colum`  | :ref:`custom-foreign-key`                          |
 +------------------------------+----------------------------------------------------+
+| :samp:`x-mixins`             | :ref:`mixins`                                      |
++------------------------------+----------------------------------------------------+
 | :samp:`x-backrefs`           | :ref:`Models File Note <backrefs>`                 |
 +------------------------------+----------------------------------------------------+
 | :samp:`x-de-$ref`            | :ref:`from_dict Note <de-ref>`                     |

docs/source/technical_details/index.rst

@@ -12,3 +12,4 @@ Technical Details
    relationships
    inheritance
    model
+   mixins

docs/source/technical_details/inheritance.rst

@@ -120,9 +120,9 @@ The required :samp:`__mapper_args__` must be added using :samp:`x-kwargs`. For
 example, for :samp:`Employee`:
 
 .. code-block:: yaml
-   :linenos:
+    :linenos:
 
-   Employee:
+    Employee:
       type: object
       ...
       x-kwargs:

docs/source/technical_details/mixins.rst

@@ -0,0 +1,49 @@
+.. _mixins:
+
+Mixin Classes
+=============
+
+SQLAlchemy supports adding common functionality from a class to many other
+classes through mixin classes. OpenAlchemy supports this through the
+:samp:`x-mixins` extension property.
+
+.. seealso::
+
+    `SQLAlchemy mixin documentation <https://docs.sqlalchemy.org/en/13/orm/extensions/declarative/mixins.html#mixing-in-columns>`_
+      Documentation for SQLAlchemy mixin.
+
+The following rules apply to the :samp:`x-mixins` extension property:
+
+* it can either be a string or a list of strings each of which defines one of
+  the mixin classes and
+* each value must be the fully qualified dotted name of the class to use as the
+  mixin. Everything before the last dot will be used to import the module and
+  everything after will be used to retrieve the class from the module.
+
+The following example adds the :samp:`sqlalchemy_mixins.TimestampsMixin` to the
+:samp:`Employee` model:
+
+.. code-block:: yaml
+    :linenos:
+
+    Employee:
+      type: object
+      x-mixins: sqlalchemy_mixins.TimestampsMixin
+      ...
+
+Alternatively, multiple mixins can be defined using a list:
+
+.. code-block:: yaml
+    :linenos:
+
+    Employee:
+      type: object
+      x-mixins:
+        - sqlalchemy_mixins.TimestampsMixin
+        - sqlalchemy_mixins.EagerLoadMixin
+      ...
+
+.. seealso::
+
+    `sqlalchemy_mixins package <https://github.com/absent1706/sqlalchemy-mixins>`_
+      Package that defines some helpful SQLAlchemy mixins.

examples/mixins/models_traditional.py

@@ -9,6 +9,8 @@ class Employee(Base, TimestampsMixin):
     """Person that works for a company."""
 
     __tablename__ = "employee"
+    __abstract__ = False
+
     id = sa.Column(sa.Integer, primary_key=True, autoincrement=True)
     name = sa.Column(sa.String, index=True)
     division = sa.Column(sa.String, index=True)

tests/open_alchemy/test_model_factory.py

@@ -562,7 +562,10 @@ def test_mixin(monkeypatch):
     mixin_class = type(
         "Mixin1",
         (),
-        {"property_2": sqlalchemy.column.Column(sqlalchemy.column.Integer)},
+        {
+            "property_2": sqlalchemy.column.Column(sqlalchemy.column.Integer),
+            "__abstract__": True,
+        },
     )
     mock_import_module.return_value.Mixin1 = mixin_class
     monkeypatch.setattr(importlib, "import_module", mock_import_module)
@@ -581,6 +584,7 @@ def test_mixin(monkeypatch):
     )
 
     assert hasattr(model, "property_2")
+    assert model.__abstract__ is False
 
 
 class TestGetSchema: