docs

Author: CosmoV

README.md

@@ -8,6 +8,7 @@
 
 [![📖 Docs (gh-pages)](https://github.com/mts-ai/FastAPI-JSONAPI/actions/workflows/documentation.yaml/badge.svg)](https://mts-ai.github.io/FastAPI-JSONAPI/)
 
+
 # FastAPI-JSONAPI
 
 FastAPI-JSONAPI is a FastAPI extension for building REST APIs.
@@ -30,25 +31,61 @@ pip install FastAPI-JSONAPI
 Create a test.py file and copy the following code into it
 
 ```python
+import sys
+from collections.abc import AsyncIterator
 from contextlib import asynccontextmanager
 from pathlib import Path
 from typing import Any, ClassVar, Optional
+from typing import Union
 
 import uvicorn
-from fastapi import APIRouter, Depends, FastAPI
+from fastapi import Depends, FastAPI
+from fastapi.responses import ORJSONResponse as JSONResponse
 from pydantic import ConfigDict
+from sqlalchemy.engine import URL
 from sqlalchemy.engine import make_url
 from sqlalchemy.ext.asyncio import AsyncEngine, AsyncSession, async_sessionmaker, create_async_engine
 from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
 
-from fastapi_jsonapi import RoutersJSONAPI, init
-from fastapi_jsonapi.misc.sqla.generics.base import DetailViewBaseGeneric, ListViewBaseGeneric
+from fastapi_jsonapi import ApplicationBuilder
+from fastapi_jsonapi.misc.sqla.generics.base import ViewBaseGeneric
 from fastapi_jsonapi.schema_base import BaseModel
-from fastapi_jsonapi.views.utils import HTTPMethod, HTTPMethodConfig
-from fastapi_jsonapi.views.view_base import ViewBase
+from fastapi_jsonapi.views import ViewBase, Operation, OperationConfig
 
 CURRENT_DIR = Path(__file__).resolve().parent
-DB_URL = f"sqlite+aiosqlite:///{CURRENT_DIR}/db.sqlite3"
+sys.path.append(f"{CURRENT_DIR.parent.parent}")
+
+
+class DB:
+    def __init__(
+        self,
+        url: Union[str, URL],
+        echo: bool = False,
+        echo_pool: bool = False,
+    ):
+        self.engine: AsyncEngine = create_async_engine(
+            url=url,
+            echo=echo,
+            echo_pool=echo_pool,
+        )
+
+        self.session_maker: async_sessionmaker[AsyncSession] = async_sessionmaker(
+            autocommit=False,
+            bind=self.engine,
+            expire_on_commit=False,
+        )
+
+    async def dispose(self):
+        await self.engine.dispose()
+
+    async def session(self) -> AsyncIterator[AsyncSession]:
+        async with self.session_maker() as session:
+            yield session
+
+
+db = DB(
+    url=make_url(f"sqlite+aiosqlite:///{CURRENT_DIR}/db.sqlite3"),
+)
 
 
 class Base(DeclarativeBase):
@@ -62,64 +99,22 @@ class User(Base):
     name: Mapped[Optional[str]]
 
 
-class UserAttributesBaseSchema(BaseModel):
+class UserSchema(BaseModel):
+    """User base schema."""
+
     model_config = ConfigDict(
         from_attributes=True,
     )
 
     name: str
 
 
-class UserSchema(UserAttributesBaseSchema):
-    """User base schema."""
-
-
-class UserPatchSchema(UserAttributesBaseSchema):
-    """User PATCH schema."""
-
-
-class UserInSchema(UserAttributesBaseSchema):
-    """User input schema."""
-
-
-def async_session() -> tuple[AsyncEngine, async_sessionmaker]:
-    engine_: AsyncEngine = create_async_engine(
-        url=f"{make_url(DB_URL)}",
-        echo=True,
-    )
-    session_maker_: async_sessionmaker[AsyncSession] = async_sessionmaker(
-        autocommit=False,
-        bind=engine,
-        expire_on_commit=False,
-    )
-    return engine_, session_maker_
-
-
-engine, session_maker = async_session()
-
-
-class Connector:
-    @classmethod
-    async def dispose(cls):
-        await engine.dispose()
-
-    @classmethod
-    async def init(cls) -> None:
-        async with engine.begin() as conn:
-            await conn.run_sync(Base.metadata.create_all)
-
-    @classmethod
-    async def session(cls):
-        async with session_maker() as db_session:
-            yield db_session
-
-
 class SessionDependency(BaseModel):
     model_config = ConfigDict(
         arbitrary_types_allowed=True,
     )
 
-    session: AsyncSession = Depends(Connector.session)
+    session: AsyncSession = Depends(db.session)
 
 
 def session_dependency_handler(view: ViewBase, dto: SessionDependency) -> dict[str, Any]:
@@ -128,89 +123,67 @@ def session_dependency_handler(view: ViewBase, dto: SessionDependency) -> dict[s
     }
 
 
-class UserDetailView(DetailViewBaseGeneric):
-    method_dependencies: ClassVar[dict[HTTPMethod, HTTPMethodConfig]] = {
-        HTTPMethod.ALL: HTTPMethodConfig(
+class UserView(ViewBaseGeneric):
+    operation_dependencies: ClassVar = {
+        Operation.ALL: OperationConfig(
             dependencies=SessionDependency,
             prepare_data_layer_kwargs=session_dependency_handler,
-        )
-    }
-
-
-class UserListView(ListViewBaseGeneric):
-    method_dependencies: ClassVar[dict[HTTPMethod, HTTPMethodConfig]] = {
-        HTTPMethod.ALL: HTTPMethodConfig(
-            dependencies=SessionDependency,
-            prepare_data_layer_kwargs=session_dependency_handler,
-        )
+        ),
     }
 
 
 def add_routes(app: FastAPI):
-    tags = [
-        {
-            "name": "User",
-            "description": "",
-        },
-    ]
-
-    router: APIRouter = APIRouter()
-    RoutersJSONAPI(
-        router=router,
+    builder = ApplicationBuilder(app)
+    builder.add_resource(
         path="/users",
         tags=["User"],
-        class_detail=UserDetailView,
-        class_list=UserListView,
+        view=UserView,
         schema=UserSchema,
-        resource_type="user",
-        schema_in_patch=UserPatchSchema,
-        schema_in_post=UserInSchema,
         model=User,
+        resource_type="user",
     )
-
-    app.include_router(router, prefix="")
-    return tags
+    builder.initialize()
 
 
 # noinspection PyUnusedLocal
 @asynccontextmanager
 async def lifespan(app: FastAPI):
     add_routes(app)
-    init(app)
 
-    await Connector.init()
+    async with db.engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
 
     yield
 
-    await Connector.dispose()
+    await db.dispose()
 
 
 app = FastAPI(
-    lifespan=lifespan,
     title="FastAPI and SQLAlchemy",
+    lifespan=lifespan,
     debug=True,
-    openapi_url="/openapi.json",
+    default_response_class=JSONResponse,
     docs_url="/docs",
+    openapi_url="/openapi.json",
 )
 
 
 if __name__ == "__main__":
     uvicorn.run(
-        "main:app",
+        app,
         host="0.0.0.0",
         port=8080,
-        reload=True,
-        app_dir=f"{CURRENT_DIR}",
     )
 ```
 
 This example provides the following API structure:
 
-| URL               | method | endpoint    | Usage                     |
-|-------------------|--------|-------------|---------------------------|
-| `/users`          | GET    | user_list   | Get a collection of users |
-| `/users`          | POST   | user_list   | Create a user             |
-| `/users`          | DELETE | user_list   | Delete users              |
-| `/users/{obj_id}` | GET    | user_detail | Get user details          |
-| `/users/{obj_id}` | PATCH  | user_detail | Update a user             |
-| `/users/{obj_id}` | DELETE | user_detail | Delete a user             |
+| URL                | method | endpoint    | Usage                         |
+|--------------------|--------|-------------|-------------------------------|
+| `/users/`          | GET    | user_list   | Get a collection of users     |
+| `/users/`          | POST   | user_list   | Create a user                 |
+| `/users/`          | DELETE | user_list   | Delete users                  |
+| `/users/{obj_id}/` | GET    | user_detail | Get user details              |
+| `/users/{obj_id}/` | PATCH  | user_detail | Update a user                 |
+| `/users/{obj_id}/` | DELETE | user_detail | Delete a user                 |
+| `/operations/`     | POST   | atomic      | Create, update, delete users  |

docs/api_filtering_example.rst

@@ -6,14 +6,16 @@ Filtering API example
 
 
 
-Filter by jsonb contains
+Filter by jsonb contains. Before using the filter, you must define it and apply it
+to the schema as shown here :ref:`custom_sql_filtering`. Some useful  filters are
+defined in module **fastapi_jsonapi.types_metadata.custom_filter_sql.py**
 
 .. code-block:: json
 
     [
       {
         "name": "words",
-        "op": "jsonb_contains",
+        "op": "sqlite_json_contains",
         "val": {"location": "Moscow", "spam": "eggs"}
       }
     ]

docs/api_limited_methods_example.rst

@@ -8,23 +8,23 @@ For example, you want to create only GET, POST and GET LIST methods,
 so user can't update or delete any items.
 
 
-Set ``methods`` on Routers registration:
+Set ``operations`` on Routers registration:
 
 .. code-block:: python
 
-    RoutersJSONAPI(
+    builder = ApplicationBuilder(app)
+    builder.add_resource(
         router=router,
         path="/users",
         tags=["User"],
-        class_detail=UserDetailView,
-        class_list=UserListView,
+        view=UserView,
         schema=UserSchema,
         model=User,
         resource_type="user",
-        methods=[
-            RoutersJSONAPI.Methods.GET_LIST,
-            RoutersJSONAPI.Methods.POST,
-            RoutersJSONAPI.Methods.GET,
+        operations=[
+            Operation.GET_LIST,
+            Operation.POST,
+            Operation.GET,
         ],
     )
 

docs/changelog.rst

@@ -1,6 +1,39 @@
 Changelog
 #########
 
+**3.0.0**
+*********
+
+Backwards compatibility changes
+===============================
+* Removed support pydantic v1 by `@NatalyaGrigoreva`_
+* Minimal fastapi version up to fastapi>=0.112.3 by `@NatalyaGrigoreva`_
+* Updated minimal pydantic version pydantic>=2.6.0 by `@NatalyaGrigoreva`_
+* Added required dependency orjson>=3.10.0 by `@NatalyaGrigoreva`_
+* Updated framework api by `@NatalyaGrigoreva`_, `@CosmoV`_
+
+Features
+========
+* Added support of pydantic v2 by `@NatalyaGrigoreva`_
+* Improved sqla orm query building by `@NatalyaGrigoreva`_
+* Updated logic of creation custom sql filters by `@mahenzon`_
+* Several bugfixes by `@NatalyaGrigoreva`_
+
+Performance improvements
+========================
+
+* Updated ViewBase logic of response building by `@CosmoV`_
+* Added storages for application lifetime entities by `@CosmoV`_
+* Updated "fields" feature logic by `@CosmoV`_
+
+Authors
+"""""""
+
+* `@CosmoV`_
+* `@NatalyaGrigoreva`_
+* `@mahenzon`_
+
+
 **2.8.0**
 *********
 
@@ -69,7 +102,7 @@ Fix relationships filtering, refactor alchemy helpers
 
 * Fix filter by relationships by `@CosmoV`_ in `#52 <https://github.com/mts-ai/FastAPI-JSONAPI/pull/52>`_
 * Add Codecov by `@mahenzon`_ in `#72 <https://github.com/mts-ai/FastAPI-JSONAPI/pull/72>`_
-* Set RoutersJSONAPI class on AtomicViewHandler by `@mahenzon`_ in `#7b2557f <https://github.com/mts-ai/FastAPI-JSONAPI/commit/7b2557f9e341c1210200efce0f7b47c15d4cac4e>`_
+* Set ApplicationBuilder class on AtomicViewHandler by `@mahenzon`_ in `#7b2557f <https://github.com/mts-ai/FastAPI-JSONAPI/commit/7b2557f9e341c1210200efce0f7b47c15d4cac4e>`_
 
 Authors
 """""""
@@ -316,3 +349,4 @@ Enhancements and bug fixes
 .. _`@mahenzon`: https://github.com/mahenzon
 .. _`@CosmoV`: https://github.com/CosmoV
 .. _`@tpynio`: https://github.com/tpynio
+.. _`@NatalyaGrigoreva`: https://github.com/NatalyaGrigoreva

docs/configuration.rst

@@ -9,4 +9,3 @@ You have access to 5 configuration keys:
 * MAX_PAGE_SIZE: the maximum page size. If you specify a page size greater than this value you will receive a 400 Bad Request response.
 * MAX_INCLUDE_DEPTH: the maximum length of an include through schema relationships
 * ALLOW_DISABLE_PAGINATION: if you want to disallow to disable pagination you can set this configuration key to False
-* CATCH_EXCEPTIONS: if you want fastapi_jsonapi to catch all exceptions and return them as JsonApiException (default is True)