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

fastapi_viewsets-1.5.2/MANIFEST.in

@@ -0,0 +1,3 @@
+include pytest.ini mkdocs.yml
+recursive-include tests *.py
+recursive-include docs *.md *.css

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi_viewsets
-Version: 1.5.0
+Version: 1.5.2
 Summary: DRF-style viewsets for FastAPI with SQLAlchemy/Tortoise/Peewee adapters and Pydantic v2 support.
 Author: Alexander Valenchits
 License: MIT
@@ -25,12 +25,10 @@ Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: fastapi>=0.110.0
-Requires-Dist: uvicorn>=0.17.6
-Requires-Dist: SQLAlchemy>=1.4.36
 Requires-Dist: pydantic<3,>=2.5
 Requires-Dist: python-dotenv>=0.19.0
 Provides-Extra: sqlalchemy
-Requires-Dist: SQLAlchemy>=1.4.36; extra == "sqlalchemy"
+Requires-Dist: SQLAlchemy[asyncio]>=2.0.0; extra == "sqlalchemy"
 Provides-Extra: tortoise
 Requires-Dist: tortoise-orm<1.0,>=0.20.0; extra == "tortoise"
 Requires-Dist: asyncpg>=0.28.0; extra == "tortoise"
@@ -43,6 +41,8 @@ Requires-Dist: pytest-cov>=4.0.0; extra == "test"
 Requires-Dist: httpx>=0.24.0; extra == "test"
 Requires-Dist: faker>=18.0.0; extra == "test"
 Requires-Dist: aiosqlite>=0.19.0; extra == "test"
+Requires-Dist: uvicorn>=0.17.6; extra == "test"
+Requires-Dist: SQLAlchemy[asyncio]>=2.0.0; extra == "test"
 Provides-Extra: lint
 Requires-Dist: ruff>=0.5; extra == "lint"
 Requires-Dist: black>=24; extra == "lint"
@@ -95,15 +95,21 @@ Django REST Framework-style ViewSets for FastAPI — auto-generate CRUD endpoint
 pip install fastapi-viewsets
 ```
 
-Optional extras (see `setup.py`):
+The base install is ORM-agnostic: it pulls in only FastAPI, Pydantic and
+python-dotenv. Pick your ORM via an extra (see `pyproject.toml`):
 
 ```bash
-pip install "fastapi-viewsets[sqlalchemy]"
+pip install "fastapi-viewsets[sqlalchemy]"   # SQLAlchemy 2.x, incl. asyncio support (greenlet)
 pip install "fastapi-viewsets[tortoise]"
 pip install "fastapi-viewsets[peewee]"
 pip install "fastapi-viewsets[test]"   # pytest, httpx, coverage, etc.
 ```
 
+For a local SQLite app, start with the
+[sync quickstart](#quickstart-sqlalchemy-sync); no separate database driver is needed.
+To execute the quickstart's `python main.py` (or serve any app) you also
+need an ASGI server, e.g. `pip install uvicorn`.
+
 For async SQLAlchemy you still need a driver such as `aiosqlite`, `asyncpg`, or `aiomysql` alongside your database URL.
 
 ## Database connection examples
@@ -432,6 +438,9 @@ an async-capable URL and use the lazy helpers from `db_conf`. The
 package auto-converts `sqlite://` to `sqlite+aiosqlite://`,
 `postgresql://` to `postgresql+asyncpg://`, etc.
 
