fastapi-viewsets 1.3.0__tar.gz → 1.4.0__tar.gz

{fastapi_viewsets-1.3.0 → fastapi_viewsets-1.4.0}/PKG-INFO

@@ -1,12 +1,13 @@
 Metadata-Version: 2.4
 Name: fastapi_viewsets
-Version: 1.3.0
+Version: 1.4.0
 Summary: DRF-style viewsets for FastAPI with SQLAlchemy/Tortoise/Peewee adapters and Pydantic v2 support.
 Author: Alexander Valenchits
 License: MIT
 Project-URL: Homepage, https://github.com/svalench/fastapi_viewsets
+Project-URL: Documentation, https://svalench.github.io/fastapi_viewsets/
 Project-URL: Issues, https://github.com/svalench/fastapi_viewsets/issues
-Project-URL: Changelog, https://github.com/svalench/fastapi_viewsets/blob/main/RELEASE_NOTES.md
+Project-URL: Changelog, https://github.com/svalench/fastapi_viewsets/blob/master/RELEASE_NOTES.md
 Keywords: fastapi,viewsets,crud,sqlalchemy,tortoise,peewee,pydantic
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.9
@@ -14,6 +15,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Framework :: FastAPI
@@ -30,10 +32,10 @@ Requires-Dist: python-dotenv>=0.19.0
 Provides-Extra: sqlalchemy
 Requires-Dist: SQLAlchemy>=1.4.36; extra == "sqlalchemy"
 Provides-Extra: tortoise
-Requires-Dist: tortoise-orm>=0.20.0; extra == "tortoise"
+Requires-Dist: tortoise-orm<1.0,>=0.20.0; extra == "tortoise"
 Requires-Dist: asyncpg>=0.28.0; extra == "tortoise"
 Provides-Extra: peewee
-Requires-Dist: peewee>=3.17.0; extra == "peewee"
+Requires-Dist: peewee<4,>=3.17.0; extra == "peewee"
 Provides-Extra: test
 Requires-Dist: pytest>=7.0.0; extra == "test"
 Requires-Dist: pytest-asyncio>=0.21.0; extra == "test"
@@ -45,6 +47,10 @@ Provides-Extra: lint
 Requires-Dist: ruff>=0.5; extra == "lint"
 Requires-Dist: black>=24; extra == "lint"
 Requires-Dist: mypy>=1.8; extra == "lint"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.6; extra == "docs"
+Requires-Dist: mkdocs-material>=9.5; extra == "docs"
+Requires-Dist: pymdown-extensions>=10.7; extra == "docs"
 Dynamic: license-file
 
 # fastapi-viewsets
