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

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

@@ -1,12 +1,13 @@
 Metadata-Version: 2.4
 Name: fastapi_viewsets
-Version: 1.3.0
+Version: 1.5.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
 
@@ -67,7 +76,7 @@ Django REST Framework-style ViewSets for FastAPI — auto-generate CRUD endpoint
 - **ORM-agnostic core** — pluggable adapters for SQLAlchemy (sync/async), Tortoise ORM, and Peewee (`ORM_TYPE` / optional extras).
 - **Typed, Pydantic-first responses** with OpenAPI tags and schemas generated from your `response_model`.
 - **Declarative eager loading** (`select_related` / `prefetch_related`) via an inner `RelatedConfig` class on Pydantic schemas — eliminates N+1 without touching the viewset.
-- **Built-in list pagination** (`limit` / `offset`), optional OAuth2 on selected operations, and room to grow for search and richer filters (see Roadmap).
+- **Built-in list pagination** (`limit` / `offset`), **server-side search**, **declarative ordering** and **advanced filters** (`eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `contains`, `in`) driven by an inner `ListConfig` class on Pydantic schemas, plus optional OAuth2 on selected operations.
 
 ## Feature matrix
 
@@ -77,8 +86,8 @@ Django REST Framework-style ViewSets for FastAPI — auto-generate CRUD endpoint
 | `limit` / `offset` on LIST | Supported | Supported | Supported | Supported |
 | OAuth2 on selected methods (`register`) | Supported | Supported | Supported | Supported |
 | Declarative eager loading (`select_related` / `prefetch_related`) | Supported | Supported | Supported (`prefetch_related`) | Supported (`select_related`) |
-| `search` query on LIST (server-side) | **Roadmap** | **Roadmap** | **Roadmap** | **Roadmap** |
-| Declarative ordering / advanced filters | **Roadmap** | **Roadmap** | **Roadmap** | **Roadmap** |
+| `search` query on LIST (server-side) | Supported | Supported | Supported | Supported |
+| Declarative ordering / advanced filters | Supported | Supported | Supported | Supported |
 
 ## Installation
 
@@ -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
 
 
@@ -664,26 +680,25 @@ def pagination_hint() -> str:
     return "limit and offset are parsed by `BaseViewset.list`"
 ```
 
-**Filtering** — `list` accepts `search`, but ORM adapters ignore it today; server-side search is on the Roadmap. Subclass `BaseViewset` and override `list()` with your own query until then.
+**Search, ordering and filters** — declare a `ListConfig` inner class on the response schema and the LIST endpoint gains `?search=`, `?ordering=` and whitelisted `?<field>` / `?<field>__<op>` query parameters, applied server-side by every ORM adapter:
 
 ```python
-from fastapi_viewsets import BaseViewset
-
-def filtering_hint() -> str:
-    """Explain that `search` is reserved; override `list` for real filters today."""
-    return "search parameter is not yet applied in adapters"
-```
-
-**Ordering** — there is no shared `order_by` helper yet; override `list()` with an ordered query or wait for the Roadmap.
+from pydantic import BaseModel
 
-```python
-from fastapi_viewsets import BaseViewset
+class ItemSchema(BaseModel):
+    id: int
+    name: str
+    status: str
 
-def ordering_hint() -> str:
-    """Note the absence of a built-in ordering helper on LIST endpoints."""
-    return "override list or wait for roadmap ordering helpers"
+    class ListConfig:
+        search_fields = ["name"]
+        ordering_fields = ["name", "id"]
+        ordering = ["-id"]
+        filters = ["status"]
 ```
 
+`GET /items?search=foo&ordering=name&status=active` then works out of the box. Operators: `ne`, `gt`, `gte`, `lt`, `lte`, `contains`, `in` (e.g. `?status__in=active,pending`). Fields outside the whitelist are ignored; ordering by an unknown field returns `400`. Without a `ListConfig`, LIST behaves exactly as before.
+
 ## Permissions and custom routes
 
 There is no `get_queryset` hook; scope queries by subclassing `BaseViewset` and overriding `list()`, `get_element()`, or related handlers. The class subclasses `APIRouter`, so attach extra endpoints with `add_api_route` **before** `register()` if paths must win over `/{id}`:
@@ -739,17 +754,17 @@ 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 |
+| Transaction helpers (`begin` / `atomic`) across adapters | future | Planned |
+| Range filters on dates (`date__range`) and null checks (`field__isnull`) | future | Planned |
+| Cross-relation search (searching through `select_related` fields) | future | Planned |
+
+Released: server-side `search` (v1.5.0), declarative ordering and advanced filters (v1.5.0).
 
 ## Comparison with alternatives
 
 | Approach | Developer experience | ORM support | Permissions | Filtering |
 | --- | --- | --- | --- | --- |
-| fastapi-viewsets | One `BaseViewset` registers CRUD routes | SQLAlchemy sync/async, Tortoise, Peewee via adapters | OAuth2 per logical method via `register` | `limit`/`offset` today; `search` and advanced filters on Roadmap |
+| fastapi-viewsets | One `BaseViewset` registers CRUD routes | SQLAlchemy sync/async, Tortoise, Peewee via adapters | OAuth2 per logical method via `register` | `limit`/`offset`, `search`, `ordering` and operator filters via `ListConfig` |
 | fastapi-crudrouter | CRUD-focused generators, less ViewSet-shaped | Primarily SQLAlchemy | Custom middleware/deps | Often extended manually |
 | Hand-rolled FastAPI | Full control, most boilerplate | Any ORM you integrate | Fully custom | Fully custom |
 

{fastapi_viewsets-1.3.0 → fastapi_viewsets-1.5.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
 
@@ -18,7 +21,7 @@ Django REST Framework-style ViewSets for FastAPI — auto-generate CRUD endpoint
 - **ORM-agnostic core** — pluggable adapters for SQLAlchemy (sync/async), Tortoise ORM, and Peewee (`ORM_TYPE` / optional extras).
 - **Typed, Pydantic-first responses** with OpenAPI tags and schemas generated from your `response_model`.
 - **Declarative eager loading** (`select_related` / `prefetch_related`) via an inner `RelatedConfig` class on Pydantic schemas — eliminates N+1 without touching the viewset.
-- **Built-in list pagination** (`limit` / `offset`), optional OAuth2 on selected operations, and room to grow for search and richer filters (see Roadmap).
+- **Built-in list pagination** (`limit` / `offset`), **server-side search**, **declarative ordering** and **advanced filters** (`eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `contains`, `in`) driven by an inner `ListConfig` class on Pydantic schemas, plus optional OAuth2 on selected operations.
 
 ## Feature matrix
 
@@ -28,8 +31,8 @@ Django REST Framework-style ViewSets for FastAPI — auto-generate CRUD endpoint
 | `limit` / `offset` on LIST | Supported | Supported | Supported | Supported |
 | OAuth2 on selected methods (`register`) | Supported | Supported | Supported | Supported |
 | Declarative eager loading (`select_related` / `prefetch_related`) | Supported | Supported | Supported (`prefetch_related`) | Supported (`select_related`) |
-| `search` query on LIST (server-side) | **Roadmap** | **Roadmap** | **Roadmap** | **Roadmap** |
-| Declarative ordering / advanced filters | **Roadmap** | **Roadmap** | **Roadmap** | **Roadmap** |
+| `search` query on LIST (server-side) | Supported | Supported | Supported | Supported |
+| Declarative ordering / advanced filters | Supported | Supported | Supported | Supported |
 
 ## Installation
 
@@ -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
 
 
@@ -615,26 +625,25 @@ def pagination_hint() -> str:
     return "limit and offset are parsed by `BaseViewset.list`"
 ```
 
-**Filtering** — `list` accepts `search`, but ORM adapters ignore it today; server-side search is on the Roadmap. Subclass `BaseViewset` and override `list()` with your own query until then.
+**Search, ordering and filters** — declare a `ListConfig` inner class on the response schema and the LIST endpoint gains `?search=`, `?ordering=` and whitelisted `?<field>` / `?<field>__<op>` query parameters, applied server-side by every ORM adapter:
 
 ```python
-from fastapi_viewsets import BaseViewset
-
-def filtering_hint() -> str:
-    """Explain that `search` is reserved; override `list` for real filters today."""
-    return "search parameter is not yet applied in adapters"
-```
-
-**Ordering** — there is no shared `order_by` helper yet; override `list()` with an ordered query or wait for the Roadmap.
+from pydantic import BaseModel
 
-```python
-from fastapi_viewsets import BaseViewset
+class ItemSchema(BaseModel):
+    id: int
+    name: str
+    status: str
 
-def ordering_hint() -> str:
-    """Note the absence of a built-in ordering helper on LIST endpoints."""
-    return "override list or wait for roadmap ordering helpers"
+    class ListConfig:
+        search_fields = ["name"]
+        ordering_fields = ["name", "id"]
+        ordering = ["-id"]
+        filters = ["status"]
 ```
 
+`GET /items?search=foo&ordering=name&status=active` then works out of the box. Operators: `ne`, `gt`, `gte`, `lt`, `lte`, `contains`, `in` (e.g. `?status__in=active,pending`). Fields outside the whitelist are ignored; ordering by an unknown field returns `400`. Without a `ListConfig`, LIST behaves exactly as before.
+
 ## Permissions and custom routes
 
 There is no `get_queryset` hook; scope queries by subclassing `BaseViewset` and overriding `list()`, `get_element()`, or related handlers. The class subclasses `APIRouter`, so attach extra endpoints with `add_api_route` **before** `register()` if paths must win over `/{id}`:
@@ -690,17 +699,17 @@ 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 |
+| Transaction helpers (`begin` / `atomic`) across adapters | future | Planned |
+| Range filters on dates (`date__range`) and null checks (`field__isnull`) | future | Planned |
+| Cross-relation search (searching through `select_related` fields) | future | Planned |
+
+Released: server-side `search` (v1.5.0), declarative ordering and advanced filters (v1.5.0).
 
 ## Comparison with alternatives
 
 | Approach | Developer experience | ORM support | Permissions | Filtering |
 | --- | --- | --- | --- | --- |
-| fastapi-viewsets | One `BaseViewset` registers CRUD routes | SQLAlchemy sync/async, Tortoise, Peewee via adapters | OAuth2 per logical method via `register` | `limit`/`offset` today; `search` and advanced filters on Roadmap |
+| fastapi-viewsets | One `BaseViewset` registers CRUD routes | SQLAlchemy sync/async, Tortoise, Peewee via adapters | OAuth2 per logical method via `register` | `limit`/`offset`, `search`, `ordering` and operator filters via `ListConfig` |
 | fastapi-crudrouter | CRUD-focused generators, less ViewSet-shaped | Primarily SQLAlchemy | Custom middleware/deps | Often extended manually |
 | Hand-rolled FastAPI | Full control, most boilerplate | Any ORM you integrate | Fully custom | Fully custom |
 

{fastapi_viewsets-1.3.0 → fastapi_viewsets-1.5.0}/fastapi_viewsets/__init__.py

@@ -9,7 +9,7 @@ from __future__ import annotations
 
 from typing import Any, Callable, Dict, List, Optional, Type, TypeVar, Union
 
-from fastapi import APIRouter, Body, Depends
+from fastapi import APIRouter, Body, Depends, Request
 from pydantic import BaseModel
 from sqlalchemy.orm import Session
 
@@ -94,9 +94,30 @@ class BaseViewset(_RegisterMixin, APIRouter):
         limit: Optional[int] = 10,
         offset: Optional[int] = 0,
         search: Optional[str] = None,
+        ordering: Optional[str] = None,
+        request: Request = None,
         token: str = Depends(_noop_dependency),
     ) -> List[ResponseModelType]:
-        """List items with ``limit``/``offset`` pagination."""
+        """List items with pagination, search, ordering and filters.
+
+        Query parameters (behaviour is driven by the response schema's
+        ``ListConfig`` — see :mod:`fastapi_viewsets.filtering`):
+
+        * ``limit`` / ``offset`` — pagination.
+        * ``search`` — case-insensitive substring match across
+          ``ListConfig.search_fields``.
+        * ``ordering`` — comma-separated fields, ``-`` prefix for
+          descending, validated against ``ListConfig.ordering_fields``.
+        * ``<field>`` / ``<field>__<op>`` — exact and comparison filters
+          on ``ListConfig.filters`` fields.
+        """
+        from fastapi_viewsets.filtering import (
+            get_list_config,
+            parse_filters,
+            parse_ordering_param,
+        )
+
+        config = get_list_config(self.response_model)
         return get_list_queryset(
             self.model,
             db_session=self.db_session,
@@ -104,6 +125,13 @@ class BaseViewset(_RegisterMixin, APIRouter):
             offset=offset,
             orm_adapter=self.orm_adapter,
             response_model=self.response_model,
+            search=search,
+            ordering=parse_ordering_param(
+                ordering, config.ordering_fields, config.ordering
+            ),
+            filters=parse_filters(request.query_params, config.filters)
+            if request is not None
+            else None,
         )
 
     def get_element(

{fastapi_viewsets-1.3.0 → fastapi_viewsets-1.5.0}/fastapi_viewsets/async_base.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 from typing import Any, Callable, Dict, List, Optional, Type, TypeVar, Union
 
-from fastapi import APIRouter, Body, Depends
+from fastapi import APIRouter, Body, Depends, Request
 from pydantic import BaseModel
 from sqlalchemy.ext.asyncio import AsyncSession
 
@@ -85,9 +85,30 @@ class AsyncBaseViewset(_RegisterMixin, APIRouter):
         limit: Optional[int] = 10,
         offset: Optional[int] = 0,
         search: Optional[str] = None,
+        ordering: Optional[str] = None,
+        request: Request = None,
         token: str = Depends(_noop_dependency),
     ) -> List[ResponseModelType]:
-        """List items with ``limit``/``offset`` pagination (async)."""
+        """List items with pagination, search, ordering and filters (async).
+
+        Query parameters (behaviour is driven by the response schema's
+        ``ListConfig`` — see :mod:`fastapi_viewsets.filtering`):
+
+        * ``limit`` / ``offset`` — pagination.
+        * ``search`` — case-insensitive substring match across
+          ``ListConfig.search_fields``.
+        * ``ordering`` — comma-separated fields, ``-`` prefix for
+          descending, validated against ``ListConfig.ordering_fields``.
+        * ``<field>`` / ``<field>__<op>`` — exact and comparison filters
+          on ``ListConfig.filters`` fields.
+        """
+        from fastapi_viewsets.filtering import (
+            get_list_config,
+            parse_filters,
+            parse_ordering_param,
+        )
+
+        config = get_list_config(self.response_model)
         return await get_list_queryset(
             self.model,
             db_session=self.db_session,
@@ -95,6 +116,13 @@ class AsyncBaseViewset(_RegisterMixin, APIRouter):
             offset=offset,
             orm_adapter=self.orm_adapter,
             response_model=self.response_model,
+            search=search,
+            ordering=parse_ordering_param(
+                ordering, config.ordering_fields, config.ordering
+            ),
+            filters=parse_filters(request.query_params, config.filters)
+            if request is not None
+            else None,
         )
 
     async def get_element(