+Save the following as `main.py` in an empty folder, then run
+`uvicorn main:app --reload`. Open `http://127.0.0.1:8000/docs` to try the API.
+
 ```python
 from contextlib import asynccontextmanager
 
@@ -492,10 +501,23 @@ Notes:
   `model_config = ConfigDict(from_attributes=True)` instead of the v1
   `class Config: orm_mode = True`.
 - `PATCH` uses `model_dump(exclude_unset=True)` internally, so unset
-  fields are no longer overwritten with defaults.
+  fields are no longer overwritten with defaults. Since v1.5.2 the PATCH
+  body is validated against an auto-generated all-optional variant of
+  your `response_model`, so partial bodies pass validation even when the
+  schema has required fields, and an explicit JSON `null` clears a
+  nullable column.
+- `PUT` replaces exactly the fields present in the payload; model
+  columns that are not part of the `response_model` are left untouched.
+- `POST` never sends an explicit `NULL` primary key to the database —
+  `id: Optional[int] = None` in the schema is safe on every adapter.
+- Integrity violations (e.g. duplicate unique values) return
+  `409 Conflict` with a sanitized message; raw SQL and driver internals
+  are never exposed in the response body.
 - If the async driver (`aiosqlite` / `asyncpg` / `aiomysql`) is not
   installed, sync usage still works — only `get_async_session()` raises
-  a helpful `RuntimeError`.
+  a helpful `RuntimeError`. The `sqlalchemy` extra installs
+  `SQLAlchemy[asyncio]`, which already includes `greenlet` for async
+  sessions.
 
 ## Overriding `list` and `create_element` (custom LIST and POST)
 
@@ -503,8 +525,11 @@ Every CRUD handler is a regular method, so subclassing the viewset is
 the canonical way to add filtering, ordering, validation, conflict
 handling, and so on. The example below subclasses `AsyncBaseViewset`
 and overrides both `list` (case-insensitive search + simple ordering)
-and `create_element` (input normalization + map `IntegrityError` to
-409).
+and `create_element` (input normalization + custom conflict message).
+
+> Since v1.5.2 the adapters themselves map `IntegrityError` to
+> `409 Conflict`; override `create_element` only when you need a custom
+> error payload or extra normalization.
 
 ```python
 from typing import List, Optional
@@ -670,7 +695,7 @@ app.include_router(router)
 
 ## Pagination, filtering, ordering
 
-**Pagination** — `BaseViewset.list` maps `limit` and `offset` to query parameters on the LIST route.
+**Pagination** — `BaseViewset.list` maps `limit` and `offset` to query parameters on the LIST route. Defaults are `limit=10`, `offset=0`; negative values are rejected with `422`, and `limit` is capped at `10000`.
 
 ```python
 from fastapi_viewsets import BaseViewset
@@ -731,6 +756,34 @@ class ItemsWithStats(BaseViewset):
 
 ## What is new
 
+### v1.5.2
+
+Bugfix release for the CRUD write paths (see
+[RELEASE_1.5.2.md](https://github.com/svalench/fastapi_viewsets/blob/master/RELEASE_1.5.2.md)):
+
+- **Multi-viewset apps fixed**: `register()` no longer leaks one viewset's
+  body schema into other viewsets — every `POST`/`PUT`/`PATCH` endpoint
+  now validates against its own `response_model`.
+- **PATCH is truly partial**: the PATCH body is validated against an
+  auto-generated all-optional variant of the response schema, and an
+  explicit JSON `null` clears a nullable column.
+- **PUT no longer nulls columns** that are absent from the Pydantic
+  schema.
+- **Integrity violations return `409 Conflict`** with a sanitized message
+  instead of `400` with raw SQL/driver internals.
+- **Create never passes an explicit `NULL` primary key** — fixes Tortoise
+  `POST` and PostgreSQL inserts with `id: Optional[int] = None` schemas.
+- **Pagination validated**: negative `limit`/`offset` rejected with `422`.
+- **Filters advertised in OpenAPI**: whitelisted `ListConfig.filters`
+  fields and their `__op` variants show up in Swagger UI.
+- **Leaner dependencies**: the base install no longer requires SQLAlchemy
+  or uvicorn; the `sqlalchemy` extra installs `SQLAlchemy[asyncio]`
+  (includes `greenlet`).
+
+Earlier releases: v1.5.0 (server-side `search`, declarative ordering and
+filters — [RELEASE_1.5.0.md](https://github.com/svalench/fastapi_viewsets/blob/master/RELEASE_1.5.0.md)),
+v1.4.0 ([RELEASE_1.4.0.md](https://github.com/svalench/fastapi_viewsets/blob/master/RELEASE_1.4.0.md)).
+
 ### v1.3.0
 
 - **Declarative eager loading** via `RelatedConfig` inside Pydantic schemas.  
@@ -746,9 +799,9 @@ class ItemsWithStats(BaseViewset):
 - Internal `register()` deduplicated between sync and async viewsets via a shared mixin.
 - PEP 621 `pyproject.toml`, `python_requires>=3.9`, FastAPI `>=0.110`, ruff/black/mypy preconfigured.
 
-Previous release: [v1.1.0](RELEASE_1.1.0.md) introduced multi-ORM support via adapters (SQLAlchemy default, optional Tortoise and Peewee), `ORMFactory` and environment-driven `ORM_TYPE` configuration.
+Previous release: [v1.1.0](https://github.com/svalench/fastapi_viewsets/blob/master/RELEASE_1.1.0.md) introduced multi-ORM support via adapters (SQLAlchemy default, optional Tortoise and Peewee), `ORMFactory` and environment-driven `ORM_TYPE` configuration.
 
-Details: [RELEASE_NOTES.md](RELEASE_NOTES.md), [RELEASE_1.2.0.md](RELEASE_1.2.0.md), [RELEASE_1.1.0.md](RELEASE_1.1.0.md).
+Details: [RELEASE_NOTES.md](https://github.com/svalench/fastapi_viewsets/blob/master/RELEASE_NOTES.md), [RELEASE_1.2.0.md](https://github.com/svalench/fastapi_viewsets/blob/master/RELEASE_1.2.0.md), [RELEASE_1.1.0.md](https://github.com/svalench/fastapi_viewsets/blob/master/RELEASE_1.1.0.md).
 
 ## Roadmap (planned)
 
@@ -773,6 +826,7 @@ Released: server-side `search` (v1.5.0), declarative ordering and advanced filte
 From the repository root (see `pytest.ini`):
 
 ```bash