@@ -53,12 +59,15 @@ Django REST Framework-style ViewSets for FastAPI — auto-generate CRUD endpoint
 
 [![PyPI version](https://badge.fury.io/py/fastapi-viewsets.svg)](https://pypi.org/project/fastapi-viewsets/)
 [![Python versions](https://img.shields.io/pypi/pyversions/fastapi-viewsets.svg)](https://pypi.org/project/fastapi-viewsets/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://github.com/svalench/fastapi_viewsets/blob/main/LICENSE)
-[![CI](https://github.com/svalench/fastapi_viewsets/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/svalench/fastapi_viewsets/actions/workflows/test.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://github.com/svalench/fastapi_viewsets/blob/master/LICENSE)
+[![CI](https://github.com/svalench/fastapi_viewsets/actions/workflows/test.yml/badge.svg?branch=master)](https://github.com/svalench/fastapi_viewsets/actions/workflows/test.yml)
 [![codecov](https://codecov.io/gh/svalench/fastapi_viewsets/graph/badge.svg)](https://codecov.io/gh/svalench/fastapi_viewsets)
 [![Downloads/month](https://static.pepy.tech/badge/fastapi-viewsets/month)](https://pepy.tech/project/fastapi-viewsets)
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/svalench/fastapi_viewsets/pulls)
+[![Docs](https://img.shields.io/badge/docs-svalench.github.io-blue.svg)](https://svalench.github.io/fastapi_viewsets/)
+
+**Documentation:** [https://svalench.github.io/fastapi_viewsets/](https://svalench.github.io/fastapi_viewsets/)
 
 ## Why fastapi-viewsets
 
@@ -108,7 +117,7 @@ you need, and the URL shape for **PostgreSQL**, **MySQL**, and
 | --- | --- | --- | --- |
 | **SQLAlchemy (sync)** | `psycopg[binary]` or `psycopg2-binary` | `pymysql` or `mysqlclient` | `pyodbc` + ODBC Driver 17/18 |
 | **SQLAlchemy (async)** | `asyncpg` | `aiomysql` or `asyncmy` | `aioodbc` + ODBC Driver 17/18 |
-| **Tortoise ORM** | `asyncpg` (built-in) | `aiomysql` (built-in) | Not supported by Tortoise |
+| **Tortoise ORM** | `asyncpg` (included in `[tortoise]` extra) | `aiomysql` (install separately) | Not supported by Tortoise |
 | **Peewee** | `psycopg2-binary` | `pymysql` or `mysqlclient` | Not supported by this adapter |
 
 > The `SQLAlchemyAdapter` auto-converts a sync URL to its async
@@ -191,8 +200,9 @@ TORTOISE_APP_LABEL=models
 ```
 
 ```python
+from contextlib import asynccontextmanager
+
 from fastapi import FastAPI
-from tortoise import Tortoise
 
 from fastapi_viewsets import AsyncBaseViewset
 from fastapi_viewsets.orm.factory import ORMFactory
@@ -201,24 +211,19 @@ app = FastAPI()
 adapter = ORMFactory.get_default_adapter()  # built from the env vars above
 
 
-@app.on_event("startup")
-async def _init_tortoise() -> None:
-    """Open the Tortoise connection pool and create schema if needed.
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Open the Tortoise connection pool at startup.
 
-    The adapter also initializes Tortoise lazily on first DB call;
-    doing it here gives you control over schema creation.
+    The adapter also initialises Tortoise lazily on the first DB call;
+    calling ``initialize()`` here gives you control over schema creation
+    and avoids a cold-start penalty on the first request.
     """
-    await Tortoise.init(
-        db_url=adapter.database_url,
-        modules={adapter.app_label: adapter.models},
-    )
-    await Tortoise.generate_schemas(safe=True)
-
+    await adapter.initialize(generate_schemas=True)
+    yield
+    await adapter.close()
 
-@app.on_event("shutdown")
-async def _close_tortoise() -> None:
-    """Close the Tortoise connection pool."""
-    await Tortoise.close_connections()
+app = FastAPI(lifespan=lifespan)
 
 
 # Define your Tortoise models in app/models.py and pass them to AsyncBaseViewset.
@@ -236,6 +241,10 @@ async def _close_tortoise() -> None:
 # app.include_router(items)
 ```
 
+> **Note:** `generate_schemas=True` is convenient for development. In
+> production, use [Aerich](https://github.com/tortoise/aerich) or another
+> migration tool instead of auto-generating schemas at startup.
+>
 > **MSSQL is not supported by Tortoise ORM.** Use SQLAlchemy with
 > `aioodbc` for SQL Server.
 
@@ -314,6 +323,7 @@ Save as `main.py` in an empty folder and run `python main.py` or `uvicorn main:a
 from fastapi import FastAPI
 from pydantic import BaseModel, ConfigDict
 from sqlalchemy import Column, Integer, String
+from typing import Optional
 
 from fastapi_viewsets import BaseViewset
 from fastapi_viewsets.db_conf import Base, engine, get_session
@@ -333,7 +343,7 @@ class ItemSchema(BaseModel):
     """Pydantic model for request and response bodies."""
 
     model_config = ConfigDict(from_attributes=True)
-    id: int | None = None
+    id: Optional[int] = None
     name: str
 
 
@@ -423,9 +433,12 @@ package auto-converts `sqlite://` to `sqlite+aiosqlite://`,
 `postgresql://` to `postgresql+asyncpg://`, etc.
 
 ```python
+from contextlib import asynccontextmanager
+
 from fastapi import FastAPI
 from pydantic import BaseModel, ConfigDict
 from sqlalchemy import Column, Integer, String
+from typing import Optional
 
 from fastapi_viewsets import AsyncBaseViewset
 from fastapi_viewsets.db_conf import (
@@ -434,7 +447,16 @@ from fastapi_viewsets.db_conf import (
     get_async_session,
 )
 
-app = FastAPI()
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Create tables once on startup using the async engine."""
+    async with async_engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+    yield
+
+
+app = FastAPI(lifespan=lifespan)
 
 
 class Item(Base):
@@ -449,17 +471,10 @@ class ItemSchema(BaseModel):
     """Pydantic v2 schema reused as request and response model."""
 
     model_config = ConfigDict(from_attributes=True)
-    id: int | None = None
+    id: Optional[int] = None
     name: str
 
 
-@app.on_event("startup")
-async def _create_tables() -> None:
-    """Create tables once on startup using the async engine."""
-    async with async_engine.begin() as conn:
-        await conn.run_sync(Base.metadata.create_all)
-
-
 items = AsyncBaseViewset(
     endpoint="/items",
     model=Item,
@@ -624,6 +639,7 @@ from fastapi import FastAPI
 from fastapi.security import OAuth2PasswordBearer
 from pydantic import BaseModel, ConfigDict
 from sqlalchemy import Column, Integer, String
+from typing import Optional
 from fastapi_viewsets import BaseViewset
 from fastapi_viewsets.db_conf import Base, engine, get_session
 
@@ -642,7 +658,7 @@ class ItemSchema(BaseModel):
     """Pydantic schema for Item payloads and responses."""
 
     model_config = ConfigDict(from_attributes=True)
-    id: int | None = None
+    id: Optional[int] = None
     name: str
 
 
@@ -739,11 +755,10 @@ Details: [RELEASE_NOTES.md](RELEASE_NOTES.md), [RELEASE_1.2.0.md](RELEASE_1.2.0.
 
 | Item | Target | Status |
 | --- | --- | --- |
-| Dedicated `AsyncModelViewSet` ergonomics on top of SQLAlchemy 2.x async sessions | v1.2 | Planned |
-| First-class Tortoise ORM viewset examples and docs (`TortoiseModelViewSet` naming TBD) | v1.2 | Planned |
-| Async pagination helpers and transaction boundaries across adapters | v1.3 | Planned |
-| Nested Pydantic models with automatic eager-loading | v1.3 | **Done** |
-| Wire `search` on LIST to real database queries | v1.2 | Planned |
+| Wire `search` on LIST to real database queries | v1.4 | Planned |
+| Transaction helpers (`begin` / `atomic`) across adapters | v1.4 | Planned |
+| Declarative ordering (`order_by`) on LIST endpoints | v1.4 | Planned |
+| Advanced filters (`__gt`, `__lt`, `__in`) via query params | v1.5 | Planned |
 
 ## Comparison with alternatives
 

{fastapi_viewsets-1.3.0 → fastapi_viewsets-1.4.0}/README.md

@@ -4,12 +4,15 @@ Django REST Framework-style ViewSets for FastAPI — auto-generate CRUD endpoint
 
 [![PyPI version](https://badge.fury.io/py/fastapi-viewsets.svg)](https://pypi.org/project/fastapi-viewsets/)
 [![Python versions](https://img.shields.io/pypi/pyversions/fastapi-viewsets.svg)](https://pypi.org/project/fastapi-viewsets/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://github.com/svalench/fastapi_viewsets/blob/main/LICENSE)
-[![CI](https://github.com/svalench/fastapi_viewsets/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/svalench/fastapi_viewsets/actions/workflows/test.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://github.com/svalench/fastapi_viewsets/blob/master/LICENSE)
+[![CI](https://github.com/svalench/fastapi_viewsets/actions/workflows/test.yml/badge.svg?branch=master)](https://github.com/svalench/fastapi_viewsets/actions/workflows/test.yml)
 [![codecov](https://codecov.io/gh/svalench/fastapi_viewsets/graph/badge.svg)](https://codecov.io/gh/svalench/fastapi_viewsets)
 [![Downloads/month](https://static.pepy.tech/badge/fastapi-viewsets/month)](https://pepy.tech/project/fastapi-viewsets)
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/svalench/fastapi_viewsets/pulls)
+[![Docs](https://img.shields.io/badge/docs-svalench.github.io-blue.svg)](https://svalench.github.io/fastapi_viewsets/)
+
+**Documentation:** [https://svalench.github.io/fastapi_viewsets/](https://svalench.github.io/fastapi_viewsets/)
 
 ## Why fastapi-viewsets
 
@@ -59,7 +62,7 @@ you need, and the URL shape for **PostgreSQL**, **MySQL**, and
 | --- | --- | --- | --- |
 | **SQLAlchemy (sync)** | `psycopg[binary]` or `psycopg2-binary` | `pymysql` or `mysqlclient` | `pyodbc` + ODBC Driver 17/18 |
 | **SQLAlchemy (async)** | `asyncpg` | `aiomysql` or `asyncmy` | `aioodbc` + ODBC Driver 17/18 |
-| **Tortoise ORM** | `asyncpg` (built-in) | `aiomysql` (built-in) | Not supported by Tortoise |
+| **Tortoise ORM** | `asyncpg` (included in `[tortoise]` extra) | `aiomysql` (install separately) | Not supported by Tortoise |
 | **Peewee** | `psycopg2-binary` | `pymysql` or `mysqlclient` | Not supported by this adapter |
 
 > The `SQLAlchemyAdapter` auto-converts a sync URL to its async
@@ -142,8 +145,9 @@ TORTOISE_APP_LABEL=models
 ```
 
 ```python
+from contextlib import asynccontextmanager
+
 from fastapi import FastAPI
-from tortoise import Tortoise
 
 from fastapi_viewsets import AsyncBaseViewset
 from fastapi_viewsets.orm.factory import ORMFactory
@@ -152,24 +156,19 @@ app = FastAPI()
 adapter = ORMFactory.get_default_adapter()  # built from the env vars above
 
 
-@app.on_event("startup")
-async def _init_tortoise() -> None:
-    """Open the Tortoise connection pool and create schema if needed.
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Open the Tortoise connection pool at startup.
 
-    The adapter also initializes Tortoise lazily on first DB call;
-    doing it here gives you control over schema creation.
+    The adapter also initialises Tortoise lazily on the first DB call;
+    calling ``initialize()`` here gives you control over schema creation
+    and avoids a cold-start penalty on the first request.
     """
-    await Tortoise.init(
-        db_url=adapter.database_url,
-        modules={adapter.app_label: adapter.models},
-    )
-    await Tortoise.generate_schemas(safe=True)
-
+    await adapter.initialize(generate_schemas=True)
+    yield
+    await adapter.close()
 
-@app.on_event("shutdown")
-async def _close_tortoise() -> None:
-    """Close the Tortoise connection pool."""
-    await Tortoise.close_connections()
+app = FastAPI(lifespan=lifespan)
 
 
 # Define your Tortoise models in app/models.py and pass them to AsyncBaseViewset.
@@ -187,6 +186,10 @@ async def _close_tortoise() -> None:
 # app.include_router(items)
 ```
 
+> **Note:** `generate_schemas=True` is convenient for development. In
+> production, use [Aerich](https://github.com/tortoise/aerich) or another
+> migration tool instead of auto-generating schemas at startup.
+>
 > **MSSQL is not supported by Tortoise ORM.** Use SQLAlchemy with
 > `aioodbc` for SQL Server.
 
@@ -265,6 +268,7 @@ Save as `main.py` in an empty folder and run `python main.py` or `uvicorn main:a
 from fastapi import FastAPI
 from pydantic import BaseModel, ConfigDict
 from sqlalchemy import Column, Integer, String
+from typing import Optional
 
 from fastapi_viewsets import BaseViewset
 from fastapi_viewsets.db_conf import Base, engine, get_session
@@ -284,7 +288,7 @@ class ItemSchema(BaseModel):
     """Pydantic model for request and response bodies."""
 
     model_config = ConfigDict(from_attributes=True)
-    id: int | None = None
+    id: Optional[int] = None
     name: str
 
 
@@ -374,9 +378,12 @@ package auto-converts `sqlite://` to `sqlite+aiosqlite://`,
 `postgresql://` to `postgresql+asyncpg://`, etc.
 
 ```python
+from contextlib import asynccontextmanager
+
 from fastapi import FastAPI
 from pydantic import BaseModel, ConfigDict
 from sqlalchemy import Column, Integer, String
+from typing import Optional
 
 from fastapi_viewsets import AsyncBaseViewset
 from fastapi_viewsets.db_conf import (
@@ -385,7 +392,16 @@ from fastapi_viewsets.db_conf import (
     get_async_session,
 )
 
-app = FastAPI()
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Create tables once on startup using the async engine."""
+    async with async_engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+    yield
+
+
+app = FastAPI(lifespan=lifespan)
 
 
 class Item(Base):
@@ -400,17 +416,10 @@ class ItemSchema(BaseModel):
     """Pydantic v2 schema reused as request and response model."""
 
     model_config = ConfigDict(from_attributes=True)
-    id: int | None = None
+    id: Optional[int] = None
     name: str
 
 
-@app.on_event("startup")
-async def _create_tables() -> None:
-    """Create tables once on startup using the async engine."""
-    async with async_engine.begin() as conn:
-        await conn.run_sync(Base.metadata.create_all)
-
-
 items = AsyncBaseViewset(
     endpoint="/items",
     model=Item,
@@ -575,6 +584,7 @@ from fastapi import FastAPI
 from fastapi.security import OAuth2PasswordBearer
 from pydantic import BaseModel, ConfigDict
 from sqlalchemy import Column, Integer, String
+from typing import Optional
 from fastapi_viewsets import BaseViewset
 from fastapi_viewsets.db_conf import Base, engine, get_session
 
@@ -593,7 +603,7 @@ class ItemSchema(BaseModel):
     """Pydantic schema for Item payloads and responses."""
 
     model_config = ConfigDict(from_attributes=True)
-    id: int | None = None
+    id: Optional[int] = None
     name: str
 
 
@@ -690,11 +700,10 @@ Details: [RELEASE_NOTES.md](RELEASE_NOTES.md), [RELEASE_1.2.0.md](RELEASE_1.2.0.
 
 | Item | Target | Status |
 | --- | --- | --- |
-| Dedicated `AsyncModelViewSet` ergonomics on top of SQLAlchemy 2.x async sessions | v1.2 | Planned |
-| First-class Tortoise ORM viewset examples and docs (`TortoiseModelViewSet` naming TBD) | v1.2 | Planned |
-| Async pagination helpers and transaction boundaries across adapters | v1.3 | Planned |
-| Nested Pydantic models with automatic eager-loading | v1.3 | **Done** |
-| Wire `search` on LIST to real database queries | v1.2 | Planned |
+| Wire `search` on LIST to real database queries | v1.4 | Planned |
+| Transaction helpers (`begin` / `atomic`) across adapters | v1.4 | Planned |
+| Declarative ordering (`order_by`) on LIST endpoints | v1.4 | Planned |
+| Advanced filters (`__gt`, `__lt`, `__in`) via query params | v1.5 | Planned |
 
 ## Comparison with alternatives
 

{fastapi_viewsets-1.3.0 → fastapi_viewsets-1.4.0}/fastapi_viewsets/orm/tortoise_adapter.py

@@ -58,6 +58,28 @@ class TortoiseAdapter(BaseORMAdapter):
             }
             await Tortoise.init(config=db_config)
             self._initialized = True
+
+    async def initialize(self, generate_schemas: bool = False) -> None:
+        """Initialize the Tortoise connection pool.
+
+        Call this in your application lifespan to explicitly open the
+        connection at startup instead of relying on lazy initialisation.
+
+        Args:
+            generate_schemas: If True, call ``Tortoise.generate_schemas(safe=True)``
+                after init. Useful for development; use Aerich in production.
+        """
+        await self._ensure_initialized()
+        if generate_schemas:
+            await Tortoise.generate_schemas(safe=True)
+
+    async def close(self) -> None:
+        """Close all Tortoise connections.
+
+        Call this in your application lifespan shutdown handler.
+        """
+        await Tortoise.close_connections()
+        self._initialized = False
     
     def get_session(self):
         """Get synchronous database session.

{fastapi_viewsets-1.3.0 → fastapi_viewsets-1.4.0}/fastapi_viewsets.egg-info/PKG-INFO

@@ -1,12 +1,13 @@
 Metadata-Version: 2.4
 Name: fastapi_viewsets
-Version: 1.3.0
+Version: 1.4.0
 Summary: DRF-style viewsets for FastAPI with SQLAlchemy/Tortoise/Peewee adapters and Pydantic v2 support.
 Author: Alexander Valenchits
 License: MIT
 Project-URL: Homepage, https://github.com/svalench/fastapi_viewsets
+Project-URL: Documentation, https://svalench.github.io/fastapi_viewsets/
 Project-URL: Issues, https://github.com/svalench/fastapi_viewsets/issues
-Project-URL: Changelog, https://github.com/svalench/fastapi_viewsets/blob/main/RELEASE_NOTES.md
+Project-URL: Changelog, https://github.com/svalench/fastapi_viewsets/blob/master/RELEASE_NOTES.md
 Keywords: fastapi,viewsets,crud,sqlalchemy,tortoise,peewee,pydantic
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.9
@@ -14,6 +15,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Framework :: FastAPI
@@ -30,10 +32,10 @@ Requires-Dist: python-dotenv>=0.19.0
 Provides-Extra: sqlalchemy
 Requires-Dist: SQLAlchemy>=1.4.36; extra == "sqlalchemy"
 Provides-Extra: tortoise
-Requires-Dist: tortoise-orm>=0.20.0; extra == "tortoise"
+Requires-Dist: tortoise-orm<1.0,>=0.20.0; extra == "tortoise"
 Requires-Dist: asyncpg>=0.28.0; extra == "tortoise"
 Provides-Extra: peewee
-Requires-Dist: peewee>=3.17.0; extra == "peewee"
+Requires-Dist: peewee<4,>=3.17.0; extra == "peewee"
 Provides-Extra: test
 Requires-Dist: pytest>=7.0.0; extra == "test"
 Requires-Dist: pytest-asyncio>=0.21.0; extra == "test"
@@ -45,6 +47,10 @@ Provides-Extra: lint
 Requires-Dist: ruff>=0.5; extra == "lint"
 Requires-Dist: black>=24; extra == "lint"
 Requires-Dist: mypy>=1.8; extra == "lint"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.6; extra == "docs"
+Requires-Dist: mkdocs-material>=9.5; extra == "docs"
+Requires-Dist: pymdown-extensions>=10.7; extra == "docs"
 Dynamic: license-file
 
 # fastapi-viewsets
@@ -53,12 +59,15 @@ Django REST Framework-style ViewSets for FastAPI — auto-generate CRUD endpoint
 
 [![PyPI version](https://badge.fury.io/py/fastapi-viewsets.svg)](https://pypi.org/project/fastapi-viewsets/)
 [![Python versions](https://img.shields.io/pypi/pyversions/fastapi-viewsets.svg)](https://pypi.org/project/fastapi-viewsets/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://github.com/svalench/fastapi_viewsets/blob/main/LICENSE)
-[![CI](https://github.com/svalench/fastapi_viewsets/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/svalench/fastapi_viewsets/actions/workflows/test.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://github.com/svalench/fastapi_viewsets/blob/master/LICENSE)
+[![CI](https://github.com/svalench/fastapi_viewsets/actions/workflows/test.yml/badge.svg?branch=master)](https://github.com/svalench/fastapi_viewsets/actions/workflows/test.yml)
 [![codecov](https://codecov.io/gh/svalench/fastapi_viewsets/graph/badge.svg)](https://codecov.io/gh/svalench/fastapi_viewsets)
 [![Downloads/month](https://static.pepy.tech/badge/fastapi-viewsets/month)](https://pepy.tech/project/fastapi-viewsets)
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/svalench/fastapi_viewsets/pulls)
+[![Docs](https://img.shields.io/badge/docs-svalench.github.io-blue.svg)](https://svalench.github.io/fastapi_viewsets/)
+
+**Documentation:** [https://svalench.github.io/fastapi_viewsets/](https://svalench.github.io/fastapi_viewsets/)
 
 ## Why fastapi-viewsets
 
@@ -108,7 +117,7 @@ you need, and the URL shape for **PostgreSQL**, **MySQL**, and
 | --- | --- | --- | --- |
 | **SQLAlchemy (sync)** | `psycopg[binary]` or `psycopg2-binary` | `pymysql` or `mysqlclient` | `pyodbc` + ODBC Driver 17/18 |
 | **SQLAlchemy (async)** | `asyncpg` | `aiomysql` or `asyncmy` | `aioodbc` + ODBC Driver 17/18 |
-| **Tortoise ORM** | `asyncpg` (built-in) | `aiomysql` (built-in) | Not supported by Tortoise |
+| **Tortoise ORM** | `asyncpg` (included in `[tortoise]` extra) | `aiomysql` (install separately) | Not supported by Tortoise |
 | **Peewee** | `psycopg2-binary` | `pymysql` or `mysqlclient` | Not supported by this adapter |
 
 > The `SQLAlchemyAdapter` auto-converts a sync URL to its async
@@ -191,8 +200,9 @@ TORTOISE_APP_LABEL=models
 ```
 
 ```python
+from contextlib import asynccontextmanager
+
 from fastapi import FastAPI
-from tortoise import Tortoise
 
 from fastapi_viewsets import AsyncBaseViewset
 from fastapi_viewsets.orm.factory import ORMFactory
@@ -201,24 +211,19 @@ app = FastAPI()
 adapter = ORMFactory.get_default_adapter()  # built from the env vars above
 
 
-@app.on_event("startup")
-async def _init_tortoise() -> None:
-    """Open the Tortoise connection pool and create schema if needed.
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Open the Tortoise connection pool at startup.
 
-    The adapter also initializes Tortoise lazily on first DB call;
-    doing it here gives you control over schema creation.
+    The adapter also initialises Tortoise lazily on the first DB call;
+    calling ``initialize()`` here gives you control over schema creation
+    and avoids a cold-start penalty on the first request.
     """
-    await Tortoise.init(
-        db_url=adapter.database_url,
-        modules={adapter.app_label: adapter.models},
-    )
-    await Tortoise.generate_schemas(safe=True)
-
+    await adapter.initialize(generate_schemas=True)
+    yield
+    await adapter.close()
 
-@app.on_event("shutdown")
-async def _close_tortoise() -> None:
-    """Close the Tortoise connection pool."""
-    await Tortoise.close_connections()
+app = FastAPI(lifespan=lifespan)
 
 
 # Define your Tortoise models in app/models.py and pass them to AsyncBaseViewset.
@@ -236,6 +241,10 @@ async def _close_tortoise() -> None:
 # app.include_router(items)
 ```
 
+> **Note:** `generate_schemas=True` is convenient for development. In
+> production, use [Aerich](https://github.com/tortoise/aerich) or another
+> migration tool instead of auto-generating schemas at startup.
+>
 > **MSSQL is not supported by Tortoise ORM.** Use SQLAlchemy with
 > `aioodbc` for SQL Server.
 
@@ -314,6 +323,7 @@ Save as `main.py` in an empty folder and run `python main.py` or `uvicorn main:a
 from fastapi import FastAPI
 from pydantic import BaseModel, ConfigDict
 from sqlalchemy import Column, Integer, String
+from typing import Optional
 
 from fastapi_viewsets import BaseViewset
 from fastapi_viewsets.db_conf import Base, engine, get_session
@@ -333,7 +343,7 @@ class ItemSchema(BaseModel):
     """Pydantic model for request and response bodies."""
 
     model_config = ConfigDict(from_attributes=True)
-    id: int | None = None
+    id: Optional[int] = None
     name: str
 
 
@@ -423,9 +433,12 @@ package auto-converts `sqlite://` to `sqlite+aiosqlite://`,
 `postgresql://` to `postgresql+asyncpg://`, etc.
 
 ```python
+from contextlib import asynccontextmanager
+
 from fastapi import FastAPI
 from pydantic import BaseModel, ConfigDict
 from sqlalchemy import Column, Integer, String
+from typing import Optional
 
 from fastapi_viewsets import AsyncBaseViewset
 from fastapi_viewsets.db_conf import (
@@ -434,7 +447,16 @@ from fastapi_viewsets.db_conf import (
     get_async_session,
 )
 
-app = FastAPI()
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Create tables once on startup using the async engine."""
+    async with async_engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+    yield
+
+
+app = FastAPI(lifespan=lifespan)
 
 
 class Item(Base):
@@ -449,17 +471,10 @@ class ItemSchema(BaseModel):
     """Pydantic v2 schema reused as request and response model."""
 
     model_config = ConfigDict(from_attributes=True)
-    id: int | None = None
+    id: Optional[int] = None
     name: str
 
 
-@app.on_event("startup")
-async def _create_tables() -> None:
-    """Create tables once on startup using the async engine."""
-    async with async_engine.begin() as conn:
-        await conn.run_sync(Base.metadata.create_all)
-
-
 items = AsyncBaseViewset(
     endpoint="/items",
     model=Item,
@@ -624,6 +639,7 @@ from fastapi import FastAPI
 from fastapi.security import OAuth2PasswordBearer
 from pydantic import BaseModel, ConfigDict
 from sqlalchemy import Column, Integer, String
+from typing import Optional
 from fastapi_viewsets import BaseViewset
 from fastapi_viewsets.db_conf import Base, engine, get_session
 
@@ -642,7 +658,7 @@ class ItemSchema(BaseModel):
     """Pydantic schema for Item payloads and responses."""
 
     model_config = ConfigDict(from_attributes=True)
-    id: int | None = None
+    id: Optional[int] = None
     name: str
 
 
@@ -739,11 +755,10 @@ Details: [RELEASE_NOTES.md](RELEASE_NOTES.md), [RELEASE_1.2.0.md](RELEASE_1.2.0.
 
 | Item | Target | Status |
 | --- | --- | --- |
-| Dedicated `AsyncModelViewSet` ergonomics on top of SQLAlchemy 2.x async sessions | v1.2 | Planned |
-| First-class Tortoise ORM viewset examples and docs (`TortoiseModelViewSet` naming TBD) | v1.2 | Planned |
-| Async pagination helpers and transaction boundaries across adapters | v1.3 | Planned |
-| Nested Pydantic models with automatic eager-loading | v1.3 | **Done** |
-| Wire `search` on LIST to real database queries | v1.2 | Planned |
+| Wire `search` on LIST to real database queries | v1.4 | Planned |
+| Transaction helpers (`begin` / `atomic`) across adapters | v1.4 | Planned |
+| Declarative ordering (`order_by`) on LIST endpoints | v1.4 | Planned |
+| Advanced filters (`__gt`, `__lt`, `__in`) via query params | v1.5 | Planned |
 
 ## Comparison with alternatives
 

{fastapi_viewsets-1.3.0 → fastapi_viewsets-1.4.0}/fastapi_viewsets.egg-info/SOURCES.txt

@@ -40,5 +40,6 @@ tests/test_missing_coverage.py
 tests/test_orm_adapters.py
 tests/test_orm_adapters_extended.py
 tests/test_select_prefetch_related.py
+tests/test_tortoise_lifecycle.py
 tests/test_utils.py
 tests/test_viewsets_with_adapters.py

{fastapi_viewsets-1.3.0 → fastapi_viewsets-1.4.0}/fastapi_viewsets.egg-info/requires.txt

@@ -4,13 +4,18 @@ SQLAlchemy>=1.4.36
 pydantic<3,>=2.5
 python-dotenv>=0.19.0
 
+[docs]
+mkdocs>=1.6
+mkdocs-material>=9.5
+pymdown-extensions>=10.7
+
 [lint]
 ruff>=0.5
 black>=24
 mypy>=1.8
 
 [peewee]
-peewee>=3.17.0
+peewee<4,>=3.17.0
 
 [sqlalchemy]
 SQLAlchemy>=1.4.36
@@ -24,5 +29,5 @@ faker>=18.0.0
 aiosqlite>=0.19.0
 
 [tortoise]
-tortoise-orm>=0.20.0
+tortoise-orm<1.0,>=0.20.0
 asyncpg>=0.28.0

{fastapi_viewsets-1.3.0 → fastapi_viewsets-1.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "fastapi_viewsets"
-version = "1.3.0"
+version = "1.4.0"
 description = "DRF-style viewsets for FastAPI with SQLAlchemy/Tortoise/Peewee adapters and Pydantic v2 support."
 readme = "README.md"
 license = { text = "MIT" }
@@ -18,6 +18,7 @@ classifiers = [
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "License :: OSI Approved :: MIT License",
     "Operating System :: OS Independent",
     "Framework :: FastAPI",
@@ -34,8 +35,8 @@ dependencies = [
 
 [project.optional-dependencies]
 sqlalchemy = ["SQLAlchemy>=1.4.36"]
-tortoise = ["tortoise-orm>=0.20.0", "asyncpg>=0.28.0"]
-peewee = ["peewee>=3.17.0"]
+tortoise = ["tortoise-orm>=0.20.0,<1.0", "asyncpg>=0.28.0"]
+peewee = ["peewee>=3.17.0,<4"]
 test = [
     "pytest>=7.0.0",
     "pytest-asyncio>=0.21.0",
@@ -45,11 +46,13 @@ test = [
     "aiosqlite>=0.19.0",
 ]
 lint = ["ruff>=0.5", "black>=24", "mypy>=1.8"]
+docs = ["mkdocs>=1.6", "mkdocs-material>=9.5", "pymdown-extensions>=10.7"]
 
 [project.urls]
 Homepage = "https://github.com/svalench/fastapi_viewsets"
+Documentation = "https://svalench.github.io/fastapi_viewsets/"
 Issues = "https://github.com/svalench/fastapi_viewsets/issues"
-Changelog = "https://github.com/svalench/fastapi_viewsets/blob/main/RELEASE_NOTES.md"
+Changelog = "https://github.com/svalench/fastapi_viewsets/blob/master/RELEASE_NOTES.md"
 
 [tool.setuptools.packages.find]
 where = ["."]
@@ -58,7 +61,7 @@ exclude = ["tests*"]
 
 [tool.black]
 line-length = 100
-target-version = ["py39", "py310", "py311", "py312", "py313"]
+target-version = ["py39", "py310", "py311", "py312", "py313", "py314"]
 
 [tool.ruff]
 line-length = 100

{fastapi_viewsets-1.3.0 → fastapi_viewsets-1.4.0}/tests/test_adapter_methods_coverage.py

@@ -186,21 +186,18 @@ class TestTortoiseAdapterMethods:
         """Test Tortoise adapter get_list_queryset_async with offset."""
         try:
             from fastapi_viewsets.orm.tortoise_adapter import TortoiseAdapter
-            from tortoise.models import Model
-            from tortoise import fields
-            
+            from tests.tortoise_models import SimpleTortoiseModel as TestModel
+
             adapter = TortoiseAdapter(
-                database_url="sqlite:///test_tortoise_offset.db",
-                models=[],
+                database_url="sqlite://:memory:",
+                models=["tests.tortoise_models"],
                 app_label="test"
             )
-            
-            class TestModel(Model):
-                id = fields.IntField(pk=True)
-                name = fields.CharField(max_length=50)
-            
-            # Initialize
+
+            # Initialize and create the table
+            from tortoise import Tortoise
             await adapter._ensure_initialized()
+            await Tortoise.generate_schemas(safe=True)
             
             # Create test data
             await TestModel.create(name="test1")
@@ -228,20 +225,14 @@ class TestTortoiseAdapterMethods:
         """Test Tortoise adapter create_element_async validation."""
         try:
             from fastapi_viewsets.orm.tortoise_adapter import TortoiseAdapter
-            from tortoise.models import Model
-            from tortoise import fields
-            
+            from tests.tortoise_models import SimpleTortoiseModel as TestModel
+
             adapter = TortoiseAdapter(
-                database_url="sqlite:///test_tortoise_validation.db",
-                models=[],
+                database_url="sqlite://:memory:",
+                models=["tests.tortoise_models"],
                 app_label="test"
             )
-            
-            class TestModel(Model):
-                id = fields.IntField(pk=True)
-                name = fields.CharField(max_length=50, required=True)
-                value = fields.IntField(null=True)
-            
+
             await adapter._ensure_initialized()
             
             # Test missing required field
@@ -266,21 +257,17 @@ class TestTortoiseAdapterMethods:
         """Test Tortoise adapter update_element_async with PUT."""
         try:
             from fastapi_viewsets.orm.tortoise_adapter import TortoiseAdapter
-            from tortoise.models import Model
-            from tortoise import fields
-            
+            from tests.tortoise_models import SimpleTortoiseModel as TestModel
+
             adapter = TortoiseAdapter(
-                database_url="sqlite:///test_tortoise_put.db",
-                models=[],
+                database_url="sqlite://:memory:",
+                models=["tests.tortoise_models"],
                 app_label="test"
             )
-            
-            class TestModel(Model):
-                id = fields.IntField(pk=True)
-                name = fields.CharField(max_length=50)
-                value = fields.IntField(null=True)
-            
+
+            from tortoise import Tortoise
             await adapter._ensure_initialized()
+            await Tortoise.generate_schemas(safe=True)
             
             # Create test data
             obj = await TestModel.create(name="old", value=10)

{fastapi_viewsets-1.3.0 → fastapi_viewsets-1.4.0}/tests/test_exception_handling.py

@@ -280,21 +280,17 @@ class TestTortoiseAdapterExceptions:
         """Test Tortoise adapter create_element_async handles IntegrityError."""
         try:
             from fastapi_viewsets.orm.tortoise_adapter import TortoiseAdapter
-            from tortoise.models import Model
-            from tortoise import fields
-            from tortoise.exceptions import IntegrityError as TortoiseIntegrityError
+            from tests.tortoise_models import UniqueNameTortoiseModel as TestModel
             
             adapter = TortoiseAdapter(
-                database_url="sqlite:///test_tortoise_integrity.db",
-                models=[],
+                database_url="sqlite://:memory:",
+                models=["tests.tortoise_models"],
                 app_label="test"
             )
             
-            class TestModel(Model):
-                id = fields.IntField(pk=True)
-                name = fields.CharField(max_length=50, unique=True)
-            
+            from tortoise import Tortoise
             await adapter._ensure_initialized()
+            await Tortoise.generate_schemas(safe=True)
             
             # Create first record
             await TestModel.create(name="test1")
@@ -322,19 +318,14 @@ class TestTortoiseAdapterExceptions:
         """Test Tortoise adapter create_element_async handles generic Exception."""
         try:
             from fastapi_viewsets.orm.tortoise_adapter import TortoiseAdapter
-            from tortoise.models import Model
-            from tortoise import fields
+            from tests.tortoise_models import SimpleTortoiseModel as TestModel
             
             adapter = TortoiseAdapter(
-                database_url="sqlite:///test_tortoise_generic.db",
-                models=[],
+                database_url="sqlite://:memory:",
+                models=["tests.tortoise_models"],
                 app_label="test"
             )
             
-            class TestModel(Model):
-                id = fields.IntField(pk=True)
-                name = fields.CharField(max_length=50)
-            
             await adapter._ensure_initialized()
             
             # Mock create to raise generic exception
@@ -361,20 +352,17 @@ class TestTortoiseAdapterExceptions:
         """Test Tortoise adapter update_element_async with empty data."""
         try:
             from fastapi_viewsets.orm.tortoise_adapter import TortoiseAdapter
-            from tortoise.models import Model
-            from tortoise import fields
+            from tests.tortoise_models import SimpleTortoiseModel as TestModel
             
             adapter = TortoiseAdapter(
-                database_url="sqlite:///test_tortoise_empty.db",
-                models=[],
+                database_url="sqlite://:memory:",
+                models=["tests.tortoise_models"],
                 app_label="test"
             )
             
-            class TestModel(Model):
-                id = fields.IntField(pk=True)
-                name = fields.CharField(max_length=50)
-            
+            from tortoise import Tortoise
             await adapter._ensure_initialized()
+            await Tortoise.generate_schemas(safe=True)
             
             # Create test data
             obj = await TestModel.create(name="test")

{fastapi_viewsets-1.3.0 → fastapi_viewsets-1.4.0}/tests/test_missing_coverage.py

@@ -316,7 +316,8 @@ class TestMissingCoverage:
             assert result is True
             
             # Verify it's deleted
-            assert TestModel.get_by_id(obj_id) is None
+            with pytest.raises(TestModel.DoesNotExist):
+                TestModel.get_by_id(obj_id)
             
             # Test with non-existent id
             with pytest.raises(HTTPException) as exc_info:

fastapi_viewsets-1.4.0/tests/test_tortoise_lifecycle.py

@@ -0,0 +1,100 @@
+"""Tests for TortoiseAdapter public lifecycle methods (initialize/close).
+
+These tests use mocking so they run even when tortoise-orm is not installed
+(which is the case in CI — only the [test] extra is installed there).
+"""
+
+import pytest
+from unittest.mock import AsyncMock, MagicMock, patch
+
+from fastapi_viewsets.orm import tortoise_adapter as ta_module
+from fastapi_viewsets.orm.tortoise_adapter import TortoiseAdapter
+
+
+@pytest.fixture
+def adapter():
+    """Create a TortoiseAdapter for testing, mocking TORTOISE_AVAILABLE."""
+    with patch.object(ta_module, "TORTOISE_AVAILABLE", True):
+        adapter = TortoiseAdapter(
+            database_url="sqlite://:memory:",
+            models=["tests.models"],
+            app_label="models",
+        )
+    return adapter
+
+
+def _mock_tortoise():
+    """Create a MagicMock that simulates the Tortoise class."""
+    mock = MagicMock()
+    mock.generate_schemas = AsyncMock()
+    mock.close_connections = AsyncMock()
+    mock.init = AsyncMock()
+    return mock
+
+
+@pytest.mark.unit
+class TestTortoiseAdapterLifecycle:
+    """Tests for initialize() and close() public methods."""
+
+    @pytest.mark.async_test
+    async def test_initialize_without_schemas(self, adapter):
+        """initialize() calls _ensure_initialized but not generate_schemas."""
+        mock_tortoise = _mock_tortoise()
+        with patch.object(
+            adapter, "_ensure_initialized", new=AsyncMock()
+        ) as mock_init, patch.object(
+            ta_module, "Tortoise", mock_tortoise, create=True
+        ):
+            await adapter.initialize(generate_schemas=False)
+            mock_init.assert_awaited_once()
+            mock_tortoise.generate_schemas.assert_not_awaited()
+
+    @pytest.mark.async_test
+    async def test_initialize_with_schemas(self, adapter):
+        """initialize(generate_schemas=True) calls both init and generate_schemas."""
+        mock_tortoise = _mock_tortoise()
+        with patch.object(
+            adapter, "_ensure_initialized", new=AsyncMock()
+        ) as mock_init, patch.object(
+            ta_module, "Tortoise", mock_tortoise, create=True
+        ):
+            await adapter.initialize(generate_schemas=True)
+            mock_init.assert_awaited_once()
+            mock_tortoise.generate_schemas.assert_awaited_once_with(safe=True)
+
+    @pytest.mark.async_test
+    async def test_close_calls_tortoise_close(self, adapter):
+        """close() calls Tortoise.close_connections() and resets _initialized."""
+        mock_tortoise = _mock_tortoise()
+        adapter._initialized = True
+        with patch.object(
+            ta_module, "Tortoise", mock_tortoise, create=True
+        ):
+            await adapter.close()
+            mock_tortoise.close_connections.assert_awaited_once()
+            assert adapter._initialized is False
+
+    @pytest.mark.async_test
+    async def test_close_resets_initialized_even_if_already_false(self, adapter):
+        """close() works even when adapter was never initialized."""
+        mock_tortoise = _mock_tortoise()
+        assert adapter._initialized is False
+        with patch.object(
+            ta_module, "Tortoise", mock_tortoise, create=True
+        ):
+            await adapter.close()
+            mock_tortoise.close_connections.assert_awaited_once()
+            assert adapter._initialized is False
+
+    @pytest.mark.async_test
+    async def test_initialize_is_idempotent(self, adapter):
+        """Calling initialize() twice does not error."""
+        mock_tortoise = _mock_tortoise()
+        with patch.object(
+            adapter, "_ensure_initialized", new=AsyncMock()
+        ) as mock_init, patch.object(
+            ta_module, "Tortoise", mock_tortoise, create=True
+        ):
+            await adapter.initialize()
+            await adapter.initialize()
+            assert mock_init.await_count == 2