update changelog, minor fixes, add examples

Author: mahenzon

.github/workflows/testing.yml

@@ -24,7 +24,7 @@ jobs:
           python -m pip install --upgrade pip poetry pre-commit
           poetry config virtualenvs.create false --local
       - name: Install dependencies
-        run: poetry install
+        run: poetry install --extras "sqla"
       - name: Lint code
         run: pre-commit run --all-files
       - name: Test with pytest

docs/changelog.rst

@@ -1,16 +1,38 @@
 Changelog
-*********
+#########
+
 
 **0.4.0**
-=========
+*********
 
 Backward-incompatible changes, improvements, bug fixes
 ======================================================
 
-* Includes (see doc TODO link)
+* Includes (see :ref:`example with many-to-many <include_many_to_many>`:) - any level of includes is now supported (tested with 4);
+* View Classes generics (Detail View and List View);
+* View Classes now use instance-level methods (breaking change, previously ``classmethods`` were used);
+* Pydantic schemas now have to be inherited from custom BaseModel methods (breaking change
+, previously all schemas were supported
+). It uses custom :ref:`registry class <https://github.com/mts-ai/FastAPI-JSONAPI/blob/188093e967bb80b7a1f0a86e754a52e47f252044/fastapi_jsonapi/schema_base.py#L33>`:
+, so we can collect and resolve all schemas. Maybe there's some workaround to collect all known schemas;
+* Improved docs, request and response examples have more info, more schemas appear in docs;
+* Reworked schemas resolving and building;
+* Fixed filtering (schemas resolving fix);
+* Fixed filtering (schemas resolving fix);
+* Create custom sql filters :ref:`example <custom_sql_filtering>`:;
+* Add linters: black, ruff;
+* Add pre-commit;
+* Add autotests with pytest;
+* Add poetry, configure dependencies groups;
+* Add GitHub Action with linting and testing;
+* Upgrade examples;
+* Update docs.
+
+- `@mahenzon`_
+
 
 **0.2.1**
-=========
+*********
 
 Enhancements and bug fixes
 ==========================
@@ -19,7 +41,7 @@ Enhancements and bug fixes
 
 
 **0.2.0**
-=========
+*********
 
 Enhancements and bug fixes
 ==========================
@@ -29,3 +51,4 @@ Enhancements and bug fixes
 
 
 .. _`@znbiz`: https://github.com/znbiz
+.. _`@mahenzon`: https://github.com/mahenzon

docs/custom_filter_example.rst

@@ -0,0 +1,50 @@
+.. _custom_sql_filtering:
+
+Custom SQL filtering
+####################
+
+.. currentmodule:: fastapi_jsonapi
+
+Sometimes you need custom filtering that's not supported natively.
+You can define new filtering rules as in this example:
+
+
+
+Prepare pydantic schema which is used in RoutersJSONAPI as schema
+-----------------------------------------------------------------
+
+
+``schemas/picture.py``:
+
+.. literalinclude:: ../examples/custom_filter_example.py
+    :language: python
+
+
+Declare models as usual, create routes as usual.
+
+Search for objects
+------------------
+
+
+.. note::
+    Note that url has to be quoted. It's unquoted only for an example
+
+Request:
+
+.. sourcecode:: http
+
+    GET /pictures?filter=[{"name":"picture.meta","op":"jsonb_contains","val":{"location":"Moscow"}}]
+    Accept: application/vnd.api+json
+
+Filter value has to be a valid JSON:
+
+.. sourcecode:: JSON
+    [
+       {
+          "name":"picture.meta",
+          "op":"jsonb_contains",
+          "val":{
+             "location":"Moscow"
+          }
+       }
+    ]

docs/include_many_to_many.rst

@@ -1,63 +1,120 @@
 .. _include_many_to_many:
 
-Include related M2M
-===================
+Include nested and related Many-to-Many
+#######################################
 
 .. currentmodule:: fastapi_jsonapi
 
-The same as usual includes. Here's an example with an association object:
+The same as usual includes. Here's an example with an association object.
 
 Example (sources `here <https://github.com/mts-ai/FastAPI-JSONAPI/tree/main/examples/api_for_sqlalchemy>`_):
 
+Prepare models and schemas
+==========================
+
 
 Define SQLAlchemy models
-~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------
+
 
-Parent:
+Parent model
+^^^^^^^^^^^^
+
+``models/parent.py``:
 
 .. literalinclude:: ../examples/api_for_sqlalchemy/models/parent.py
     :language: python
 
 
-Child:
+
+Child model
+^^^^^^^^^^^
+
+``models/child.py``:
 
 .. literalinclude:: ../examples/api_for_sqlalchemy/models/child.py
     :language: python
 
 
-Parent to Child Association object:
+
+Parent to Child Association model
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``models/parent_child_association.py``:
 
 .. literalinclude:: ../examples/api_for_sqlalchemy/models/parent_child_association.py
     :language: python
 
 
 