+python -m pip install -e ".[test]"
 pytest
 ```
 
@@ -784,7 +838,7 @@ See [open issues](https://github.com/svalench/fastapi_viewsets/issues) to propos
 
 ## License
 
-Distributed under the MIT License. See [LICENSE](LICENSE).
+Distributed under the MIT License. See [LICENSE](https://github.com/svalench/fastapi_viewsets/blob/master/LICENSE).
 
 ## Author
 

{fastapi_viewsets-1.5.0 → fastapi_viewsets-1.5.2}/README.md

@@ -40,15 +40,21 @@ Django REST Framework-style ViewSets for FastAPI — auto-generate CRUD endpoint
 pip install fastapi-viewsets
 ```
 
-Optional extras (see `setup.py`):
+The base install is ORM-agnostic: it pulls in only FastAPI, Pydantic and
+python-dotenv. Pick your ORM via an extra (see `pyproject.toml`):
 
 ```bash
-pip install "fastapi-viewsets[sqlalchemy]"
+pip install "fastapi-viewsets[sqlalchemy]"   # SQLAlchemy 2.x, incl. asyncio support (greenlet)
 pip install "fastapi-viewsets[tortoise]"
 pip install "fastapi-viewsets[peewee]"
 pip install "fastapi-viewsets[test]"   # pytest, httpx, coverage, etc.
 ```
 
+For a local SQLite app, start with the
+[sync quickstart](#quickstart-sqlalchemy-sync); no separate database driver is needed.
+To execute the quickstart's `python main.py` (or serve any app) you also
+need an ASGI server, e.g. `pip install uvicorn`.
+
 For async SQLAlchemy you still need a driver such as `aiosqlite`, `asyncpg`, or `aiomysql` alongside your database URL.
 
 ## Database connection examples
@@ -377,6 +383,9 @@ an async-capable URL and use the lazy helpers from `db_conf`. The
 package auto-converts `sqlite://` to `sqlite+aiosqlite://`,
 `postgresql://` to `postgresql+asyncpg://`, etc.
 
+Save the following as `main.py` in an empty folder, then run
+`uvicorn main:app --reload`. Open `http://127.0.0.1:8000/docs` to try the API.
+
 ```python
 from contextlib import asynccontextmanager
 
@@ -437,10 +446,23 @@ Notes:
   `model_config = ConfigDict(from_attributes=True)` instead of the v1
   `class Config: orm_mode = True`.
 - `PATCH` uses `model_dump(exclude_unset=True)` internally, so unset
-  fields are no longer overwritten with defaults.
+  fields are no longer overwritten with defaults. Since v1.5.2 the PATCH
+  body is validated against an auto-generated all-optional variant of
+  your `response_model`, so partial bodies pass validation even when the
+  schema has required fields, and an explicit JSON `null` clears a
+  nullable column.
+- `PUT` replaces exactly the fields present in the payload; model
+  columns that are not part of the `response_model` are left untouched.
+- `POST` never sends an explicit `NULL` primary key to the database —
+  `id: Optional[int] = None` in the schema is safe on every adapter.
+- Integrity violations (e.g. duplicate unique values) return
+  `409 Conflict` with a sanitized message; raw SQL and driver internals
+  are never exposed in the response body.
 - If the async driver (`aiosqlite` / `asyncpg` / `aiomysql`) is not
   installed, sync usage still works — only `get_async_session()` raises
-  a helpful `RuntimeError`.
+  a helpful `RuntimeError`. The `sqlalchemy` extra installs
+  `SQLAlchemy[asyncio]`, which already includes `greenlet` for async
+  sessions.
 
 ## Overriding `list` and `create_element` (custom LIST and POST)
 
@@ -448,8 +470,11 @@ Every CRUD handler is a regular method, so subclassing the viewset is
 the canonical way to add filtering, ordering, validation, conflict
 handling, and so on. The example below subclasses `AsyncBaseViewset`
 and overrides both `list` (case-insensitive search + simple ordering)
-and `create_element` (input normalization + map `IntegrityError` to
-409).
+and `create_element` (input normalization + custom conflict message).
+
+> Since v1.5.2 the adapters themselves map `IntegrityError` to
+> `409 Conflict`; override `create_element` only when you need a custom
+> error payload or extra normalization.
 
 ```python
 from typing import List, Optional
@@ -615,7 +640,7 @@ app.include_router(router)
 
 ## Pagination, filtering, ordering
 
-**Pagination** — `BaseViewset.list` maps `limit` and `offset` to query parameters on the LIST route.
+**Pagination** — `BaseViewset.list` maps `limit` and `offset` to query parameters on the LIST route. Defaults are `limit=10`, `offset=0`; negative values are rejected with `422`, and `limit` is capped at `10000`.
 
 ```python
 from fastapi_viewsets import BaseViewset
@@ -676,6 +701,34 @@ class ItemsWithStats(BaseViewset):
 
 ## What is new
 
+### v1.5.2
+
+Bugfix release for the CRUD write paths (see
+[RELEASE_1.5.2.md](https://github.com/svalench/fastapi_viewsets/blob/master/RELEASE_1.5.2.md)):
+
+- **Multi-viewset apps fixed**: `register()` no longer leaks one viewset's
+  body schema into other viewsets — every `POST`/`PUT`/`PATCH` endpoint
+  now validates against its own `response_model`.
+- **PATCH is truly partial**: the PATCH body is validated against an
+  auto-generated all-optional variant of the response schema, and an
+  explicit JSON `null` clears a nullable column.
+- **PUT no longer nulls columns** that are absent from the Pydantic
+  schema.
+- **Integrity violations return `409 Conflict`** with a sanitized message
+  instead of `400` with raw SQL/driver internals.
+- **Create never passes an explicit `NULL` primary key** — fixes Tortoise
+  `POST` and PostgreSQL inserts with `id: Optional[int] = None` schemas.
+- **Pagination validated**: negative `limit`/`offset` rejected with `422`.
+- **Filters advertised in OpenAPI**: whitelisted `ListConfig.filters`
+  fields and their `__op` variants show up in Swagger UI.
+- **Leaner dependencies**: the base install no longer requires SQLAlchemy
+  or uvicorn; the `sqlalchemy` extra installs `SQLAlchemy[asyncio]`
+  (includes `greenlet`).
+
+Earlier releases: v1.5.0 (server-side `search`, declarative ordering and
+filters — [RELEASE_1.5.0.md](https://github.com/svalench/fastapi_viewsets/blob/master/RELEASE_1.5.0.md)),
+v1.4.0 ([RELEASE_1.4.0.md](https://github.com/svalench/fastapi_viewsets/blob/master/RELEASE_1.4.0.md)).
+
 ### v1.3.0
 
 - **Declarative eager loading** via `RelatedConfig` inside Pydantic schemas.  
@@ -691,9 +744,9 @@ class ItemsWithStats(BaseViewset):
 - Internal `register()` deduplicated between sync and async viewsets via a shared mixin.
 - PEP 621 `pyproject.toml`, `python_requires>=3.9`, FastAPI `>=0.110`, ruff/black/mypy preconfigured.
 
-Previous release: [v1.1.0](RELEASE_1.1.0.md) introduced multi-ORM support via adapters (SQLAlchemy default, optional Tortoise and Peewee), `ORMFactory` and environment-driven `ORM_TYPE` configuration.
+Previous release: [v1.1.0](https://github.com/svalench/fastapi_viewsets/blob/master/RELEASE_1.1.0.md) introduced multi-ORM support via adapters (SQLAlchemy default, optional Tortoise and Peewee), `ORMFactory` and environment-driven `ORM_TYPE` configuration.
 
-Details: [RELEASE_NOTES.md](RELEASE_NOTES.md), [RELEASE_1.2.0.md](RELEASE_1.2.0.md), [RELEASE_1.1.0.md](RELEASE_1.1.0.md).
+Details: [RELEASE_NOTES.md](https://github.com/svalench/fastapi_viewsets/blob/master/RELEASE_NOTES.md), [RELEASE_1.2.0.md](https://github.com/svalench/fastapi_viewsets/blob/master/RELEASE_1.2.0.md), [RELEASE_1.1.0.md](https://github.com/svalench/fastapi_viewsets/blob/master/RELEASE_1.1.0.md).
 
 ## Roadmap (planned)
 
@@ -718,6 +771,7 @@ Released: server-side `search` (v1.5.0), declarative ordering and advanced filte
 From the repository root (see `pytest.ini`):
 
 ```bash
+python -m pip install -e ".[test]"
 pytest
 ```
 
@@ -729,7 +783,7 @@ See [open issues](https://github.com/svalench/fastapi_viewsets/issues) to propos
 
 ## License
 
-Distributed under the MIT License. See [LICENSE](LICENSE).
+Distributed under the MIT License. See [LICENSE](https://github.com/svalench/fastapi_viewsets/blob/master/LICENSE).
 
 ## Author
 

fastapi_viewsets-1.5.2/docs/api-reference.md

@@ -0,0 +1,311 @@
+# API Reference
+
+## `BaseViewset`
+
+```python
+from fastapi_viewsets import BaseViewset
+```
+
+Synchronous CRUD viewset. Subclasses `APIRouter` and `_RegisterMixin`. Provides `LIST`, `GET`, `POST`, `PUT`, `PATCH`, and `DELETE` endpoints generated from an ORM model and a Pydantic response model.
+
+### Constructor
+
+```python
+BaseViewset(
+    *,
+    allowed_methods: Optional[List[str]] = None,
+    endpoint: Optional[str] = None,
+    model: Optional[Type[ModelType]] = None,
+    db_session: Optional[Callable[[], Any]] = None,
+    response_model: Optional[Type[BaseModel]] = None,
+    orm_adapter: Optional[BaseORMAdapter] = None,
+    **kwargs,  # forwarded to APIRouter
+)
+```
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `allowed_methods` | `Optional[List[str]]` | `None` | Override of `ALLOWED_METHODS` |
+| `endpoint` | `Optional[str]` | `None` | Base endpoint path, e.g. `"/user"` |
+| `model` | `Optional[Type]` | `None` | ORM model class |
+| `db_session` | `Optional[Callable]` | `None` | Database session factory function |
+| `response_model` | `Optional[Type[BaseModel]]` | `None` | Pydantic schema for request/response bodies |
+| `orm_adapter` | `Optional[BaseORMAdapter]` | `None` | ORM adapter; resolved from config when omitted |
+| `**kwargs` | — | — | Forwarded to `fastapi.APIRouter` (e.g. `tags`, `prefix`, `dependencies`) |
+
+### CRUD handlers
+
+#### `list()`
+
+```python
+def list(
+    self,
+    limit: Optional[int] = 10,
+    offset: Optional[int] = 0,
+    search: Optional[str] = None,
+    token: str = Depends(_noop_dependency),
+) -> List[ResponseModelType]
+```
+
+List items with `limit`/`offset` pagination. Returns a list of `response_model` instances.
+
+!!! warning "`search` parameter is reserved"
+
+    The `search` parameter is accepted by `list()` and appears in the
+    OpenAPI schema, but ORM adapters currently ignore it. Server-side
+    search is planned for v1.4. Until then, override `list()` in a
+    subclass to implement filtering — see
+    [Pagination & Filtering](pagination-filtering.md).
+
+#### `get_element()`
+
+```python
+def get_element(
+    self,
+    id: Union[int, str],
+    token: str = Depends(_noop_dependency),
+) -> ResponseModelType
+```
+
+Retrieve a single item by ID. Raises `404` if `id` is empty or `None`.
+
+#### `create_element()`
+
+```python
+def create_element(
+    self,
+    item: ResponseModelType = Body(...),
+    token: str = Depends(_noop_dependency),
+) -> ResponseModelType
+```
+
+Create a new item from the request body.
+
+#### `update_element()`
+
+```python
+def update_element(
+    self,
+    id: Union[int, str],
+    item: ResponseModelType = Body(...),
+    token: str = Depends(_noop_dependency),
+    partial: bool = False,
+) -> ResponseModelType
+```
+
+Update an existing item. `partial=True` (used by `PATCH`) only writes fields the client explicitly set, preserving correct PATCH semantics under Pydantic v2.
+
+#### `delete_element()`
+
+```python
+def delete_element(
+    self,
+    id: Union[int, str],
+    token: str = Depends(_noop_dependency),
+) -> Dict[str, Union[bool, str]]
+```
+
+Delete an item by ID. Returns `{"status": True, "text": "successfully deleted"}` or `{"status": False, "text": "deletion failed"}`.
+
+---
+
+## `AsyncBaseViewset`
+
+```python
+from fastapi_viewsets import AsyncBaseViewset
+```
+
+Asynchronous CRUD viewset. Mirrors `BaseViewset` but every CRUD handler is `async`, backed by an async-capable ORM adapter (SQLAlchemy `AsyncSession` or Tortoise ORM).
+
+### Constructor
+
+Same parameters as `BaseViewset`, but `db_session` should be an async session factory (`Callable[[], AsyncSession]`).
+
+### CRUD handlers
+
+Identical signatures to `BaseViewset`, but `async def`:
+
+- `async def list(...)`
+- `async def get_element(...)`
+- `async def create_element(...)`
+- `async def update_element(...)`
+- `async def delete_element(...)`
+
+---
+
+## `register()`
+
+```python
+def register(
+    self,
+    methods: Optional[List[str]] = None,
+    oauth_protect: Optional[OAuth2PasswordBearer] = None,
+    protected_methods: Optional[List[str]] = None,
+) -> None
+```
+
+Register CRUD endpoints on the router.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `methods` | `Optional[List[str]]` | `None` (all) | Logical methods to register |
+| `oauth_protect` | `Optional[OAuth2PasswordBearer]` | `None` | OAuth2 dependency for protected operations |
+| `protected_methods` | `Optional[List[str]]` | `None` | Subset of `methods` requiring the bearer token |
+
+### Allowed methods
+
+```python
+ALLOWED_METHODS = ["LIST", "POST", "GET", "PUT", "PATCH", "DELETE"]
+```
+
+### Method-to-route mapping
+
+| Logical method | HTTP method | Path | Handler | Response |
+| --- | --- | --- | --- | --- |
+| `LIST` | `GET` | `/` | `list` | `List[response_model]` |
+| `GET` | `GET` | `/{id}` | `get_element` | `response_model` |
+| `POST` | `POST` | `/` | `create_element` | `response_model` |
+| `PUT` | `PUT` | `/{id}` | `update_element` (`partial=False`) | `response_model` |
+| `PATCH` | `PATCH` | `/{id}` | `update_element` (`partial=True`) | `response_model` |
+| `DELETE` | `DELETE` | `/{id}` | `delete_element` | `None` (raw dict) |
+
+---
+
+## `ORMFactory`
+
+```python
+from fastapi_viewsets.orm.factory import ORMFactory
+```
+
+Central entry point for adapter resolution.
+
+### Methods
+
+| Method | Returns | Description |
+| --- | --- | --- |
+| `get_default_adapter()` | `BaseORMAdapter` | Returns the cached singleton adapter for the current `ORM_TYPE` |
+| `create_adapter(orm_type, config)` | `BaseORMAdapter` | Creates a new adapter instance from a dict config |
+| `register_adapter(orm_type, adapter_class)` | `None` | Registers a custom adapter class (e.g. for a new ORM) |
+| `get_adapter_from_env()` | `BaseORMAdapter` | Builds an adapter from environment variables (used internally by `get_default_adapter`) |
+| `reset_default_adapter()` | `None` | Clears the cached singleton; the next `get_default_adapter()` call rebuilds from env. Useful in tests and hot-reload scenarios. |
+
+---
+
+## `BaseORMAdapter`
+
+```python
+from fastapi_viewsets.orm.base import BaseORMAdapter
+```
+
+Abstract base class for ORM adapters. All adapters (SQLAlchemy, Tortoise, Peewee) implement this interface.
+
+### Abstract methods
+
+| Method | Sync/Async | Description |
+| --- | --- | --- |
+| `get_session()` | Sync | Get a synchronous database session |
+| `get_async_session()` | Sync | Get an async database session |
+| `get_base()` | Sync | Get the base class for ORM models |
+| `get_list_queryset(model, db_session, limit, offset, select_related, prefetch_related)` | Sync | Get a paginated list of model instances |
+| `get_list_queryset_async(model, db_session, limit, offset, select_related, prefetch_related)` | Async | Async version of `get_list_queryset` |
+| `get_element_by_id(model, db_session, id, select_related, prefetch_related)` | Sync | Get a single element by ID |
+| `get_element_by_id_async(model, db_session, id, select_related, prefetch_related)` | Async | Async version of `get_element_by_id` |
+| `create_element(model, db_session, data)` | Sync | Create a new element |
+| `create_element_async(model, db_session, data)` | Async | Async version of `create_element` |
+| `update_element(model, db_session, id, data, partial)` | Sync | Update an element (`partial=True` for PATCH) |
+| `update_element_async(model, db_session, id, data, partial)` | Async | Async version of `update_element` |
+| `delete_element(model, db_session, id)` | Sync | Delete an element by ID |
+| `delete_element_async(model, db_session, id)` | Async | Async version of `delete_element` |
+| `get_model_columns(model)` | Sync | Get column information for a model |
+
+---
+
+## `db_conf` module
+
+```python
+from fastapi_viewsets.db_conf import (
+    ORM_TYPE,
+    SQLALCHEMY_DATABASE_URL,
+    get_orm_adapter,
+    # Lazy SQLAlchemy globals:
+    engine,
+    Base,
+    SessionLocal,
+    db_session,
+    get_session,
+    async_engine,
+    AsyncSessionLocal,
+    get_async_session,
+)
+```
+
+### Environment variables
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `ORM_TYPE` | `sqlalchemy` | Active ORM: `sqlalchemy`, `tortoise`, or `peewee` |
+| `DATABASE_URL` | `sqlite:///<cwd>/base.db` | Generic database URL (fallback) |
+| `SQLALCHEMY_DATABASE_URL` | — | SQLAlchemy-specific URL |
+| `SQLALCHEMY_ASYNC_DATABASE_URL` | Auto-derived | Explicit async URL (overrides auto-conversion) |
+| `TORTOISE_DATABASE_URL` | — | Tortoise database URL |
+| `TORTOISE_MODELS` | — | JSON list of model modules, e.g. `["app.models"]` |
+| `TORTOISE_APP_LABEL` | `models` | Tortoise app label |
+| `PEEWEE_DATABASE_URL` | — | Peewee database URL |
+
+### Lazy resolution
+
+SQLAlchemy globals (`engine`, `Base`, `get_session`, `get_async_session`, etc.) are resolved lazily on first access. Importing the package does not create engines unless they are needed, and works without async drivers installed.
+
+---
+
+## Serializer utilities
+
+```python
+from fastapi_viewsets.serializer_utils import get_select_related, get_prefetch_related
+```
+
+These helpers read eager-loading configuration from a Pydantic schema's inner `RelatedConfig` class. They are used internally by `get_list_queryset` and `get_element_by_id` (sync and async) when a `response_model` is provided.
+
+| Function | Returns | Description |
+| --- | --- | --- |
+| `get_select_related(response_model)` | `List[str]` | Reads `RelatedConfig.select_related` (FK / many-to-one relations) |
+| `get_prefetch_related(response_model)` | `List[str]` | Reads `RelatedConfig.prefetch_related` (collections / M2M relations) |
+
+See [Eager Loading](eager-loading.md) for usage examples.
+
+---
+
+## Internal auth placeholder
+
+The `token` parameter on every CRUD handler defaults to `Depends(_noop_dependency)`, where `_noop_dependency` is a private function that returns `None`. It is overridden when `oauth_protect` is passed to `register()`. The backward-compatible alias `butle` also points to this function.
+
+You should not import `_noop_dependency` directly. If you override a handler and want to preserve the optional-auth behaviour, use `Depends(lambda: None)` or your own no-op dependency.
+
+---
+
+## Constants
+
+```python
+from fastapi_viewsets.constants import ALLOWED_METHODS, MAP_METHODS
+```
+
+### `ALLOWED_METHODS`
+
+```python
+ALLOWED_METHODS = ["LIST", "POST", "GET", "PUT", "PATCH", "DELETE"]
+```
+
+### `MAP_METHODS`
+
+Maps logical method names to their route specifications:
+
+```python
+MAP_METHODS = {
+    "GET":    {"method": "get_element",    "http_method": "GET",    "path": "/{id}", "is_list": False},
+    "POST":   {"method": "create_element", "http_method": "POST",   "path": "",      "is_list": False},
+    "PUT":    {"method": "update_element", "http_method": "PUT",    "path": "/{id}", "is_list": False},
+    "PATCH":  {"method": "update_element", "http_method": "PATCH",  "path": "/{id}", "is_list": False},
+    "DELETE": {"method": "delete_element", "http_method": "DELETE", "path": "/{id}", "is_list": False},
+    "LIST":   {"method": "list",           "http_method": "GET",    "path": "",      "is_list": True},
+}
+```

fastapi_viewsets-1.5.2/docs/assets/custom.css

@@ -0,0 +1,25 @@
+/* fastapi-viewsets docs custom styles */
+
+.md-header__title {
+  font-weight: 700;
+}
+
+.md-typeset__table td:not(:last-child),
+.md-typeset__table th:not(:last-child) {
+  padding-right: 1.2rem;
+}
+
+.md-typeset .grid.cards > ul > li {
+  border: 1px solid var(--md-default-fg-color--lightest);
+  border-radius: 0.4rem;
+  transition: border-color 0.25s, box-shadow 0.25s;
+}
+
+.md-typeset .grid.cards > ul > li:hover {
+  border-color: var(--md-accent-fg-color);
+  box-shadow: 0 0 0.2rem var(--md-accent-fg-color);
+}
+
+.md-typeset code {
+  font-size: 0.85em;
+}