+
 Define pydantic schemas
-~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------
 
 
-Parent Schema:
+Parent Schema
+^^^^^^^^^^^^^
+
+``schemas/parent.py``:
 
 .. literalinclude:: ../examples/api_for_sqlalchemy/models/schemas/parent.py
     :language: python
 
 
-Child Schema:
+Child Schema
+^^^^^^^^^^^^
+
+``schemas/child.py``:
 
 .. literalinclude:: ../examples/api_for_sqlalchemy/models/schemas/child.py
     :language: python
 
 
-Parent to Child Association Schema:
+Parent to Child Association Schema
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``schemas/parent_child_association.py``:
 
 .. literalinclude:: ../examples/api_for_sqlalchemy/models/schemas/parent_child_association.py
     :language: python
 
 
 
 
+Define view classes
+-------------------
+
+
+Base Views
+^^^^^^^^^^
+
+``api/base.py``:
+
+.. literalinclude:: ../examples/api_for_sqlalchemy/api/base.py
+    :language: python
+
+
+Parent Views
+^^^^^^^^^^^^
+
+``schemas/child.py``:
+
+.. literalinclude:: ../examples/api_for_sqlalchemy/api/parent.py
+    :language: python
+
+
+Child Views
+^^^^^^^^^^^
+
+``schemas/child.py``:
+
+.. literalinclude:: ../examples/api_for_sqlalchemy/api/child.py
+    :language: python
+
+
+
 List Parent objects with Children through an Association object
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------------------------------------------
 
 Request:
 

docs/index.rst

@@ -60,6 +60,7 @@ FastAPI-JSONAPI with FastAPI.
    filtering
    include_related_objects
    include_many_to_many
+   custom_sql_filtering
    sparse_fieldsets
    pagination
    sorting

docs/installation.rst

@@ -15,14 +15,14 @@ The development version can be downloaded from `its page at GitHub
 
     git clone https://github.com/mts-ai/FastAPI-JSONAPI.git
     cd fastapi-jsonapi
-    python3 -m venv venv
-    . ./venv/bin/activate
-    pip install -U pip
-    python setup.py install
-    pip install -r requirements-dev.txt
+    poetry install poetry install --all-extras
 
 .. note::
 
     If you don't have virtualenv please install it
 
     $ pip install virtualenv
+
+    If you don't have poetry please install it
+
+    $ pip install poetry

examples/api_for_sqlalchemy/models/schemas/child.py

@@ -5,8 +5,6 @@ class ChildBaseSchema(BaseModel):
     """Child base schema."""
 
     class Config:
-        """Pydantic schema config."""
-
         orm_mode = True
 
     name: str
@@ -21,11 +19,6 @@ class ChildInSchema(ChildBaseSchema):
 
 
 class ChildSchema(ChildInSchema):
-    """PostComment item schema."""
-
-    class Config:
-        """Pydantic model config."""
-
-        orm_mode = True
+    """Child item schema."""
 
     id: int

examples/api_for_sqlalchemy/models/schemas/parent.py

@@ -10,8 +10,6 @@ class ParentBaseSchema(BaseModel):
     """Parent base schema."""
 
     class Config:
-        """Pydantic schema config."""
-
         orm_mode = True
 
     name: str
@@ -26,15 +24,9 @@ class ParentInSchema(ParentBaseSchema):
 
 
 class ParentSchema(ParentInSchema):
-    """PostComment item schema."""
-
-    class Config:
-        """Pydantic model config."""
-
-        orm_mode = True
+    """Parent item schema."""
 
     id: int
-
     children: List["ParentToChildAssociationSchema"] = Field(
         relationship=RelationshipInfo(
             resource_type="parent_child_association",

examples/custom_filter_example.py

@@ -0,0 +1,39 @@
+from typing import Any
+
+from pydantic.fields import Field, ModelField
+from sqlalchemy.orm import InstrumentedAttribute
+
+from fastapi_jsonapi.schema_base import BaseModel
+
+
+def jsonb_contains_sql_filter(
+    schema_field: ModelField,
+    model_column: InstrumentedAttribute,
+    value: dict[Any, Any],
+    operator: str,
+) -> tuple[Any, list[Any]]:
+    """
+    Any SQLA (or Tortoise) magic here
+
+    :param schema_field:
+    :param model_column:
+    :param value: any dict
+    :param operator: value 'jsonb_contains'
+    :return: one sqla filter and list of joins
+    """
+    filter_sqla = model_column.op("@>")(value)
+    return filter_sqla, []
+
+
+class PictureSchema(BaseModel):
+    """
+    Now you can use `jsonb_contains` sql filter for this resource
+    """
+
+    name: str
+    meta: dict[Any, Any] = Field(
+        default_factory=dict,
+        description="Any additional info in JSON format.",
+        example={"location": "Moscow", "spam": "eggs"},
+        _jsonb_contains_sql_filter_=jsonb_contains_sql_filter,
+    )