docs: add documentation versioning

* feat/add WatchedFieldsMixin and watch_fields decorator for field-change monitoring

* docs: add WatchedFieldsMixin

* feat: add on_event, on_create and on_delete

* docs: update README

.github/workflows/docs.yml

@@ -5,7 +5,7 @@ on:
     types: [published]
 
 permissions:
-  contents: read
+  contents: write
   pages: write
   id-token: write
 
@@ -16,9 +16,14 @@ jobs:
       url: ${{ steps.deployment.outputs.page_url }}
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/configure-pages@v5
-
       - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Configure git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
 
       - name: Install uv
         uses: astral-sh/setup-uv@v7
@@ -26,9 +31,22 @@ jobs:
       - name: Set up Python
         run: uv python install 3.13
 
-      - run: uv sync --group dev
+      - run: uv sync --group docs
 
-      - run: uv run zensical build --clean
+      - name: Install mkdocs shim
+        run: cp scripts/mkdocs .venv/bin/mkdocs && chmod +x .venv/bin/mkdocs
+
+      - name: Deploy docs version
+        run: |
+          VERSION="${GITHUB_REF_NAME#v}"
+          MINOR_VERSION="${VERSION%.*}"
+          uv run mike deploy --push --update-aliases "$MINOR_VERSION" latest
+          uv run mike set-default --push latest
+
+      - name: Prepare site artifact
+        run: git worktree add site gh-pages
+
+      - uses: actions/configure-pages@v5
 
       - uses: actions/upload-pages-artifact@v4
         with:

README.md

@@ -20,7 +20,7 @@ A modular collection of production-ready utilities for FastAPI. Install only wha
 
 ## Installation
 
-The base package includes the core modules (CRUD, database, schemas, exceptions, fixtures, dependencies, logging):
+The base package includes the core modules (CRUD, database, schemas, exceptions, fixtures, dependencies, model mixins, logging):
 
 ```bash
 uv add fastapi-toolsets
@@ -29,9 +29,9 @@ uv add fastapi-toolsets
 Install only the extras you need:
 
 ```bash
-uv add "fastapi-toolsets[cli]"      # CLI (typer)
+uv add "fastapi-toolsets[cli]"
-uv add "fastapi-toolsets[metrics]"  # Prometheus metrics (prometheus_client)
+uv add "fastapi-toolsets[metrics]"
-uv add "fastapi-toolsets[pytest]"   # Pytest helpers (httpx, pytest-xdist)
+uv add "fastapi-toolsets[pytest]"
 ```
 
 Or install everything:
@@ -48,7 +48,8 @@ uv add "fastapi-toolsets[all]"
 - **Database**: Session management, transaction helpers, table locking, and polling-based row change detection
 - **Dependencies**: FastAPI dependency factories (`PathDependency`, `BodyDependency`) for automatic DB lookups from path or body parameters
 - **Fixtures**: Fixture system with dependency management, context support, and pytest integration
-- **Standardized API Responses**: Consistent response format with `Response`, `PaginatedResponse`, and `PydanticBase`
+- **Model Mixins**: SQLAlchemy mixins for common column patterns (`UUIDMixin`, `UUIDv7Mixin`, `CreatedAtMixin`, `UpdatedAtMixin`, `TimestampMixin`) and lifecycle callbacks (`WatchedFieldsMixin`, `@watch`) that fire after commit for insert, update, and delete events
+- **Standardized API Responses**: Consistent response format with `Response`, `ErrorResponse`, `PaginatedResponse`, `CursorPaginatedResponse` and `OffsetPaginatedResponse`.
 - **Exception Handling**: Structured error responses with automatic OpenAPI documentation
 - **Logging**: Logging configuration with uvicorn integration via `configure_logging` and `get_logger`
 

docs/examples/pagination-search.md

@@ -42,12 +42,17 @@ Declare `searchable_fields`, `facet_fields`, and `order_fields` once on [`CrudFa
 
 
 ## Routes
+
+```python title="routes.py:1:17"
+--8<-- "docs_src/examples/pagination_search/routes.py:1:17"
+```
+
 ### Offset pagination
 
 Best for admin panels or any UI that needs a total item count and numbered pages.
 
-```python title="routes.py:1:36"
+```python title="routes.py:20:40"
---8<-- "docs_src/examples/pagination_search/routes.py:1:36"
+--8<-- "docs_src/examples/pagination_search/routes.py:20:40"
 ```
 
 **Example request**
@@ -61,6 +66,7 @@ GET /articles/offset?page=2&items_per_page=10&search=fastapi&status=published&or
 ```json
 {
   "status": "SUCCESS",
+  "pagination_type": "offset",
   "data": [
     { "id": "3f47ac69-...", "title": "FastAPI tips", "status": "published", ... }
   ],
@@ -83,8 +89,8 @@ GET /articles/offset?page=2&items_per_page=10&search=fastapi&status=published&or
 
 Best for feeds, infinite scroll, or any high-throughput API where offset performance degrades.
 
-```python title="routes.py:39:59"
+```python title="routes.py:43:63"
---8<-- "docs_src/examples/pagination_search/routes.py:39:59"
+--8<-- "docs_src/examples/pagination_search/routes.py:43:63"
 ```
 
 **Example request**
@@ -98,6 +104,7 @@ GET /articles/cursor?items_per_page=10&status=published&order_by=created_at&orde
 ```json
 {
   "status": "SUCCESS",
+  "pagination_type": "cursor",
   "data": [
     { "id": "3f47ac69-...", "title": "FastAPI tips", "status": "published", ... }
   ],
@@ -116,6 +123,47 @@ GET /articles/cursor?items_per_page=10&status=published&order_by=created_at&orde
 
 Pass `next_cursor` as the `cursor` query parameter on the next request to advance to the next page.
 
+### Unified endpoint (both strategies)
+
+!!! info "Added in `v2.3.0`"
+
+[`paginate()`](../module/crud.md#unified-paginate--both-strategies-on-one-endpoint) lets a single endpoint support both strategies via a `pagination_type` query parameter. The `pagination_type` field in the response acts as a discriminator for frontend tooling.
+
+```python title="routes.py:66:90"
+--8<-- "docs_src/examples/pagination_search/routes.py:66:90"
+```
+
+**Offset request** (default)
+
+```
+GET /articles/?pagination_type=offset&page=1&items_per_page=10
+```
+
+```json
+{
+  "status": "SUCCESS",
+  "pagination_type": "offset",
+  "data": ["..."],
+  "pagination": { "total_count": 42, "page": 1, "items_per_page": 10, "has_more": true }
+}
+```
+
+**Cursor request**
+
+```
+GET /articles/?pagination_type=cursor&items_per_page=10
+GET /articles/?pagination_type=cursor&items_per_page=10&cursor=eyJ2YWx1ZSI6...
+```
+
+```json
+{
+  "status": "SUCCESS",
+  "pagination_type": "cursor",
+  "data": ["..."],
+  "pagination": { "next_cursor": "eyJ2YWx1ZSI6...", "prev_cursor": null, "items_per_page": 10, "has_more": true }
+}
+```
+
 ## Search behaviour
 
 Both endpoints inherit the same `searchable_fields` declared on `ArticleCrud`:

docs/index.md

@@ -20,7 +20,7 @@ A modular collection of production-ready utilities for FastAPI. Install only wha
 
 ## Installation
 
-The base package includes the core modules (CRUD, database, schemas, exceptions, fixtures, dependencies, logging):
+The base package includes the core modules (CRUD, database, schemas, exceptions, fixtures, dependencies, model mixins, logging):
 
 ```bash
 uv add fastapi-toolsets
@@ -29,9 +29,9 @@ uv add fastapi-toolsets
 Install only the extras you need:
 
 ```bash
-uv add "fastapi-toolsets[cli]"      # CLI (typer)
+uv add "fastapi-toolsets[cli]"
-uv add "fastapi-toolsets[metrics]"  # Prometheus metrics (prometheus_client)
+uv add "fastapi-toolsets[metrics]"
-uv add "fastapi-toolsets[pytest]"   # Pytest helpers (httpx, pytest-xdist)
+uv add "fastapi-toolsets[pytest]"
 ```
 
 Or install everything:
@@ -44,11 +44,12 @@ uv add "fastapi-toolsets[all]"
 
 ### Core
 
-- **CRUD**: Generic async CRUD operations with `CrudFactory`, built-in full-text/faceted search and offset/cursor pagination.
+- **CRUD**: Generic async CRUD operations with `CrudFactory`, built-in full-text/faceted search and Offset/Cursor pagination.
 - **Database**: Session management, transaction helpers, table locking, and polling-based row change detection
 - **Dependencies**: FastAPI dependency factories (`PathDependency`, `BodyDependency`) for automatic DB lookups from path or body parameters
 - **Fixtures**: Fixture system with dependency management, context support, and pytest integration
-- **Standardized API Responses**: Consistent response format with `Response`, `PaginatedResponse`, and `PydanticBase`
+- **Model Mixins**: SQLAlchemy mixins for common column patterns (`UUIDMixin`, `UUIDv7Mixin`, `CreatedAtMixin`, `UpdatedAtMixin`, `TimestampMixin`) and lifecycle callbacks (`WatchedFieldsMixin`) that fire after commit for insert, update, and delete events.
+- **Standardized API Responses**: Consistent response format with `Response`, `ErrorResponse`, `PaginatedResponse`, `CursorPaginatedResponse` and `OffsetPaginatedResponse`.
 - **Exception Handling**: Structured error responses with automatic OpenAPI documentation
 - **Logging**: Logging configuration with uvicorn integration via `configure_logging` and `get_logger`
 

docs/migration/v2.md

@@ -0,0 +1,137 @@
+# Migrating to v2.0
+
+This page covers every breaking change introduced in **v2.0** and the steps required to update your code.
+
+---
+
+## CRUD
+
+### `schema` is now required in `offset_paginate()` and `cursor_paginate()`
+
+Calls that omit `schema` will now raise a `TypeError` at runtime.
+
+Previously `schema` was optional; omitting it returned raw SQLAlchemy model instances inside the response. It is now a required keyword argument and the response always contains serialized schema instances.
+
+=== "Before (`v1`)"
+
+    ```python
+    # schema omitted — returned raw model instances
+    result = await UserCrud.offset_paginate(session=session, page=1)
+    result = await UserCrud.cursor_paginate(session=session, cursor=token)
+    ```
+
+=== "Now (`v2`)"
+
+    ```python
+    result = await UserCrud.offset_paginate(session=session, page=1, schema=UserRead)
+    result = await UserCrud.cursor_paginate(session=session, cursor=token, schema=UserRead)
+    ```
+
+### `as_response` removed from `create()`, `get()`, and `update()`
+
+Passing `as_response` to these methods will raise a `TypeError` at runtime.
+
+The `as_response=True` shorthand is replaced by passing a `schema` directly. The return value is a `Response[schema]` when `schema` is provided, or the raw model instance when it is not.
+
+=== "Before (`v1`)"
+
+    ```python
+    user = await UserCrud.create(session=session, obj=data, as_response=True)
+    user = await UserCrud.get(session=session, filters=filters, as_response=True)
+    user = await UserCrud.update(session=session, obj=data, filters, as_response=True)
+    ```
+
+=== "Now (`v2`)"
+
+    ```python
+    user = await UserCrud.create(session=session, obj=data, schema=UserRead)
+    user = await UserCrud.get(session=session, filters=filters, schema=UserRead)
+    user = await UserCrud.update(session=session, obj=data, filters, schema=UserRead)
+    ```
+
+### `delete()`: `as_response` renamed and return type changed
+
+`as_response` is gone, and the plain (non-response) call no longer returns `True`.
+
+Two changes were made to `delete()`:
+
+1. The `as_response` parameter is renamed to `return_response`.
+2. When called without `return_response=True`, the method now returns `None` on success instead of `True`.
+
+=== "Before (`v1`)"
+
+    ```python
+    ok = await UserCrud.delete(session=session, filters=filters)
+    if ok:  # True on success
+        ...
+
+    response = await UserCrud.delete(session=session, filters=filters, as_response=True)
+    ```
+
+=== "Now (`v2`)"
+
+    ```python
+    await UserCrud.delete(session=session, filters=filters)  # returns None
+
+    response = await UserCrud.delete(session=session, filters=filters, return_response=True)
+    ```
+
+### `paginate()` alias removed
+
+Any call to `crud.paginate(...)` will raise `AttributeError` at runtime.
+
+The `paginate` shorthand was an alias for `offset_paginate`. It has been removed; call `offset_paginate` directly.
+
+=== "Before (`v1`)"
+
+    ```python
+    result = await UserCrud.paginate(session=session, page=2, items_per_page=20, schema=UserRead)
+    ```
+
+=== "Now (`v2`)"
+
+    ```python
+    result = await UserCrud.offset_paginate(session=session, page=2, items_per_page=20, schema=UserRead)
+    ```
+
+---
+
+## Exceptions
+
+### Missing `api_error` raises `TypeError` at class definition time
+
+Unfinished or stub exception subclasses that previously compiled fine will now fail on import.
+
+In `v1`, a subclass without `api_error` would only fail when the exception was raised. In `v2`, `__init_subclass__` validates this at class definition time.
+
+=== "Before (`v1`)"
+
+    ```python
+    class MyError(ApiException):
+        pass  # fine until raised
+    ```
+
+=== "Now (`v2`)"
+
+    ```python
+    class MyError(ApiException):
+        pass  # TypeError: MyError must define an 'api_error' class attribute.
+    ```
+
+For shared base classes that are not meant to be raised directly, use `abstract=True`:
+
+```python
+class BillingError(ApiException, abstract=True):
+    """Base for all billing-related errors — not raised directly."""
+
+class PaymentRequiredError(BillingError):
+    api_error = ApiError(code=402, msg="Payment Required", desc="...", err_code="BILLING-402")
+```
+
+---
+
+## Schemas
+
+### `Pagination` alias removed
+
+`Pagination` was already deprecated in `v1` and is fully removed in `v2`, you now need to use [`OffsetPagination`](../reference/schemas.md#fastapi_toolsets.schemas.OffsetPagination) or [`CursorPagination`](../reference/schemas.md#fastapi_toolsets.schemas.CursorPagination).

docs/module/crud.md

@@ -7,10 +7,12 @@ Generic async CRUD operations for SQLAlchemy models with search, pagination, and
 
 ## Overview
 
-The `crud` module provides [`AsyncCrud`](../reference/crud.md#fastapi_toolsets.crud.factory.AsyncCrud), an abstract base class with a full suite of async database operations, and [`CrudFactory`](../reference/crud.md#fastapi_toolsets.crud.factory.CrudFactory), a convenience function to instantiate it for a given model.
+The `crud` module provides [`AsyncCrud`](../reference/crud.md#fastapi_toolsets.crud.factory.AsyncCrud), a base class with a full suite of async database operations, and [`CrudFactory`](../reference/crud.md#fastapi_toolsets.crud.factory.CrudFactory), a convenience function to instantiate it for a given model.
 
 ## Creating a CRUD class
 
+### Factory style
+
 ```python
 from fastapi_toolsets.crud import CrudFactory
 from myapp.models import User
@@ -18,10 +20,70 @@ from myapp.models import User
 UserCrud = CrudFactory(model=User)
 ```
 
-[`CrudFactory`](../reference/crud.md#fastapi_toolsets.crud.factory.CrudFactory) dynamically creates a class named `AsyncUserCrud` with `User` as its model.
+[`CrudFactory`](../reference/crud.md#fastapi_toolsets.crud.factory.CrudFactory) dynamically creates a class named `AsyncUserCrud` with `User` as its model. This is the most concise option for straightforward CRUD with no custom logic.
+
+### Subclass style
+
+!!! info "Added in `v2.3.0`"
+
+```python
+from fastapi_toolsets.crud.factory import AsyncCrud
+from myapp.models import User
+
+class UserCrud(AsyncCrud[User]):
+    model = User
+    searchable_fields = [User.username, User.email]
+    default_load_options = [selectinload(User.role)]
+```
+
+Subclassing [`AsyncCrud`](../reference/crud.md#fastapi_toolsets.crud.factory.AsyncCrud) directly is the preferred style when you need to add custom methods or when the configuration is complex enough to benefit from a named class body. 
+
+### Adding custom methods
+
+```python
+class UserCrud(AsyncCrud[User]):
+    model = User
+
+    @classmethod
+    async def get_active(cls, session: AsyncSession) -> list[User]:
+        return await cls.get_multi(session, filters=[User.is_active == True])
+```
+
+### Sharing a custom base across multiple models
+
+Define a generic base class with the shared methods, then subclass it for each model:
+
+```python
+from typing import Generic, TypeVar
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.orm import DeclarativeBase
+from fastapi_toolsets.crud.factory import AsyncCrud
+
+T = TypeVar("T", bound=DeclarativeBase)
+
+class AuditedCrud(AsyncCrud[T], Generic[T]):
+    """Base CRUD with custom function"""
+
+    @classmethod
+    async def get_active(cls, session: AsyncSession):
+        return await cls.get_multi(session, filters=[cls.model.is_active == True])
+
+
+class UserCrud(AuditedCrud[User]):
+    model = User
+    searchable_fields = [User.username, User.email]
+```
+
+You can also use the factory shorthand with the same base by passing `base_class`:
+
+```python
+UserCrud = CrudFactory(User, base_class=AuditedCrud)
+```
 
 ## Basic operations
 
+!!! info "`get_or_none` added in `v2.2`"
+
 ```python
 # Create
 user = await UserCrud.create(session=session, obj=UserCreateSchema(username="alice"))
@@ -29,6 +91,9 @@ user = await UserCrud.create(session=session, obj=UserCreateSchema(username="ali
 # Get one (raises NotFoundError if not found)
 user = await UserCrud.get(session=session, filters=[User.id == user_id])
 
+# Get one or None (never raises)
+user = await UserCrud.get_or_none(session=session, filters=[User.id == user_id])
+
 # Get first or None
 user = await UserCrud.first(session=session, filters=[User.email == email])
 
@@ -46,45 +111,74 @@ count = await UserCrud.count(session=session, filters=[User.is_active == True])
 exists = await UserCrud.exists(session=session, filters=[User.email == email])
 ```
 
+## Fetching a single record
+
+Three methods fetch a single record — choose based on how you want to handle the "not found" case and whether you need strict uniqueness:
+
+| Method | Not found | Multiple results |
+|---|---|---|
+| `get` | raises `NotFoundError` | raises `MultipleResultsFound` |
+| `get_or_none` | returns `None` | raises `MultipleResultsFound` |
+| `first` | returns `None` | returns the first match silently |
+
+Use `get` when the record must exist (e.g. a detail endpoint that should return 404):
+
+```python
+user = await UserCrud.get(session=session, filters=[User.id == user_id])
+```
+
+Use `get_or_none` when the record may not exist but you still want strict uniqueness enforcement:
+
+```python
+user = await UserCrud.get_or_none(session=session, filters=[User.email == email])
+if user is None:
+    ...  # handle missing case without catching an exception
+```
+
+Use `first` when you only care about any one match and don't need uniqueness:
+
+```python
+user = await UserCrud.first(session=session, filters=[User.is_active == True])
+```
+
 ## Pagination
 
 !!! info "Added in `v1.1` (only offset_pagination via `paginate` if `<v1.1`)"
 
-Two pagination strategies are available. Both return a [`PaginatedResponse`](../reference/schemas.md#fastapi_toolsets.schemas.PaginatedResponse) but differ in how they navigate through results.
+Three pagination methods are available.  All return a typed response whose `pagination_type` field tells clients which strategy was used.
 
-| | `offset_paginate` | `cursor_paginate` |
+| | `offset_paginate` | `cursor_paginate` | `paginate` |
-|---|---|---|
+|---|---|---|---|
-| Total count | Yes | No |
+| Return type | `OffsetPaginatedResponse` | `CursorPaginatedResponse` | either, based on `pagination_type` param |
-| Jump to arbitrary page | Yes | No |
+| Total count | Yes | No | / |
-| Performance on deep pages | Degrades | Constant |
+| Jump to arbitrary page | Yes | No | / |
-| Stable under concurrent inserts | No | Yes |
+| Performance on deep pages | Degrades | Constant | / |
-| Search compatible | Yes | Yes |
+| Stable under concurrent inserts | No | Yes | / |
-| Use case | Admin panels, numbered pagination | Feeds, APIs, infinite scroll |
+| Use case | Admin panels, numbered pagination | Feeds, APIs, infinite scroll | single endpoint, both strategies |
 
 ### Offset pagination
 
 ```python
-@router.get(
+@router.get("")
-    "",
-    response_model=PaginatedResponse[User],
-)
 async def get_users(
     session: SessionDep,
     items_per_page: int = 50,
     page: int = 1,
-):
+) -> OffsetPaginatedResponse[UserRead]:
-    return await crud.UserCrud.offset_paginate(
+    return await UserCrud.offset_paginate(
         session=session,
         items_per_page=items_per_page,
         page=page,
+        schema=UserRead,
     )
 ```
 
-The [`offset_paginate`](../reference/crud.md#fastapi_toolsets.crud.factory.AsyncCrud.offset_paginate) method returns a [`PaginatedResponse`](../reference/schemas.md#fastapi_toolsets.schemas.PaginatedResponse) whose `pagination` field is an [`OffsetPagination`](../reference/schemas.md#fastapi_toolsets.schemas.OffsetPagination) object:
+The [`offset_paginate`](../reference/crud.md#fastapi_toolsets.crud.factory.AsyncCrud.offset_paginate) method returns an [`OffsetPaginatedResponse`](../reference/schemas.md#fastapi_toolsets.schemas.OffsetPaginatedResponse):
 
 ```json
 {
   "status": "SUCCESS",
+  "pagination_type": "offset",
   "data": ["..."],
   "pagination": {
     "total_count": 100,
@@ -95,33 +189,29 @@ The [`offset_paginate`](../reference/crud.md#fastapi_toolsets.crud.factory.Async
 }
 ```
 
-!!! warning "Deprecated: `paginate`"
-    The `paginate` function is a backward-compatible alias for `offset_paginate`. This function is **deprecated** and will be removed in **v2.0**.
-
 ### Cursor pagination
 
 ```python
-@router.get(
+@router.get("")
-    "",
-    response_model=PaginatedResponse[UserRead],
-)
 async def list_users(
     session: SessionDep,
     cursor: str | None = None,
     items_per_page: int = 20,
-):
+) -> CursorPaginatedResponse[UserRead]:
     return await UserCrud.cursor_paginate(
         session=session,
         cursor=cursor,
         items_per_page=items_per_page,
+        schema=UserRead,
     )
 ```
 
-The [`cursor_paginate`](../reference/crud.md#fastapi_toolsets.crud.factory.AsyncCrud.cursor_paginate) method returns a [`PaginatedResponse`](../reference/schemas.md#fastapi_toolsets.schemas.PaginatedResponse) whose `pagination` field is a [`CursorPagination`](../reference/schemas.md#fastapi_toolsets.schemas.CursorPagination) object:
+The [`cursor_paginate`](../reference/crud.md#fastapi_toolsets.crud.factory.AsyncCrud.cursor_paginate) method returns a [`CursorPaginatedResponse`](../reference/schemas.md#fastapi_toolsets.schemas.CursorPaginatedResponse):
 
 ```json
 {
   "status": "SUCCESS",
+  "pagination_type": "cursor",
   "data": ["..."],
   "pagination": {
     "next_cursor": "eyJ2YWx1ZSI6ICIzZjQ3YWM2OS0uLi4ifQ==",
@@ -166,6 +256,41 @@ PostCrud = CrudFactory(model=Post, cursor_column=Post.id)
 PostCrud = CrudFactory(model=Post, cursor_column=Post.created_at)
 ```
 
+### Unified endpoint (both strategies)
+
+!!! info "Added in `v2.3.0`"
+
+[`paginate()`](../reference/crud.md#fastapi_toolsets.crud.factory.AsyncCrud.paginate) dispatches to `offset_paginate` or `cursor_paginate` based on a `pagination_type` query parameter, letting you expose **one endpoint** that supports both strategies.  The `pagination_type` field in the response tells clients which strategy was used, enabling frontend discriminated-union typing.
+
+```python
+from fastapi_toolsets.crud import PaginationType
+from fastapi_toolsets.schemas import PaginatedResponse
+
+@router.get("")
+async def list_users(
+    session: SessionDep,
+    pagination_type: PaginationType = PaginationType.OFFSET,
+    page: int = Query(1, ge=1, description="Current page (offset only)"),
+    cursor: str | None = Query(None, description="Cursor token (cursor only)"),
+    items_per_page: int = Query(20, ge=1, le=100),
+) -> PaginatedResponse[UserRead]:
+    return await UserCrud.paginate(
+        session,
+        pagination_type=pagination_type,
+        page=page,
+        cursor=cursor,
+        items_per_page=items_per_page,
+        schema=UserRead,
+    )
+```
+
+```
+GET /users?pagination_type=offset&page=2&items_per_page=10
+GET /users?pagination_type=cursor&cursor=eyJ2YWx1ZSI6...&items_per_page=10
+```
+
+Both `page` and `cursor` are always accepted by the endpoint — unused parameters are silently ignored by `paginate()`.
+
 ## Search
 
 Two search strategies are available, both compatible with [`offset_paginate`](../reference/crud.md#fastapi_toolsets.crud.factory.AsyncCrud.offset_paginate) and [`cursor_paginate`](../reference/crud.md#fastapi_toolsets.crud.factory.AsyncCrud.cursor_paginate).
@@ -180,6 +305,9 @@ Two search strategies are available, both compatible with [`offset_paginate`](..
 
 ### Full-text search
 
+!!! info "Added in `v2.2.1`"
+    The model's primary key is always included in `searchable_fields` automatically, so searching by ID works out of the box without any configuration. When no `searchable_fields` are declared, only the primary key is searched.
+
 Declare `searchable_fields` on the CRUD class. Relationship traversal is supported via tuples:
 
 ```python
@@ -205,40 +333,36 @@ result = await UserCrud.offset_paginate(
 This allows searching with both [`offset_paginate`](../reference/crud.md#fastapi_toolsets.crud.factory.AsyncCrud.offset_paginate) and [`cursor_paginate`](../reference/crud.md#fastapi_toolsets.crud.factory.AsyncCrud.cursor_paginate):
 
 ```python
-@router.get(
+@router.get("")
-    "",
-    response_model=PaginatedResponse[User],
-)
 async def get_users(
     session: SessionDep,
     items_per_page: int = 50,
     page: int = 1,
     search: str | None = None,
-):
+) -> OffsetPaginatedResponse[UserRead]:
-    return await crud.UserCrud.offset_paginate(
+    return await UserCrud.offset_paginate(
         session=session,
         items_per_page=items_per_page,
         page=page,
         search=search,
+        schema=UserRead,
     )
 ```
 
 ```python
-@router.get(
+@router.get("")
-    "",
-    response_model=PaginatedResponse[User],
-)
 async def get_users(
     session: SessionDep,
     cursor: str | None = None,
     items_per_page: int = 50,
     search: str | None = None,
-):
+) -> CursorPaginatedResponse[UserRead]:
-    return await crud.UserCrud.cursor_paginate(
+    return await UserCrud.cursor_paginate(
         session=session,
         items_per_page=items_per_page,
         cursor=cursor,
         search=search,
+        schema=UserRead,
     )
 ```
 
@@ -309,11 +433,12 @@ async def list_users(
     session: SessionDep,
     page: int = 1,
     filter_by: Annotated[dict[str, list[str]], Depends(UserCrud.filter_params())],
-) -> PaginatedResponse[UserRead]:
+) -> OffsetPaginatedResponse[UserRead]:
     return await UserCrud.offset_paginate(
         session=session,
         page=page,
         filter_by=filter_by,
+        schema=UserRead,
     )
 ```
 
@@ -353,8 +478,8 @@ from fastapi_toolsets.crud import OrderByClause
 async def list_users(
     session: SessionDep,
     order_by: Annotated[OrderByClause | None, Depends(UserCrud.order_params())],
-) -> PaginatedResponse[UserRead]:
+) -> OffsetPaginatedResponse[UserRead]:
-    return await UserCrud.offset_paginate(session=session, order_by=order_by)
+    return await UserCrud.offset_paginate(session=session, order_by=order_by, schema=UserRead)
 ```
 
 The dependency adds two query parameters to the endpoint:
@@ -461,7 +586,7 @@ async def get_user(session: SessionDep, uuid: UUID) -> Response[UserRead]:
     )
 
 @router.get("")
-async def list_users(session: SessionDep, page: int = 1) -> PaginatedResponse[UserRead]:
+async def list_users(session: SessionDep, page: int = 1) -> OffsetPaginatedResponse[UserRead]:
     return await crud.UserCrud.offset_paginate(
         session=session,
         page=page,
@@ -471,9 +596,6 @@ async def list_users(session: SessionDep, page: int = 1) -> PaginatedResponse[Us
 
 The schema must have `from_attributes=True` (or inherit from [`PydanticBase`](../reference/schemas.md#fastapi_toolsets.schemas.PydanticBase)) so it can be built from SQLAlchemy model instances.
 
-!!! warning "Deprecated: `as_response`"
-    The `as_response=True` parameter is **deprecated** and will be removed in **v2.0**. Replace it with `schema=YourSchema`.
-
 ---
 
 [:material-api: API Reference](../reference/crud.md)

docs/module/db.md

@@ -87,6 +87,37 @@ await wait_for_row_change(
 )
 ```
 
+## Creating a database
+
+!!! info "Added in `v2.1`"
+
+[`create_database`](../reference/db.md#fastapi_toolsets.db.create_database) creates a database at a given URL. It connects to *server_url* and issues a `CREATE DATABASE` statement:
+
+```python
+from fastapi_toolsets.db import create_database
+
+SERVER_URL = "postgresql+asyncpg://postgres:postgres@localhost/postgres"
+
+await create_database(db_name="myapp_test", server_url=SERVER_URL)
+```
+
+For test isolation with automatic cleanup, use [`create_worker_database`](../reference/pytest.md#fastapi_toolsets.pytest.utils.create_worker_database) from the `pytest` module instead — it handles drop-before, create, and drop-after automatically.
+
+## Cleaning up tables
+
+!!! info "Added in `v2.1`"
+
+[`cleanup_tables`](../reference/db.md#fastapi_toolsets.db.cleanup_tables) truncates all tables:
+
+```python
+from fastapi_toolsets.db import cleanup_tables
+
+@pytest.fixture(autouse=True)
+async def clean(db_session):
+    yield
+    await cleanup_tables(session=db_session, base=Base)
+```
+
 ---
 
 [:material-api: API Reference](../reference/db.md)

docs/module/dependencies.md

@@ -13,8 +13,13 @@ The `dependencies` module provides two factory functions that create FastAPI dep
 ```python
 from fastapi_toolsets.dependencies import PathDependency
 
+# Plain callable
 UserDep = PathDependency(model=User, field=User.id, session_dep=get_db)
 
+# Annotated
+SessionDep = Annotated[AsyncSession, Depends(get_db)]
+UserDep = PathDependency(model=User, field=User.id, session_dep=SessionDep)
+
 @router.get("/users/{user_id}")
 async def get_user(user: User = UserDep):
     return user
@@ -37,8 +42,14 @@ async def get_user(user: User = UserDep):
 ```python
 from fastapi_toolsets.dependencies import BodyDependency
 
+# Plain callable
 RoleDep = BodyDependency(model=Role, field=Role.id, session_dep=get_db, body_field="role_id")
 
+# Annotated
+SessionDep = Annotated[AsyncSession, Depends(get_db)]
+RoleDep = BodyDependency(model=Role, field=Role.id, session_dep=SessionDep, body_field="role_id")
+
+
 @router.post("/users")
 async def create_user(body: UserCreateSchema, role: Role = RoleDep):
     user = User(username=body.username, role=role)

docs/module/exceptions.md

@@ -21,30 +21,37 @@ init_exceptions_handlers(app=app)
 This registers handlers for:
 
 - [`ApiException`](../reference/exceptions.md#fastapi_toolsets.exceptions.exceptions.ApiException) — all custom exceptions below
+- `HTTPException` — Starlette/FastAPI HTTP errors
 - `RequestValidationError` — Pydantic request validation (422)
 - `ResponseValidationError` — Pydantic response validation (422)
 - `Exception` — unhandled errors (500)
 
+It also patches `app.openapi()` to replace the default Pydantic 422 schema with a structured example matching the `ErrorResponse` format.
+
 ## Built-in exceptions
 
 | Exception | Status | Default message |
 |-----------|--------|-----------------|
 | [`UnauthorizedError`](../reference/exceptions.md#fastapi_toolsets.exceptions.exceptions.UnauthorizedError) | 401 | Unauthorized |
 | [`ForbiddenError`](../reference/exceptions.md#fastapi_toolsets.exceptions.exceptions.ForbiddenError) | 403 | Forbidden |
-| [`NotFoundError`](../reference/exceptions.md#fastapi_toolsets.exceptions.exceptions.NotFoundError) | 404 | Not found |
+| [`NotFoundError`](../reference/exceptions.md#fastapi_toolsets.exceptions.exceptions.NotFoundError) | 404 | Not Found |
 | [`ConflictError`](../reference/exceptions.md#fastapi_toolsets.exceptions.exceptions.ConflictError) | 409 | Conflict |
-| [`NoSearchableFieldsError`](../reference/exceptions.md#fastapi_toolsets.exceptions.exceptions.NoSearchableFieldsError) | 400 | No searchable fields |
+| [`NoSearchableFieldsError`](../reference/exceptions.md#fastapi_toolsets.exceptions.exceptions.NoSearchableFieldsError) | 400 | No Searchable Fields |
-| [`InvalidFacetFilterError`](../reference/exceptions.md#fastapi_toolsets.exceptions.exceptions.InvalidFacetFilterError) | 400 | Invalid facet filter |
+| [`InvalidFacetFilterError`](../reference/exceptions.md#fastapi_toolsets.exceptions.exceptions.InvalidFacetFilterError) | 400 | Invalid Facet Filter |
+| [`InvalidOrderFieldError`](../reference/exceptions.md#fastapi_toolsets.exceptions.exceptions.InvalidOrderFieldError) | 422 | Invalid Order Field |
+
+### Per-instance overrides
+
+All built-in exceptions accept optional keyword arguments to customise the response for a specific raise site without changing the class defaults:
+
+| Argument | Effect |
+|----------|--------|
+| `detail` | Overrides both `str(exc)` (log output) and the `message` field in the response body |
+| `desc` | Overrides the `description` field |
+| `data` | Overrides the `data` field |
 
 ```python
-from fastapi_toolsets.exceptions import NotFoundError
+raise NotFoundError(detail="User 42 not found", desc="No user with that ID exists in the database.")
-
-@router.get("/users/{id}")
-async def get_user(id: int, session: AsyncSession = Depends(get_db)):
-    user = await UserCrud.first(session=session, filters=[User.id == id])
-    if not user:
-        raise NotFoundError
-    return user
 ```
 
 ## Custom exceptions
@@ -58,12 +65,51 @@ from fastapi_toolsets.schemas import ApiError
 class PaymentRequiredError(ApiException):
     api_error = ApiError(
         code=402,
-        msg="Payment required",
+        msg="Payment Required",
         desc="Your subscription has expired.",
-        err_code="PAYMENT_REQUIRED",
+        err_code="BILLING-402",
     )
 ```
 
+!!! warning
+    Subclasses that do not define `api_error` raise a `TypeError` at **class creation time**, not at raise time.
+
+### Custom `__init__`
+
+Override `__init__` to compute `detail`, `desc`, or `data` dynamically, then delegate to `super().__init__()`:
+
+```python
+class OrderValidationError(ApiException):
+    api_error = ApiError(
+        code=422,
+        msg="Order Validation Failed",
+        desc="One or more order fields are invalid.",
+        err_code="ORDER-422",
+    )
+
+    def __init__(self, *field_errors: str) -> None:
+        super().__init__(
+            f"{len(field_errors)} validation error(s)",
+            desc=", ".join(field_errors),
+            data={"errors": [{"message": e} for e in field_errors]},
+        )
+```
+
+### Intermediate base classes
+
+Use `abstract=True` when creating a shared base that is not meant to be raised directly:
+
+```python
+class BillingError(ApiException, abstract=True):
+    """Base for all billing-related errors."""
+
+class PaymentRequiredError(BillingError):
+    api_error = ApiError(code=402, msg="Payment Required", desc="...", err_code="BILLING-402")
+
+class SubscriptionExpiredError(BillingError):
+    api_error = ApiError(code=402, msg="Subscription Expired", desc="...", err_code="BILLING-402-EXP")
+```
+
 ## OpenAPI response documentation
 
 Use [`generate_error_responses`](../reference/exceptions.md#fastapi_toolsets.exceptions.exceptions.generate_error_responses) to add error schemas to your endpoint's OpenAPI spec:
@@ -78,8 +124,7 @@ from fastapi_toolsets.exceptions import generate_error_responses, NotFoundError,
 async def get_user(...): ...
 ```
 
-!!! info
+Multiple exceptions sharing the same HTTP status code are grouped under one entry, each appearing as a named example keyed by its `err_code`. This keeps the OpenAPI UI readable when several error variants map to the same status.
-    The pydantic validation error is automatically added by FastAPI.
 
 ---
 

docs/module/metrics.md

@@ -36,7 +36,13 @@ This mounts the `/metrics` endpoint that Prometheus can scrape.
 
 ### Providers
 
-Providers are called once at startup and register metrics that are updated externally (e.g. counters, histograms):
+Providers are called once at startup by `init_metrics`. The return value (the Prometheus metric object) is stored in the registry and can be retrieved later with [`registry.get(name)`](../reference/metrics.md#fastapi_toolsets.metrics.registry.MetricsRegistry.get).
+
+Use providers when you want **deferred initialization**: the Prometheus metric is not registered with the global `CollectorRegistry` until `init_metrics` runs, not at import time. This is particularly useful for testing — importing the module in a test suite without calling `init_metrics` leaves no metrics registered, avoiding cross-test pollution.
+
+It is also useful when metrics are defined across multiple modules and merged with `include_registry`: any code that needs a metric can call `metrics.get()` on the shared registry instead of importing the metric directly from its origin module.
+
+If neither of these applies to you, declaring metrics at module level (e.g. `HTTP_REQUESTS = Counter(...)`) is simpler and equally valid.
 
 ```python
 from prometheus_client import Counter, Histogram
@@ -50,15 +56,32 @@ def request_duration():
     return Histogram("request_duration_seconds", "Request duration")
 ```
 
-### Collectors
+To use a provider's metric elsewhere (e.g. in a middleware), call `metrics.get()` inside the handler — **not** at module level, as providers are only initialized when `init_metrics` runs:
-
-Collectors are called on every scrape. Use them for metrics that reflect current state (e.g. gauges):
 
 ```python
+async def metrics_middleware(request: Request, call_next):
+    response = await call_next(request)
+    metrics.get("http_requests").labels(
+        method=request.method, status=response.status_code
+    ).inc()
+    return response
+```
+
+### Collectors
+
+Collectors are called on every scrape. Use them for metrics that reflect current state (e.g. gauges).
+
+!!! warning "Declare the metric at module level"
+    Do **not** instantiate the Prometheus metric inside the collector function. Doing so recreates it on every scrape, raising `ValueError: Duplicated timeseries in CollectorRegistry`. Declare it once at module level instead:
+
+```python
+from prometheus_client import Gauge
+
+_queue_depth = Gauge("queue_depth", "Current queue depth")
+
 @metrics.register(collect=True)
-def queue_depth():
+def collect_queue_depth():
-    gauge = Gauge("queue_depth", "Current queue depth")
+    _queue_depth.set(get_current_queue_depth())
-    gauge.set(get_current_queue_depth())
 ```
 
 ## Merging registries

docs/module/models.md

@@ -0,0 +1,219 @@
+# Models
+
+!!! info "Added in `v2.0`"
+
+Reusable SQLAlchemy 2.0 mixins for common column patterns, designed to be composed freely on any `DeclarativeBase` model.
+
+## Overview
+
+The `models` module provides mixins that each add a single, well-defined column behaviour. They work with standard SQLAlchemy 2.0 declarative syntax and are fully compatible with `AsyncSession`.
+
+```python
+from fastapi_toolsets.models import UUIDMixin, TimestampMixin
+
+class Article(Base, UUIDMixin, TimestampMixin):
+    __tablename__ = "articles"
+
+    title: Mapped[str]
+    content: Mapped[str]
+```
+
+All timestamp columns are timezone-aware (`TIMESTAMPTZ`). All defaults are server-side (`clock_timestamp()`), so they are also applied when inserting rows via raw SQL outside the ORM.
+
+## Mixins
+
+### [`UUIDMixin`](../reference/models.md#fastapi_toolsets.models.UUIDMixin)
+
+Adds a `id: UUID` primary key generated server-side by PostgreSQL using `gen_random_uuid()`. The value is retrieved via `RETURNING` after insert, so it is available on the Python object immediately after `flush()`.
+
+!!! warning "Requires PostgreSQL 13+"
+
+```python
+from fastapi_toolsets.models import UUIDMixin
+
+class User(Base, UUIDMixin):
+    __tablename__ = "users"
+
+    username: Mapped[str]
+
+# id is None before flush
+user = User(username="alice")
+session.add(user)
+await session.flush()
+print(user.id)  # UUID('...')
+```
+
+### [`UUIDv7Mixin`](../reference/models.md#fastapi_toolsets.models.UUIDv7Mixin)
+
+!!! info "Added in `v2.3`"
+
+Adds a `id: UUID` primary key generated server-side by PostgreSQL using `uuidv7()`. It's a time-ordered UUID format that encodes a millisecond-precision timestamp in the most significant bits, making it naturally sortable and index-friendly.
+
+!!! warning "Requires PostgreSQL 18+"
+
+```python
+from fastapi_toolsets.models import UUIDv7Mixin
+
+class Event(Base, UUIDv7Mixin):
+    __tablename__ = "events"
+
+    name: Mapped[str]
+
+# id is None before flush
+event = Event(name="user.signup")
+session.add(event)
+await session.flush()
+print(event.id)  # UUID('019...')
+```
+
+### [`CreatedAtMixin`](../reference/models.md#fastapi_toolsets.models.CreatedAtMixin)
+
+Adds a `created_at: datetime` column set to `clock_timestamp()` on insert. The column has no `onupdate` hook — it is intentionally immutable after the row is created.
+
+```python
+from fastapi_toolsets.models import UUIDMixin, CreatedAtMixin
+
+class Order(Base, UUIDMixin, CreatedAtMixin):
+    __tablename__ = "orders"
+
+    total: Mapped[float]
+```
+
+### [`UpdatedAtMixin`](../reference/models.md#fastapi_toolsets.models.UpdatedAtMixin)
+
+Adds an `updated_at: datetime` column set to `clock_timestamp()` on insert and automatically updated to `clock_timestamp()` on every ORM-level update (via SQLAlchemy's `onupdate` hook).
+
+```python
+from fastapi_toolsets.models import UUIDMixin, UpdatedAtMixin
+
+class Post(Base, UUIDMixin, UpdatedAtMixin):
+    __tablename__ = "posts"
+
+    title: Mapped[str]
+
+post = Post(title="Hello")
+await session.flush()
+await session.refresh(post)
+
+post.title = "Hello World"
+await session.flush()
+await session.refresh(post)
+print(post.updated_at)
+```
+
+!!! note
+    `updated_at` is updated by SQLAlchemy at ORM flush time. If you update rows via raw SQL (e.g. `UPDATE posts SET ...`), the column will **not** be updated automatically — use a database trigger if you need that guarantee.
+
+### [`TimestampMixin`](../reference/models.md#fastapi_toolsets.models.TimestampMixin)
+
+Convenience mixin that combines [`CreatedAtMixin`](../reference/models.md#fastapi_toolsets.models.CreatedAtMixin) and [`UpdatedAtMixin`](../reference/models.md#fastapi_toolsets.models.UpdatedAtMixin). Equivalent to inheriting both.
+
+```python
+from fastapi_toolsets.models import UUIDMixin, TimestampMixin
+
+class Article(Base, UUIDMixin, TimestampMixin):
+    __tablename__ = "articles"
+
+    title: Mapped[str]
+```
+
+### [`WatchedFieldsMixin`](../reference/models.md#fastapi_toolsets.models.WatchedFieldsMixin)
+
+!!! info "Added in `v2.4`"
+
+`WatchedFieldsMixin` provides lifecycle callbacks that fire **after commit** — meaning the row is durably persisted when your callback runs. If the transaction rolls back, no callback fires.
+
+Three callbacks are available, each corresponding to a [`ModelEvent`](../reference/models.md#fastapi_toolsets.models.ModelEvent) value:
+
+| Callback | Event | Trigger |
+|---|---|---|
+| `on_create()` | `ModelEvent.CREATE` | After `INSERT` |
+| `on_delete()` | `ModelEvent.DELETE` | After `DELETE` |
+| `on_update(changes)` | `ModelEvent.UPDATE` | After `UPDATE` on a watched field |
+
+Server-side defaults (e.g. `id`, `created_at`) are fully populated in all callbacks. All callbacks support both `async def` and plain `def`. Use `@watch` to restrict which fields trigger `on_update`:
+
+| Decorator | `on_update` behaviour |
+|---|---|
+| `@watch("status", "role")` | Only fires when `status` or `role` changes |
+| *(no decorator)* | Fires when **any** mapped field changes |
+
+#### Option 1 — catch-all with `on_event`
+
+Override `on_event` to handle all event types in one place. The specific methods delegate here by default:
+
+```python
+from fastapi_toolsets.models import ModelEvent, UUIDMixin, WatchedFieldsMixin, watch
+
+@watch("status")
+class Order(Base, UUIDMixin, WatchedFieldsMixin):
+    __tablename__ = "orders"
+
+    status: Mapped[str]
+
+    async def on_event(self, event: ModelEvent, changes: dict | None = None) -> None:
+        if event == ModelEvent.CREATE:
+            await notify_new_order(self.id)
+        elif event == ModelEvent.DELETE:
+            await notify_order_cancelled(self.id)
+        elif event == ModelEvent.UPDATE:
+            await notify_status_change(self.id, changes["status"])
+```
+
+#### Option 2 — targeted overrides
+
+Override individual methods for more focused logic:
+
+```python
+@watch("status")
+class Order(Base, UUIDMixin, WatchedFieldsMixin):
+    __tablename__ = "orders"
+
+    status: Mapped[str]
+
+    async def on_create(self) -> None:
+        await notify_new_order(self.id)
+
+    async def on_delete(self) -> None:
+        await notify_order_cancelled(self.id)
+
+    async def on_update(self, changes: dict) -> None:
+        if "status" in changes:
+            old = changes["status"]["old"]
+            new = changes["status"]["new"]
+            await notify_status_change(self.id, old, new)
+```
+
+#### Field changes format
+
+The `changes` dict maps each watched field that changed to `{"old": ..., "new": ...}`. Only fields that actually changed are included:
+
+```python
+# status changed   → {"status": {"old": "pending", "new": "shipped"}}
+# two fields changed → {"status": {...}, "assigned_to": {...}}
+```
+
+!!! info "Multiple flushes in one transaction are merged: the earliest `old` and latest `new` are preserved, and `on_update` fires only once per commit."
+
+!!! warning "Callbacks fire only for ORM-level changes. Rows updated via raw SQL (`UPDATE ... SET ...`) are not detected."
+
+## Composing mixins
+
+All mixins can be combined in any order. The only constraint is that exactly one primary key must be defined — either via `UUIDMixin` or directly on the model.
+
+```python
+from fastapi_toolsets.models import UUIDMixin, TimestampMixin
+
+class Event(Base, UUIDMixin, TimestampMixin):
+    __tablename__ = "events"
+    name: Mapped[str]
+
+class Counter(Base, UpdatedAtMixin):
+    __tablename__ = "counters"
+    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
+    value: Mapped[int]
+```
+
+---
+
+[:material-api: API Reference](../reference/models.md)

docs/module/pytest.md

@@ -40,10 +40,10 @@ async def http_client(db_session):
 
 ## Database sessions in tests
 
-Use [`create_db_session`](../reference/pytest.md#fastapi_toolsets.pytest.utils.create_db_session) to create an isolated `AsyncSession` for a test:
+Use [`create_db_session`](../reference/pytest.md#fastapi_toolsets.pytest.utils.create_db_session) to create an isolated `AsyncSession` for a test, combined with [`create_worker_database`](../reference/pytest.md#fastapi_toolsets.pytest.utils.create_worker_database) to set up a per-worker database:
 
 ```python
-from fastapi_toolsets.pytest import create_db_session, create_worker_database
+from fastapi_toolsets.pytest import create_worker_database, create_db_session
 
 @pytest.fixture(scope="session")
 async def worker_db_url():
@@ -64,16 +64,28 @@ async def db_session(worker_db_url):
 !!! info
     In this example, the database is reset between each test using the argument `cleanup=True`.
 
+Use [`worker_database_url`](../reference/pytest.md#fastapi_toolsets.pytest.utils.worker_database_url) to derive the per-worker URL manually if needed:
+
+```python
+from fastapi_toolsets.pytest import worker_database_url
+
+url = worker_database_url("postgresql+asyncpg://user:pass@localhost/test_db", default_test_db="test")
+# e.g. "postgresql+asyncpg://user:pass@localhost/test_db_gw0" under xdist
+```
+
 ## Parallel testing with pytest-xdist
 
 The examples above are already compatible with parallel test execution with `pytest-xdist`.
 
 ## Cleaning up tables
 
-If you want to manually clean up a database you can use [`cleanup_tables`](../reference/pytest.md#fastapi_toolsets.pytest.utils.cleanup_tables), this will truncates all tables between tests for fast isolation:
+!!! warning
+    Since `V2.1.0` `cleanup_tables` now live in `fastapi_toolsets.db`. For backward compatibility the function is still available in `fastapi_toolsets.pytest`, but this will be remove in `V3.0.0`.
+
+If you want to manually clean up a database you can use [`cleanup_tables`](../reference/db.md#fastapi_toolsets.db.cleanup_tables), this will truncate all tables between tests for fast isolation:
 
 ```python
-from fastapi_toolsets.pytest import cleanup_tables
+from fastapi_toolsets.db import cleanup_tables
 
 @pytest.fixture(autouse=True)
 async def clean(db_session):

docs/module/schemas.md

@@ -20,26 +20,115 @@ async def get_user(user: User = UserDep) -> Response[UserSchema]:
     return Response(data=user, message="User retrieved")
 ```
 
-### [`PaginatedResponse[T]`](../reference/schemas.md#fastapi_toolsets.schemas.PaginatedResponse)
+### Paginated response models
 
-Wraps a list of items with pagination metadata and optional facet values.
+Three classes wrap paginated list results. Pick the one that matches your endpoint's strategy:
+
+| Class | `pagination` type | `pagination_type` field | Use when |
+|---|---|---|---|
+| [`OffsetPaginatedResponse[T]`](#offsetpaginatedresponset) | `OffsetPagination` | `"offset"` (fixed) | endpoint always uses offset |
+| [`CursorPaginatedResponse[T]`](#cursorpaginatedresponset) | `CursorPagination` | `"cursor"` (fixed) | endpoint always uses cursor |
+| [`PaginatedResponse[T]`](#paginatedresponset) | `OffsetPagination \| CursorPagination` | — | unified endpoint supporting both strategies |
+
+#### [`OffsetPaginatedResponse[T]`](../reference/schemas.md#fastapi_toolsets.schemas.OffsetPaginatedResponse)
+
+!!! info "Added in `v2.3.0`"
+
+Use as the return type when the endpoint always uses [`offset_paginate`](crud.md#offset-pagination).  The `pagination` field is guaranteed to be an [`OffsetPagination`](../reference/schemas.md#fastapi_toolsets.schemas.OffsetPagination) object; the response always includes a `pagination_type: "offset"` discriminator.
 
 ```python
-from fastapi_toolsets.schemas import PaginatedResponse, Pagination
+from fastapi_toolsets.schemas import OffsetPaginatedResponse
 
 @router.get("/users")
-async def list_users() -> PaginatedResponse[UserSchema]:
+async def list_users(
-    return PaginatedResponse(
+    page: int = 1,
-        data=users,
+    items_per_page: int = 20,
-        pagination=Pagination(
+) -> OffsetPaginatedResponse[UserSchema]:
-            total_count=100,
+    return await UserCrud.offset_paginate(
-            items_per_page=10,
+        session, page=page, items_per_page=items_per_page, schema=UserSchema
-            page=1,
-            has_more=True,
-        ),
     )
 ```
 
+**Response shape:**
+
+```json
+{
+  "status": "SUCCESS",
+  "pagination_type": "offset",
+  "data": ["..."],
+  "pagination": {
+    "total_count": 100,
+    "page": 1,
+    "items_per_page": 20,
+    "has_more": true
+  }
+}
+```
+
+#### [`CursorPaginatedResponse[T]`](../reference/schemas.md#fastapi_toolsets.schemas.CursorPaginatedResponse)
+
+!!! info "Added in `v2.3.0`"
+
+Use as the return type when the endpoint always uses [`cursor_paginate`](crud.md#cursor-pagination).  The `pagination` field is guaranteed to be a [`CursorPagination`](../reference/schemas.md#fastapi_toolsets.schemas.CursorPagination) object; the response always includes a `pagination_type: "cursor"` discriminator.
+
+```python
+from fastapi_toolsets.schemas import CursorPaginatedResponse
+
+@router.get("/events")
+async def list_events(
+    cursor: str | None = None,
+    items_per_page: int = 20,
+) -> CursorPaginatedResponse[EventSchema]:
+    return await EventCrud.cursor_paginate(
+        session, cursor=cursor, items_per_page=items_per_page, schema=EventSchema
+    )
+```
+
+**Response shape:**
+
+```json
+{
+  "status": "SUCCESS",
+  "pagination_type": "cursor",
+  "data": ["..."],
+  "pagination": {
+    "next_cursor": "eyJpZCI6IDQyfQ==",
+    "prev_cursor": null,
+    "items_per_page": 20,
+    "has_more": true
+  }
+}
+```
+
+#### [`PaginatedResponse[T]`](../reference/schemas.md#fastapi_toolsets.schemas.PaginatedResponse)
+
+Return type for endpoints that support **both** pagination strategies via a `pagination_type` query parameter (using [`paginate()`](crud.md#unified-paginate--both-strategies-on-one-endpoint)).
+
+When used as a return annotation, `PaginatedResponse[T]` automatically expands to `Annotated[Union[CursorPaginatedResponse[T], OffsetPaginatedResponse[T]], Field(discriminator="pagination_type")]`, so FastAPI emits a proper `oneOf` + discriminator in the OpenAPI schema with no extra boilerplate:
+
+```python
+from fastapi_toolsets.crud import PaginationType
+from fastapi_toolsets.schemas import PaginatedResponse
+
+@router.get("/users")
+async def list_users(
+    pagination_type: PaginationType = PaginationType.OFFSET,
+    page: int = 1,
+    cursor: str | None = None,
+    items_per_page: int = 20,
+) -> PaginatedResponse[UserSchema]:
+    return await UserCrud.paginate(
+        session,
+        pagination_type=pagination_type,
+        page=page,
+        cursor=cursor,
+        items_per_page=items_per_page,
+        schema=UserSchema,
+    )
+```
+
+#### Pagination metadata models
+
 The optional `filter_attributes` field is populated when `facet_fields` are configured on the CRUD class (see [Filter attributes](crud.md#filter-attributes-facets)). It is `None` by default and can be hidden from API responses with `response_model_exclude_none=True`.
 
 ### [`ErrorResponse`](../reference/schemas.md#fastapi_toolsets.schemas.ErrorResponse)

docs/reference/db.md

@@ -7,6 +7,8 @@ You can import them directly from `fastapi_toolsets.db`:
 ```python
 from fastapi_toolsets.db import (
     LockMode,
+    cleanup_tables,
+    create_database,
     create_db_dependency,
     create_db_context,
     get_transaction,
@@ -26,3 +28,7 @@ from fastapi_toolsets.db import (
 ## ::: fastapi_toolsets.db.lock_tables
 
 ## ::: fastapi_toolsets.db.wait_for_row_change
+
+## ::: fastapi_toolsets.db.create_database
+
+## ::: fastapi_toolsets.db.cleanup_tables

docs/reference/models.md

@@ -0,0 +1,34 @@
+# `models`
+
+Here's the reference for the SQLAlchemy model mixins provided by the `models` module.
+
+You can import them directly from `fastapi_toolsets.models`:
+
+```python
+from fastapi_toolsets.models import (
+    ModelEvent,
+    UUIDMixin,
+    UUIDv7Mixin,
+    CreatedAtMixin,
+    UpdatedAtMixin,
+    TimestampMixin,
+    WatchedFieldsMixin,
+    watch,
+)
+```
+
+## ::: fastapi_toolsets.models.ModelEvent
+
+## ::: fastapi_toolsets.models.UUIDMixin
+
+## ::: fastapi_toolsets.models.UUIDv7Mixin
+
+## ::: fastapi_toolsets.models.CreatedAtMixin
+
+## ::: fastapi_toolsets.models.UpdatedAtMixin
+
+## ::: fastapi_toolsets.models.TimestampMixin
+
+## ::: fastapi_toolsets.models.WatchedFieldsMixin
+
+## ::: fastapi_toolsets.models.watch

docs/reference/pytest.md

@@ -24,5 +24,3 @@ from fastapi_toolsets.pytest import (
 ## ::: fastapi_toolsets.pytest.utils.worker_database_url
 
 ## ::: fastapi_toolsets.pytest.utils.create_worker_database
-
-## ::: fastapi_toolsets.pytest.utils.cleanup_tables

docs/reference/schemas.md

@@ -1,4 +1,4 @@
-# `schemas` module
+# `schemas`
 
 Here's the reference for all response models and types provided by the `schemas` module.
 
@@ -12,8 +12,12 @@ from fastapi_toolsets.schemas import (
     BaseResponse,
     Response,
     ErrorResponse,
-    Pagination,
+    OffsetPagination,
+    CursorPagination,
+    PaginationType,
     PaginatedResponse,
+    OffsetPaginatedResponse,
+    CursorPaginatedResponse,
 )
 ```
 
@@ -29,6 +33,14 @@ from fastapi_toolsets.schemas import (
 
 ## ::: fastapi_toolsets.schemas.ErrorResponse
 
-## ::: fastapi_toolsets.schemas.Pagination
+## ::: fastapi_toolsets.schemas.OffsetPagination
+
+## ::: fastapi_toolsets.schemas.CursorPagination
+
+## ::: fastapi_toolsets.schemas.PaginationType
 
 ## ::: fastapi_toolsets.schemas.PaginatedResponse
+
+## ::: fastapi_toolsets.schemas.OffsetPaginatedResponse
+
+## ::: fastapi_toolsets.schemas.CursorPaginatedResponse

docs_src/examples/pagination_search/models.py

@@ -1,9 +1,10 @@
-import datetime
 import uuid
 
-from sqlalchemy import Boolean, DateTime, ForeignKey, String, Text, func
+from sqlalchemy import Boolean, ForeignKey, String, Text
 from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, relationship
 
+from fastapi_toolsets.models import CreatedAtMixin
+
 
 class Base(DeclarativeBase):
     pass
@@ -18,13 +19,10 @@ class Category(Base):
     articles: Mapped[list["Article"]] = relationship(back_populates="category")
 
 
-class Article(Base):
+class Article(Base, CreatedAtMixin):
     __tablename__ = "articles"
 
     id: Mapped[uuid.UUID] = mapped_column(primary_key=True, default=uuid.uuid4)
-    created_at: Mapped[datetime.datetime] = mapped_column(
-        DateTime(timezone=True), server_default=func.now()
-    )
     title: Mapped[str] = mapped_column(String(256))
     body: Mapped[str] = mapped_column(Text)
     status: Mapped[str] = mapped_column(String(32))

docs_src/examples/pagination_search/routes.py

@@ -2,8 +2,12 @@ from typing import Annotated
 
 from fastapi import APIRouter, Depends, Query
 
-from fastapi_toolsets.crud import OrderByClause
+from fastapi_toolsets.crud import OrderByClause, PaginationType
-from fastapi_toolsets.schemas import PaginatedResponse
+from fastapi_toolsets.schemas import (
+    CursorPaginatedResponse,
+    OffsetPaginatedResponse,
+    PaginatedResponse,
+)
 
 from .crud import ArticleCrud
 from .db import SessionDep
@@ -24,7 +28,7 @@ async def list_articles_offset(
     page: int = Query(1, ge=1),
     items_per_page: int = Query(20, ge=1, le=100),
     search: str | None = None,
-) -> PaginatedResponse[ArticleRead]:
+) -> OffsetPaginatedResponse[ArticleRead]:
     return await ArticleCrud.offset_paginate(
         session=session,
         page=page,
@@ -47,7 +51,7 @@ async def list_articles_cursor(
     cursor: str | None = None,
     items_per_page: int = Query(20, ge=1, le=100),
     search: str | None = None,
-) -> PaginatedResponse[ArticleRead]:
+) -> CursorPaginatedResponse[ArticleRead]:
     return await ArticleCrud.cursor_paginate(
         session=session,
         cursor=cursor,
@@ -57,3 +61,30 @@ async def list_articles_cursor(
         order_by=order_by,
         schema=ArticleRead,
     )
+
+
+@router.get("/")
+async def list_articles(
+    session: SessionDep,
+    filter_by: Annotated[dict[str, list[str]], Depends(ArticleCrud.filter_params())],
+    order_by: Annotated[
+        OrderByClause | None,
+        Depends(ArticleCrud.order_params(default_field=Article.created_at)),
+    ],
+    pagination_type: PaginationType = PaginationType.OFFSET,
+    page: int = Query(1, ge=1),
+    cursor: str | None = None,
+    items_per_page: int = Query(20, ge=1, le=100),
+    search: str | None = None,
+) -> PaginatedResponse[ArticleRead]:
+    return await ArticleCrud.paginate(
+        session,
+        pagination_type=pagination_type,
+        page=page,
+        cursor=cursor,
+        items_per_page=items_per_page,
+        search=search,
+        filter_by=filter_by or None,
+        order_by=order_by,
+        schema=ArticleRead,
+    )

mkdocs.yml

@@ -0,0 +1,5 @@
+# Minimal stub for mike compatibility.
+# The actual build is handled by zensical (see scripts/mkdocs shim).
+site_name: FastAPI Toolsets
+docs_dir: docs
+site_dir: site

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fastapi-toolsets"
-version = "1.3.0"
+version = "2.3.0"
 description = "Production-ready utilities for FastAPI applications"
 readme = "README.md"
 license = "MIT"
@@ -79,8 +79,9 @@ tests = [
     "pytest>=8.0.0",
 ]
 docs = [
+    "mike>=2.0.0",
     "mkdocstrings-python>=2.0.2",
-    "zensical>=0.0.23",
+    "zensical>=0.0.28",
 ]
 
 [build-system]

scripts/mkdocs

@@ -0,0 +1,60 @@
+#!/usr/bin/env python3
+"""mkdocs shim for mike compatibility.
+
+mike parses mkdocs.yml (valid YAML stub) for its Python internals, then calls
+`mkdocs build --config-file <mike-injected-temp.yml>` as a subprocess.
+
+This shim intercepts that subprocess call, ignores the temp config, and
+delegates the actual build to `zensical build -f zensical.toml` instead.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+
+
+def main() -> None:
+    args = sys.argv[1:]
+
+    # mike calls `mkdocs --version` to embed in the commit message
+    if args and args[0] == "--version":
+        print("mkdocs, version 1.0.0 (zensical shim)")
+        return
+
+    if not args or args[0] != "build":
+        result = subprocess.run(["python3", "-m", "mkdocs"] + args)
+        sys.exit(result.returncode)
+
+    config_file = "mkdocs.yml"
+    clean = False
+
+    i = 1
+    while i < len(args):
+        if args[i] in ("-f", "--config-file") and i + 1 < len(args):
+            config_file = args[i + 1]
+            i += 2
+        elif args[i] in ("-c", "--clean"):
+            clean = True
+            i += 1
+        elif args[i] == "--dirty":
+            i += 1
+        else:
+            i += 1
+
+    # mike creates a temp file prefixed with "mike-mkdocs"; always delegate
+    # the actual build to zensical regardless of which config was passed.
+    del config_file  # unused — zensical auto-discovers zensical.toml
+
+    cmd = ["zensical", "build"]
+    if clean:
+        cmd.append("--clean")
+
+    env = os.environ.copy()
+    result = subprocess.run(cmd, env=env)
+    sys.exit(result.returncode)
+
+
+if __name__ == "__main__":
+    main()

src/fastapi_toolsets/__init__.py

@@ -21,4 +21,4 @@ Example usage:
         return Response(data={"user": user.username}, message="Success")
 """
 
-__version__ = "1.3.0"
+__version__ = "2.3.0"

src/fastapi_toolsets/cli/commands/fixtures.py

@@ -72,7 +72,7 @@ async def load(
     registry = get_fixtures_registry()
     db_context = get_db_context()
 
-    context_list = [c.value for c in contexts] if contexts else [Context.BASE]
+    context_list = list(contexts) if contexts else [Context.BASE]
 
     ordered = registry.resolve_context_dependencies(*context_list)
 

src/fastapi_toolsets/crud/__init__.py

@@ -1,14 +1,19 @@
 """Generic async CRUD operations for SQLAlchemy models."""
 
 from ..exceptions import InvalidFacetFilterError, NoSearchableFieldsError
-from .factory import CrudFactory, JoinType, M2MFieldType, OrderByClause
+from ..schemas import PaginationType
-from .search import (
+from ..types import (
     FacetFieldType,
-    SearchConfig,
+    JoinType,
-    get_searchable_fields,
+    M2MFieldType,
+    OrderByClause,
+    SearchFieldType,
 )
+from .factory import AsyncCrud, CrudFactory
+from .search import SearchConfig, get_searchable_fields
 
 __all__ = [
+    "AsyncCrud",
     "CrudFactory",
     "FacetFieldType",
     "get_searchable_fields",
@@ -17,5 +22,7 @@ __all__ = [
     "M2MFieldType",
     "NoSearchableFieldsError",
     "OrderByClause",
+    "PaginationType",
     "SearchConfig",
+    "SearchFieldType",
 ]

src/fastapi_toolsets/crud/search.py

@@ -1,24 +1,23 @@
 """Search utilities for AsyncCrud."""
 
 import asyncio
+import functools
 from collections import Counter
 from collections.abc import Sequence
-from dataclasses import dataclass
+from dataclasses import dataclass, replace
 from typing import TYPE_CHECKING, Any, Literal
 
-from sqlalchemy import String, or_, select
+from sqlalchemy import String, and_, or_, select
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.orm import DeclarativeBase
 from sqlalchemy.orm.attributes import InstrumentedAttribute
 
 from ..exceptions import InvalidFacetFilterError, NoSearchableFieldsError
+from ..types import FacetFieldType, SearchFieldType
 
 if TYPE_CHECKING:
     from sqlalchemy.sql.elements import ColumnElement
 
-SearchFieldType = InstrumentedAttribute[Any] | tuple[InstrumentedAttribute[Any], ...]
-FacetFieldType = SearchFieldType
-
 
 @dataclass
 class SearchConfig:
@@ -37,6 +36,7 @@ class SearchConfig:
     match_mode: Literal["any", "all"] = "any"
 
 
+@functools.lru_cache(maxsize=128)
 def get_searchable_fields(
     model: type[DeclarativeBase],
     *,
@@ -101,14 +101,11 @@ def build_search_filters(
     if isinstance(search, str):
         config = SearchConfig(query=search, fields=search_fields)
     else:
-        config = search
+        config = (
-        if search_fields is not None:
+            replace(search, fields=search_fields)
-            config = SearchConfig(
+            if search_fields is not None
-                query=config.query,
+            else search
-                fields=search_fields,
+        )
-                case_sensitive=config.case_sensitive,
-                match_mode=config.match_mode,
-            )
 
     if not config.query or not config.query.strip():
         return [], []
@@ -227,8 +224,6 @@ async def build_facets(
                 q = q.outerjoin(rel)
 
         if base_filters:
-            from sqlalchemy import and_
-
             q = q.where(and_(*base_filters))
 
         q = q.order_by(column)

src/fastapi_toolsets/db.py

@@ -7,15 +7,19 @@ from enum import Enum
 from typing import Any, TypeVar
 
 from sqlalchemy import text
-from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
 from sqlalchemy.orm import DeclarativeBase
 
+from .exceptions import NotFoundError
+
 __all__ = [
     "LockMode",
+    "cleanup_tables",
+    "create_database",
     "create_db_context",
     "create_db_dependency",
-    "lock_tables",
     "get_transaction",
+    "lock_tables",
     "wait_for_row_change",
 ]
 
@@ -186,6 +190,71 @@ async def lock_tables(
         yield session
 
 
+async def create_database(
+    db_name: str,
+    *,
+    server_url: str,
+) -> None:
+    """Create a database.
+
+    Connects to *server_url* using ``AUTOCOMMIT`` isolation and issues a
+    ``CREATE DATABASE`` statement for *db_name*.
+
+    Args:
+        db_name: Name of the database to create.
+        server_url: URL used for server-level DDL (must point to an existing
+            database on the same server).
+
+    Example:
+        ```python
+        from fastapi_toolsets.db import create_database
+
+        SERVER_URL = "postgresql+asyncpg://postgres:postgres@localhost/postgres"
+        await create_database("myapp_test", server_url=SERVER_URL)
+        ```
+    """
+    engine = create_async_engine(server_url, isolation_level="AUTOCOMMIT")
+    try:
+        async with engine.connect() as conn:
+            await conn.execute(text(f"CREATE DATABASE {db_name}"))
+    finally:
+        await engine.dispose()
+
+
+async def cleanup_tables(
+    session: AsyncSession,
+    base: type[DeclarativeBase],
+) -> None:
+    """Truncate all tables for fast between-test cleanup.
+
+    Executes a single ``TRUNCATE … RESTART IDENTITY CASCADE`` statement
+    across every table in *base*'s metadata, which is significantly faster
+    than dropping and re-creating tables between tests.
+
+    This is a no-op when the metadata contains no tables.
+
+    Args:
+        session: An active async database session.
+        base: SQLAlchemy DeclarativeBase class containing model metadata.
+
+    Example:
+        ```python
+        @pytest.fixture
+        async def db_session(worker_db_url):
+            async with create_db_session(worker_db_url, Base) as session:
+                yield session
+                await cleanup_tables(session, Base)
+        ```
+    """
+    tables = base.metadata.sorted_tables
+    if not tables:
+        return
+
+    table_names = ", ".join(f'"{t.name}"' for t in tables)
+    await session.execute(text(f"TRUNCATE {table_names} RESTART IDENTITY CASCADE"))
+    await session.commit()
+
+
 _M = TypeVar("_M", bound=DeclarativeBase)
 
 
@@ -216,7 +285,7 @@ async def wait_for_row_change(
         The refreshed model instance with updated values
 
     Raises:
-        LookupError: If the row does not exist or is deleted during polling
+        NotFoundError: If the row does not exist or is deleted during polling
         TimeoutError: If timeout expires before a change is detected
 
     Example:
@@ -237,7 +306,7 @@ async def wait_for_row_change(
     """
     instance = await session.get(model, pk_value)
     if instance is None:
-        raise LookupError(f"{model.__name__} with pk={pk_value!r} not found")
+        raise NotFoundError(f"{model.__name__} with pk={pk_value!r} not found")
 
     if columns is not None:
         watch_cols = columns
@@ -261,7 +330,7 @@ async def wait_for_row_change(
         instance = await session.get(model, pk_value)
 
         if instance is None:
-            raise LookupError(f"{model.__name__} with pk={pk_value!r} was deleted")
+            raise NotFoundError(f"{model.__name__} with pk={pk_value!r} was deleted")
 
         current = {col: getattr(instance, col) for col in watch_cols}
         if current != initial:

src/fastapi_toolsets/dependencies.py

@@ -1,19 +1,27 @@
 """Dependency factories for FastAPI routes."""
 
 import inspect
-from collections.abc import AsyncGenerator, Callable
+import typing
-from typing import Any, TypeVar, cast
+from collections.abc import Callable
+from typing import Any, cast
 
 from fastapi import Depends
+from fastapi.params import Depends as DependsClass
 from sqlalchemy.ext.asyncio import AsyncSession
-from sqlalchemy.orm import DeclarativeBase
 
 from .crud import CrudFactory
+from .types import ModelType, SessionDependency
 
 __all__ = ["BodyDependency", "PathDependency"]
 
-ModelType = TypeVar("ModelType", bound=DeclarativeBase)
+
-SessionDependency = Callable[[], AsyncGenerator[AsyncSession, None]]
+def _unwrap_session_dep(session_dep: SessionDependency) -> Callable[..., Any]:
+    """Extract the plain callable from ``Annotated[AsyncSession, Depends(fn)]`` if needed."""
+    if typing.get_origin(session_dep) is typing.Annotated:
+        for arg in typing.get_args(session_dep)[1:]:
+            if isinstance(arg, DependsClass):
+                return arg.dependency
+    return session_dep
 
 
 def PathDependency(
@@ -47,6 +55,7 @@ def PathDependency(
         ): ...
         ```
     """
+    session_callable = _unwrap_session_dep(session_dep)
     crud = CrudFactory(model)
     name = (
         param_name
@@ -56,7 +65,7 @@ def PathDependency(
     python_type = field.type.python_type
 
     async def dependency(
-        session: AsyncSession = Depends(session_dep), **kwargs: Any
+        session: AsyncSession = Depends(session_callable), **kwargs: Any
     ) -> ModelType:
         value = kwargs[name]
         return await crud.get(session, filters=[field == value])
@@ -73,7 +82,7 @@ def PathDependency(
                     "session",
                     inspect.Parameter.KEYWORD_ONLY,
                     annotation=AsyncSession,
-                    default=Depends(session_dep),
+                    default=Depends(session_callable),
                 ),
             ]
         ),
@@ -115,11 +124,12 @@ def BodyDependency(
         ): ...
         ```
     """
+    session_callable = _unwrap_session_dep(session_dep)
     crud = CrudFactory(model)
     python_type = field.type.python_type
 
     async def dependency(
-        session: AsyncSession = Depends(session_dep), **kwargs: Any
+        session: AsyncSession = Depends(session_callable), **kwargs: Any
     ) -> ModelType:
         value = kwargs[body_field]
         return await crud.get(session, filters=[field == value])
@@ -136,7 +146,7 @@ def BodyDependency(
                     "session",
                     inspect.Parameter.KEYWORD_ONLY,
                     annotation=AsyncSession,
-                    default=Depends(session_dep),
+                    default=Depends(session_callable),
                 ),
             ]
         ),

src/fastapi_toolsets/exceptions/exceptions.py

@@ -6,32 +6,46 @@ from ..schemas import ApiError, ErrorResponse, ResponseStatus
 
 
 class ApiException(Exception):
-    """Base exception for API errors with structured response.
+    """Base exception for API errors with structured response."""
-
-    Subclass this to create custom API exceptions with consistent error format.
-    The exception handler will use api_error to generate the response.
-
-    Example:
-        ```python
-        class CustomError(ApiException):
-            api_error = ApiError(
-                code=400,
-                msg="Bad Request",
-                desc="The request was invalid.",
-                err_code="CUSTOM-400",
-            )
-        ```
-    """
 
     api_error: ClassVar[ApiError]
 
-    def __init__(self, detail: str | None = None):
+    def __init_subclass__(cls, abstract: bool = False, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+        if not abstract and not hasattr(cls, "api_error"):
+            raise TypeError(
+                f"{cls.__name__} must define an 'api_error' class attribute. "
+                "Pass abstract=True when creating intermediate base classes."
+            )
+
+    def __init__(
+        self,
+        detail: str | None = None,
+        *,
+        desc: str | None = None,
+        data: Any = None,
+    ) -> None:
         """Initialize the exception.
 
         Args:
-            detail: Optional override for the error message
+            detail: Optional human-readable message
+            desc: Optional per-instance override for the ``description`` field
+                in the HTTP response body.
+            data: Optional per-instance override for the ``data`` field in the
+                HTTP response body.
         """
-        super().__init__(detail or self.api_error.msg)
+        updates: dict[str, Any] = {}
+        if detail is not None:
+            updates["msg"] = detail
+        if desc is not None:
+            updates["desc"] = desc
+        if data is not None:
+            updates["data"] = data
+        if updates:
+            object.__setattr__(
+                self, "api_error", self.__class__.api_error.model_copy(update=updates)
+            )
+        super().__init__(self.api_error.msg)
 
 
 class UnauthorizedError(ApiException):
@@ -92,14 +106,15 @@ class NoSearchableFieldsError(ApiException):
         """Initialize the exception.
 
         Args:
-            model: The SQLAlchemy model class that has no searchable fields
+            model: The model class that has no searchable fields configured.
         """
         self.model = model
-        detail = (
+        super().__init__(
-            f"No searchable fields found for model '{model.__name__}'. "
+            desc=(
-            "Provide 'search_fields' parameter or set 'searchable_fields' on the CRUD class."
+                f"No searchable fields found for model '{model.__name__}'. "
+                "Provide 'search_fields' parameter or set 'searchable_fields' on the CRUD class."
+            )
         )
-        super().__init__(detail)
 
 
 class InvalidFacetFilterError(ApiException):
@@ -116,16 +131,17 @@ class InvalidFacetFilterError(ApiException):
         """Initialize the exception.
 
         Args:
-            key: The unknown filter key provided by the caller
+            key: The unknown filter key provided by the caller.
-            valid_keys: Set of valid keys derived from the declared facet_fields
+            valid_keys: Set of valid keys derived from the declared facet_fields.
         """
         self.key = key
         self.valid_keys = valid_keys
-        detail = (
+        super().__init__(
-            f"'{key}' is not a declared facet field. "
+            desc=(
-            f"Valid keys: {sorted(valid_keys) or 'none — set facet_fields on the CRUD class'}."
+                f"'{key}' is not a declared facet field. "
+                f"Valid keys: {sorted(valid_keys) or 'none — set facet_fields on the CRUD class'}."
+            )
         )
-        super().__init__(detail)
 
 
 class InvalidOrderFieldError(ApiException):
@@ -142,15 +158,14 @@ class InvalidOrderFieldError(ApiException):
         """Initialize the exception.
 
         Args:
-            field: The unknown order field provided by the caller
+            field: The unknown order field provided by the caller.
-            valid_fields: List of valid field names
+            valid_fields: List of valid field names.
         """
         self.field = field
         self.valid_fields = valid_fields
-        detail = (
+        super().__init__(
-            f"'{field}' is not an allowed order field. Valid fields: {valid_fields}."
+            desc=f"'{field}' is not an allowed order field. Valid fields: {valid_fields}."
         )
-        super().__init__(detail)
 
 
 def generate_error_responses(
@@ -158,44 +173,39 @@ def generate_error_responses(
 ) -> dict[int | str, dict[str, Any]]:
     """Generate OpenAPI response documentation for exceptions.
 
-    Use this to document possible error responses for an endpoint.
-
     Args:
-        *errors: Exception classes that inherit from ApiException
+        *errors: Exception classes that inherit from ApiException.
 
     Returns:
-        Dict suitable for FastAPI's responses parameter
+        Dict suitable for FastAPI's ``responses`` parameter.
-
-    Example:
-        ```python
-        from fastapi_toolsets.exceptions import generate_error_responses, UnauthorizedError, ForbiddenError
-
-        @app.get(
-            "/admin",
-            responses=generate_error_responses(UnauthorizedError, ForbiddenError)
-        )
-        async def admin_endpoint():
-            ...
-        ```
     """
     responses: dict[int | str, dict[str, Any]] = {}
 
     for error in errors:
         api_error = error.api_error
+        code = api_error.code
 
-        responses[api_error.code] = {
+        if code not in responses:
-            "model": ErrorResponse,
+            responses[code] = {
-            "description": api_error.msg,
+                "model": ErrorResponse,
-            "content": {
+                "description": api_error.msg,
-                "application/json": {
+                "content": {
-                    "example": {
+                    "application/json": {
-                        "data": api_error.data,
+                        "examples": {},
-                        "status": ResponseStatus.FAIL.value,
-                        "message": api_error.msg,
-                        "description": api_error.desc,
-                        "error_code": api_error.err_code,
                     }
-                }
+                },
+            }
+
+        responses[code]["content"]["application/json"]["examples"][
+            api_error.err_code
+        ] = {
+            "summary": api_error.msg,
+            "value": {
+                "data": api_error.data,
+                "status": ResponseStatus.FAIL.value,
+                "message": api_error.msg,
+                "description": api_error.desc,
+                "error_code": api_error.err_code,
             },
         }
 

src/fastapi_toolsets/exceptions/handler.py

@@ -1,56 +1,41 @@
 """Exception handlers for FastAPI applications."""
 
+from collections.abc import Callable
 from typing import Any
 
 from fastapi import FastAPI, Request, Response, status
-from fastapi.exceptions import RequestValidationError, ResponseValidationError
+from fastapi.exceptions import (
-from fastapi.openapi.utils import get_openapi
+    HTTPException,
+    RequestValidationError,
+    ResponseValidationError,
+)
 from fastapi.responses import JSONResponse
 
 from ..schemas import ErrorResponse, ResponseStatus
 from .exceptions import ApiException
 
+_VALIDATION_LOCATION_PARAMS: frozenset[str] = frozenset(
+    {"body", "query", "path", "header", "cookie"}
+)
+
 
 def init_exceptions_handlers(app: FastAPI) -> FastAPI:
     """Register exception handlers and custom OpenAPI schema on a FastAPI app.
 
-    Installs handlers for :class:`ApiException`, validation errors, and
-    unhandled exceptions, and replaces the default 422 schema with a
-    consistent error format.
-
     Args:
-        app: FastAPI application instance
+        app: FastAPI application instance.
 
     Returns:
-        The same FastAPI instance (for chaining)
+        The same FastAPI instance (for chaining).
-
-    Example:
-        ```python
-        from fastapi import FastAPI
-        from fastapi_toolsets.exceptions import init_exceptions_handlers
-
-        app = FastAPI()
-        init_exceptions_handlers(app)
-        ```
     """
     _register_exception_handlers(app)
-    app.openapi = lambda: _custom_openapi(app)  # type: ignore[method-assign]
+    _original_openapi = app.openapi
+    app.openapi = lambda: _patched_openapi(app, _original_openapi)  # type: ignore[method-assign]
     return app
 
 
 def _register_exception_handlers(app: FastAPI) -> None:
-    """Register all exception handlers on a FastAPI application.
+    """Register all exception handlers on a FastAPI application."""
-
-    Args:
-        app: FastAPI application instance
-
-    Example:
-        from fastapi import FastAPI
-        from fastapi_toolsets.exceptions import init_exceptions_handlers
-
-        app = FastAPI()
-        init_exceptions_handlers(app)
-    """
 
     @app.exception_handler(ApiException)
     async def api_exception_handler(request: Request, exc: ApiException) -> Response:
@@ -62,12 +47,25 @@ def _register_exception_handlers(app: FastAPI) -> None:
             description=api_error.desc,
             error_code=api_error.err_code,
         )
-
         return JSONResponse(
             status_code=api_error.code,
             content=error_response.model_dump(),
         )
 
+    @app.exception_handler(HTTPException)
+    async def http_exception_handler(request: Request, exc: HTTPException) -> Response:
+        """Handle Starlette/FastAPI HTTPException with a consistent error format."""
+        detail = exc.detail if isinstance(exc.detail, str) else "HTTP Error"
+        error_response = ErrorResponse(
+            message=detail,
+            error_code=f"HTTP-{exc.status_code}",
+        )
+        return JSONResponse(
+            status_code=exc.status_code,
+            content=error_response.model_dump(),
+            headers=getattr(exc, "headers", None),
+        )
+
     @app.exception_handler(RequestValidationError)
     async def request_validation_handler(
         request: Request, exc: RequestValidationError
@@ -90,7 +88,6 @@ def _register_exception_handlers(app: FastAPI) -> None:
             description="An unexpected error occurred. Please try again later.",
             error_code="SERVER-500",
         )
-
         return JSONResponse(
             status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
             content=error_response.model_dump(),
@@ -105,11 +102,10 @@ def _format_validation_error(
     formatted_errors = []
 
     for error in errors:
-        field_path = ".".join(
+        locs = error["loc"]
-            str(loc)
+        if locs and locs[0] in _VALIDATION_LOCATION_PARAMS:
-            for loc in error["loc"]
+            locs = locs[1:]
-            if loc not in ("body", "query", "path", "header", "cookie")
+        field_path = ".".join(str(loc) for loc in locs)
-        )
         formatted_errors.append(
             {
                 "field": field_path or "root",
@@ -131,34 +127,22 @@ def _format_validation_error(
     )
 
 
-def _custom_openapi(app: FastAPI) -> dict[str, Any]:
+def _patched_openapi(
-    """Generate custom OpenAPI schema with standardized error format.
+    app: FastAPI, original_openapi: Callable[[], dict[str, Any]]
-
+) -> dict[str, Any]:
-    Replaces default 422 validation error responses with the custom format.
+    """Generate the OpenAPI schema and replace default 422 responses.
 
     Args:
-        app: FastAPI application instance
+        app: FastAPI application instance.
+        original_openapi: The previous ``app.openapi`` callable to delegate to.
 
     Returns:
-        OpenAPI schema dict
+        Patched OpenAPI schema dict.
-
-    Example:
-        from fastapi import FastAPI
-        from fastapi_toolsets.exceptions import init_exceptions_handlers
-
-        app = FastAPI()
-        init_exceptions_handlers(app)  # Automatically sets custom OpenAPI
     """
     if app.openapi_schema:
         return app.openapi_schema
 
-    openapi_schema = get_openapi(
+    openapi_schema = original_openapi()
-        title=app.title,
-        version=app.version,
-        openapi_version=app.openapi_version,
-        description=app.description,
-        routes=app.routes,
-    )
 
     for path_data in openapi_schema.get("paths", {}).values():
         for operation in path_data.values():
@@ -168,20 +152,25 @@ def _custom_openapi(app: FastAPI) -> dict[str, Any]:
                         "description": "Validation Error",
                         "content": {
                             "application/json": {
-                                "example": {
+                                "examples": {
-                                    "data": {
+                                    "VAL-422": {
-                                        "errors": [
+                                        "summary": "Validation Error",
-                                            {
+                                        "value": {
-                                                "field": "field_name",
+                                            "data": {
-                                                "message": "value is not valid",
+                                                "errors": [
-                                                "type": "value_error",
+                                                    {
-                                            }
+                                                        "field": "field_name",
-                                        ]
+                                                        "message": "value is not valid",
-                                    },
+                                                        "type": "value_error",
-                                    "status": ResponseStatus.FAIL.value,
+                                                    }
-                                    "message": "Validation Error",
+                                                ]
-                                    "description": "1 validation error(s) detected",
+                                            },
-                                    "error_code": "VAL-422",
+                                            "status": ResponseStatus.FAIL.value,
+                                            "message": "Validation Error",
+                                            "description": "1 validation error(s) detected",
+                                            "error_code": "VAL-422",
+                                        },
+                                    }
                                 }
                             }
                         },

src/fastapi_toolsets/fixtures/utils.py

@@ -1,24 +1,84 @@
 """Fixture loading utilities for database seeding."""
 
 from collections.abc import Callable, Sequence
-from typing import Any, TypeVar
+from typing import Any
 
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.orm import DeclarativeBase
 
 from ..db import get_transaction
 from ..logger import get_logger
+from ..types import ModelType
 from .enum import LoadStrategy
 from .registry import Context, FixtureRegistry
 
 logger = get_logger()
 
-T = TypeVar("T", bound=DeclarativeBase)
+
+async def _load_ordered(
+    session: AsyncSession,
+    registry: FixtureRegistry,
+    ordered_names: list[str],
+    strategy: LoadStrategy,
+) -> dict[str, list[DeclarativeBase]]:
+    """Load fixtures in order."""
+    results: dict[str, list[DeclarativeBase]] = {}
+
+    for name in ordered_names:
+        fixture = registry.get(name)
+        instances = list(fixture.func())
+
+        if not instances:
+            results[name] = []
+            continue
+
+        model_name = type(instances[0]).__name__
+        loaded: list[DeclarativeBase] = []
+
+        async with get_transaction(session):
+            for instance in instances:
+                if strategy == LoadStrategy.INSERT:
+                    session.add(instance)
+                    loaded.append(instance)
+
+                elif strategy == LoadStrategy.MERGE:
+                    merged = await session.merge(instance)
+                    loaded.append(merged)
+
+                else:  # LoadStrategy.SKIP_EXISTING
+                    pk = _get_primary_key(instance)
+                    if pk is not None:
+                        existing = await session.get(type(instance), pk)
+                        if existing is None:
+                            session.add(instance)
+                            loaded.append(instance)
+                    else:
+                        session.add(instance)
+                        loaded.append(instance)
+
+        results[name] = loaded
+        logger.info(f"Loaded fixture '{name}': {len(loaded)} {model_name}(s)")
+
+    return results
+
+
+def _get_primary_key(instance: DeclarativeBase) -> Any | None:
+    """Get the primary key value of a model instance."""
+    mapper = instance.__class__.__mapper__
+    pk_cols = mapper.primary_key
+
+    if len(pk_cols) == 1:
+        return getattr(instance, pk_cols[0].name, None)
+
+    pk_values = tuple(getattr(instance, col.name, None) for col in pk_cols)
+    if all(v is not None for v in pk_values):
+        return pk_values
+    return None
 
 
 def get_obj_by_attr(
-    fixtures: Callable[[], Sequence[T]], attr_name: str, value: Any
+    fixtures: Callable[[], Sequence[ModelType]], attr_name: str, value: Any
-) -> T:
+) -> ModelType:
     """Get a SQLAlchemy model instance by matching an attribute value.
 
     Args:
@@ -57,13 +117,6 @@ async def load_fixtures(
 
     Returns:
         Dict mapping fixture names to loaded instances
-
-    Example:
-        ```python
-        # Loads 'roles' first (dependency), then 'users'
-        result = await load_fixtures(session, fixtures, "users")
-        print(result["users"])  # [User(...), ...]
-        ```
     """
     ordered = registry.resolve_dependencies(*names)
     return await _load_ordered(session, registry, ordered, strategy)
@@ -85,76 +138,6 @@ async def load_fixtures_by_context(
 
     Returns:
         Dict mapping fixture names to loaded instances
-
-    Example:
-        ```python
-        # Load base + testing fixtures
-        await load_fixtures_by_context(
-            session, fixtures,
-            Context.BASE, Context.TESTING
-        )
-        ```
     """
     ordered = registry.resolve_context_dependencies(*contexts)
     return await _load_ordered(session, registry, ordered, strategy)
-
-
-async def _load_ordered(
-    session: AsyncSession,
-    registry: FixtureRegistry,
-    ordered_names: list[str],
-    strategy: LoadStrategy,
-) -> dict[str, list[DeclarativeBase]]:
-    """Load fixtures in order."""
-    results: dict[str, list[DeclarativeBase]] = {}
-
-    for name in ordered_names:
-        fixture = registry.get(name)
-        instances = list(fixture.func())
-
-        if not instances:
-            results[name] = []
-            continue
-
-        model_name = type(instances[0]).__name__
-        loaded: list[DeclarativeBase] = []
-
-        async with get_transaction(session):
-            for instance in instances:
-                if strategy == LoadStrategy.INSERT:
-                    session.add(instance)
-                    loaded.append(instance)
-
-                elif strategy == LoadStrategy.MERGE:
-                    merged = await session.merge(instance)
-                    loaded.append(merged)
-
-                elif strategy == LoadStrategy.SKIP_EXISTING:
-                    pk = _get_primary_key(instance)
-                    if pk is not None:
-                        existing = await session.get(type(instance), pk)
-                        if existing is None:
-                            session.add(instance)
-                            loaded.append(instance)
-                    else:
-                        session.add(instance)
-                        loaded.append(instance)
-
-        results[name] = loaded
-        logger.info(f"Loaded fixture '{name}': {len(loaded)} {model_name}(s)")
-
-    return results
-
-
-def _get_primary_key(instance: DeclarativeBase) -> Any | None:
-    """Get the primary key value of a model instance."""
-    mapper = instance.__class__.__mapper__
-    pk_cols = mapper.primary_key
-
-    if len(pk_cols) == 1:
-        return getattr(instance, pk_cols[0].name, None)
-
-    pk_values = tuple(getattr(instance, col.name, None) for col in pk_cols)
-    if all(v is not None for v in pk_values):
-        return pk_values
-    return None

src/fastapi_toolsets/metrics/handler.py

@@ -51,19 +51,25 @@ def init_metrics(
     """
     for provider in registry.get_providers():
         logger.debug("Initialising metric provider '%s'", provider.name)
-        provider.func()
+        registry._instances[provider.name] = provider.func()
 
-    collectors = registry.get_collectors()
+    # Partition collectors and cache env check at startup — both are stable for the app lifetime.
+    async_collectors = [
+        c for c in registry.get_collectors() if asyncio.iscoroutinefunction(c.func)
+    ]
+    sync_collectors = [
+        c for c in registry.get_collectors() if not asyncio.iscoroutinefunction(c.func)
+    ]
+    multiprocess_mode = _is_multiprocess()
 
     @app.get(path, include_in_schema=False)
     async def metrics_endpoint() -> Response:
-        for collector in collectors:
+        for collector in sync_collectors:
-            if asyncio.iscoroutinefunction(collector.func):
+            collector.func()
-                await collector.func()
+        for collector in async_collectors:
-            else:
+            await collector.func()
-                collector.func()
 
-        if _is_multiprocess():
+        if multiprocess_mode:
             prom_registry = CollectorRegistry()
             multiprocess.MultiProcessCollector(prom_registry)
             output = generate_latest(prom_registry)

src/fastapi_toolsets/metrics/registry.py

@@ -19,31 +19,11 @@ class Metric:
 
 
 class MetricsRegistry:
-    """Registry for managing Prometheus metric providers and collectors.
+    """Registry for managing Prometheus metric providers and collectors."""
-
-    Example:
-        ```python
-        from prometheus_client import Counter, Gauge
-        from fastapi_toolsets.metrics import MetricsRegistry
-
-        metrics = MetricsRegistry()
-
-        @metrics.register
-        def http_requests():
-            return Counter("http_requests_total", "Total HTTP requests", ["method", "status"])
-
-        @metrics.register(name="db_pool")
-        def database_pool_size():
-            return Gauge("db_pool_size", "Database connection pool size")
-
-        @metrics.register(collect=True)
-        def collect_queue_depth(gauge=Gauge("queue_depth", "Current queue depth")):
-            gauge.set(get_current_queue_depth())
-        ```
-    """
 
     def __init__(self) -> None:
         self._metrics: dict[str, Metric] = {}
+        self._instances: dict[str, Any] = {}
 
     def register(
         self,
@@ -61,17 +41,6 @@ class MetricsRegistry:
             name: Metric name (defaults to function name).
             collect: If ``True``, the function is called on every scrape.
                 If ``False`` (default), called once at init time.
-
-        Example:
-            ```python
-            @metrics.register
-            def my_counter():
-                return Counter("my_counter", "A counter")
-
-            @metrics.register(collect=True, name="queue")
-            def collect_queue_depth():
-                gauge.set(compute_depth())
-            ```
         """
 
         def decorator(fn: Callable[..., Any]) -> Callable[..., Any]:
@@ -87,6 +56,25 @@ class MetricsRegistry:
             return decorator(func)
         return decorator
 
+    def get(self, name: str) -> Any:
+        """Return the metric instance created by a provider.
+
+        Args:
+            name: The metric name (defaults to the provider function name).
+
+        Raises:
+            KeyError: If the metric name is unknown or ``init_metrics`` has not
+                been called yet.
+        """
+        if name not in self._instances:
+            if name in self._metrics:
+                raise KeyError(
+                    f"Metric '{name}' exists but has not been initialized yet. "
+                    "Ensure init_metrics() has been called before accessing metric instances."
+                )
+            raise KeyError(f"Unknown metric '{name}'.")
+        return self._instances[name]
+
     def include_registry(self, registry: "MetricsRegistry") -> None:
         """Include another :class:`MetricsRegistry` into this one.
 
@@ -95,18 +83,6 @@ class MetricsRegistry:
 
         Raises:
             ValueError: If a metric name already exists in the current registry.
-
-        Example:
-            ```python
-            main = MetricsRegistry()
-            sub = MetricsRegistry()
-
-            @sub.register
-            def sub_metric():
-                return Counter("sub_total", "Sub counter")
-
-            main.include_registry(sub)
-            ```
         """
         for metric_name, definition in registry._metrics.items():
             if metric_name in self._metrics:

src/fastapi_toolsets/models/__init__.py

@@ -0,0 +1,21 @@
+"""SQLAlchemy model mixins for common column patterns."""
+
+from .columns import (
+    CreatedAtMixin,
+    TimestampMixin,
+    UUIDMixin,
+    UUIDv7Mixin,
+    UpdatedAtMixin,
+)
+from .watched import ModelEvent, WatchedFieldsMixin, watch
+
+__all__ = [
+    "ModelEvent",
+    "UUIDMixin",
+    "UUIDv7Mixin",
+    "CreatedAtMixin",
+    "UpdatedAtMixin",
+    "TimestampMixin",
+    "WatchedFieldsMixin",
+    "watch",
+]

src/fastapi_toolsets/models/columns.py

@@ -0,0 +1,58 @@
+"""SQLAlchemy column mixins for common column patterns."""
+
+import uuid
+from datetime import datetime
+
+from sqlalchemy import DateTime, Uuid, text
+from sqlalchemy.orm import Mapped, mapped_column
+
+__all__ = [
+    "UUIDMixin",
+    "UUIDv7Mixin",
+    "CreatedAtMixin",
+    "UpdatedAtMixin",
+    "TimestampMixin",
+]
+
+
+class UUIDMixin:
+    """Mixin that adds a UUID primary key auto-generated by the database."""
+
+    id: Mapped[uuid.UUID] = mapped_column(
+        Uuid,
+        primary_key=True,
+        server_default=text("gen_random_uuid()"),
+    )
+
+
+class UUIDv7Mixin:
+    """Mixin that adds a UUIDv7 primary key auto-generated by the database."""
+
+    id: Mapped[uuid.UUID] = mapped_column(
+        Uuid,
+        primary_key=True,
+        server_default=text("uuidv7()"),
+    )
+
+
+class CreatedAtMixin:
+    """Mixin that adds a ``created_at`` timestamp column."""
+
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=text("clock_timestamp()"),
+    )
+
+
+class UpdatedAtMixin:
+    """Mixin that adds an ``updated_at`` timestamp column."""
+
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=text("clock_timestamp()"),
+        onupdate=text("clock_timestamp()"),
+    )
+
+
+class TimestampMixin(CreatedAtMixin, UpdatedAtMixin):
+    """Mixin that combines ``created_at`` and ``updated_at`` timestamp columns."""

src/fastapi_toolsets/models/watched.py

@@ -0,0 +1,204 @@
+"""Field-change monitoring via SQLAlchemy session events."""
+
+import asyncio
+import weakref
+from collections.abc import Awaitable
+from enum import Enum
+from typing import Any, TypeVar
+
+from sqlalchemy import event
+from sqlalchemy import inspect as sa_inspect
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from ..logger import get_logger
+
+__all__ = ["ModelEvent", "WatchedFieldsMixin", "watch"]
+
+_logger = get_logger()
+_T = TypeVar("_T")
+_CALLBACK_ERROR_MSG = "WatchedFieldsMixin callback raised an unhandled exception"
+_WATCHED_FIELDS: weakref.WeakKeyDictionary[type, list[str]] = (
+    weakref.WeakKeyDictionary()
+)
+_SESSION_PENDING_NEW = "_ft_pending_new"
+_SESSION_CREATES = "_ft_creates"
+_SESSION_DELETES = "_ft_deletes"
+_SESSION_UPDATES = "_ft_updates"
+
+
+class ModelEvent(str, Enum):
+    """Event types emitted by :class:`WatchedFieldsMixin`."""
+
+    CREATE = "create"
+    DELETE = "delete"
+    UPDATE = "update"
+
+
+def watch(*fields: str) -> Any:
+    """Class decorator to filter which fields trigger ``on_update``.
+
+    Args:
+        *fields: One or more field names to watch. At least one name is required.
+
+    Raises:
+        ValueError: If called with no field names.
+    """
+    if not fields:
+        raise ValueError("@watch requires at least one field name.")
+
+    def decorator(cls: type[_T]) -> type[_T]:
+        _WATCHED_FIELDS[cls] = list(fields)
+        return cls
+
+    return decorator
+
+
+def _upsert_changes(
+    pending: dict[int, tuple[Any, dict[str, dict[str, Any]]]],
+    obj: Any,
+    changes: dict[str, dict[str, Any]],
+) -> None:
+    """Insert or merge *changes* into *pending* for *obj*."""
+    key = id(obj)
+    if key in pending:
+        existing = pending[key][1]
+        for field, change in changes.items():
+            if field in existing:
+                existing[field]["new"] = change["new"]
+            else:
+                existing[field] = change
+    else:
+        pending[key] = (obj, changes)
+
+
+@event.listens_for(AsyncSession.sync_session_class, "after_flush")
+def _after_flush(session: Any, flush_context: Any) -> None:
+    # New objects: capture references while session.new is still populated.
+    # Values are read in _after_flush_postexec once RETURNING has been processed.
+    for obj in session.new:
+        if isinstance(obj, WatchedFieldsMixin):
+            session.info.setdefault(_SESSION_PENDING_NEW, []).append(obj)
+
+    # Deleted objects: capture before they leave the identity map.
+    for obj in session.deleted:
+        if isinstance(obj, WatchedFieldsMixin):
+            session.info.setdefault(_SESSION_DELETES, []).append(obj)
+
+    # Dirty objects: read old/new from SQLAlchemy attribute history.
+    for obj in session.dirty:
+        if not isinstance(obj, WatchedFieldsMixin):
+            continue
+
+        # None = not in dict = watch all fields; list = specific fields only
+        watched = _WATCHED_FIELDS.get(type(obj))
+        changes: dict[str, dict[str, Any]] = {}
+
+        attrs = (
+            # Specific fields
+            ((field, sa_inspect(obj).attrs[field]) for field in watched)
+            if watched is not None
+            # All mapped fields
+            else ((s.key, s) for s in sa_inspect(obj).attrs)
+        )
+        for field, attr_state in attrs:
+            history = attr_state.history
+            if history.has_changes() and history.deleted:
+                changes[field] = {
+                    "old": history.deleted[0],
+                    "new": history.added[0] if history.added else None,
+                }
+
+        if changes:
+            _upsert_changes(
+                session.info.setdefault(_SESSION_UPDATES, {}),
+                obj,
+                changes,
+            )
+
+
+@event.listens_for(AsyncSession.sync_session_class, "after_flush_postexec")
+def _after_flush_postexec(session: Any, flush_context: Any) -> None:
+    # New objects are now persistent and RETURNING values have been applied,
+    # so server defaults (id, created_at, …) are available via getattr.
+    pending_new: list[Any] = session.info.pop(_SESSION_PENDING_NEW, [])
+    if not pending_new:
+        return
+    session.info.setdefault(_SESSION_CREATES, []).extend(pending_new)
+
+
+@event.listens_for(AsyncSession.sync_session_class, "after_rollback")
+def _after_rollback(session: Any) -> None:
+    session.info.pop(_SESSION_PENDING_NEW, None)
+    session.info.pop(_SESSION_CREATES, None)
+    session.info.pop(_SESSION_DELETES, None)
+    session.info.pop(_SESSION_UPDATES, None)
+
+
+def _task_error_handler(task: asyncio.Task[Any]) -> None:
+    if not task.cancelled() and (exc := task.exception()):
+        _logger.error(_CALLBACK_ERROR_MSG, exc_info=exc)
+
+
+def _call_callback(loop: asyncio.AbstractEventLoop, fn: Any, *args: Any) -> None:
+    """Dispatch *fn* with *args*, handling both sync and async callables."""
+    try:
+        result = fn(*args)
+    except Exception as exc:
+        _logger.error(_CALLBACK_ERROR_MSG, exc_info=exc)
+        return
+    if asyncio.iscoroutine(result):
+        task = loop.create_task(result)
+        task.add_done_callback(_task_error_handler)
+
+
+@event.listens_for(AsyncSession.sync_session_class, "after_commit")
+def _after_commit(session: Any) -> None:
+    creates: list[Any] = session.info.pop(_SESSION_CREATES, [])
+    deletes: list[Any] = session.info.pop(_SESSION_DELETES, [])
+    field_changes: dict[int, tuple[Any, dict[str, dict[str, Any]]]] = session.info.pop(
+        _SESSION_UPDATES, {}
+    )
+
+    if not creates and not deletes and not field_changes:
+        return
+
+    try:
+        loop = asyncio.get_running_loop()
+    except RuntimeError:
+        return
+
+    for obj in creates:
+        _call_callback(loop, obj.on_create)
+
+    for obj in deletes:
+        _call_callback(loop, obj.on_delete)
+
+    for obj, changes in field_changes.values():
+        _call_callback(loop, obj.on_update, changes)
+
+
+class WatchedFieldsMixin:
+    """Mixin that enables lifecycle callbacks for SQLAlchemy models."""
+
+    def on_event(
+        self, event: ModelEvent, changes: dict[str, dict[str, Any]] | None = None
+    ) -> Awaitable[None] | None:
+        """Catch-all callback fired for every lifecycle event.
+
+        Args:
+            event: The event type (:attr:`ModelEvent.CREATE`, :attr:`ModelEvent.DELETE`,
+                or :attr:`ModelEvent.UPDATE`).
+            changes: Field changes for :attr:`ModelEvent.UPDATE`, ``None`` otherwise.
+        """
+
+    def on_create(self) -> Awaitable[None] | None:
+        """Called after INSERT commit."""
+        return self.on_event(ModelEvent.CREATE)
+
+    def on_delete(self) -> Awaitable[None] | None:
+        """Called after DELETE commit."""
+        return self.on_event(ModelEvent.DELETE)
+
+    def on_update(self, changes: dict[str, dict[str, Any]]) -> Awaitable[None] | None:
+        """Called after UPDATE commit when watched fields change."""
+        return self.on_event(ModelEvent.UPDATE, changes=changes)

src/fastapi_toolsets/pytest/utils.py

@@ -1,12 +1,12 @@
 """Pytest helper utilities for FastAPI testing."""
 
 import os
+import warnings
 from collections.abc import AsyncGenerator, Callable
 from contextlib import asynccontextmanager
 from typing import Any
 
 from httpx import ASGITransport, AsyncClient
-from sqlalchemy import text
 from sqlalchemy.engine import make_url
 from sqlalchemy.ext.asyncio import (
     AsyncSession,
@@ -15,7 +15,134 @@ from sqlalchemy.ext.asyncio import (
 )
 from sqlalchemy.orm import DeclarativeBase
 
-from ..db import create_db_context
+from sqlalchemy import text
+
+from ..db import (
+    cleanup_tables as _cleanup_tables,
+    create_database,
+    create_db_context,
+)
+
+
+async def cleanup_tables(
+    session: AsyncSession,
+    base: type[DeclarativeBase],
+) -> None:
+    """Truncate all tables for fast between-test cleanup.
+
+    .. deprecated::
+        Import ``cleanup_tables`` from ``fastapi_toolsets.db`` instead.
+        This re-export will be removed in v3.0.0.
+    """
+    warnings.warn(
+        "Importing cleanup_tables from fastapi_toolsets.pytest is deprecated "
+        "and will be removed in v3.0.0. "
+        "Use 'from fastapi_toolsets.db import cleanup_tables' instead.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    await _cleanup_tables(session=session, base=base)
+
+
+def _get_xdist_worker(default_test_db: str) -> str:
+    """Return the pytest-xdist worker name, or *default_test_db* when not running under xdist.
+
+    Reads the ``PYTEST_XDIST_WORKER`` environment variable that xdist sets
+    automatically in each worker process (e.g. ``"gw0"``, ``"gw1"``).
+    When xdist is not installed or not active, the variable is absent and
+    *default_test_db* is returned instead.
+
+    Args:
+        default_test_db: Fallback value returned when ``PYTEST_XDIST_WORKER``
+            is not set.
+    """
+    return os.environ.get("PYTEST_XDIST_WORKER", default_test_db)
+
+
+def worker_database_url(database_url: str, default_test_db: str) -> str:
+    """Derive a per-worker database URL for pytest-xdist parallel runs.
+
+    Appends ``_{worker_name}`` to the database name so each xdist worker
+    operates on its own database.  When not running under xdist,
+    ``_{default_test_db}`` is appended instead.
+
+    The worker name is read from the ``PYTEST_XDIST_WORKER`` environment
+    variable (set automatically by xdist in each worker process).
+
+    Args:
+        database_url: Original database connection URL.
+        default_test_db: Suffix appended to the database name when
+            ``PYTEST_XDIST_WORKER`` is not set.
+
+    Returns:
+        A database URL with a worker- or default-specific database name.
+    """
+    worker = _get_xdist_worker(default_test_db=default_test_db)
+
+    url = make_url(database_url)
+    url = url.set(database=f"{url.database}_{worker}")
+    return url.render_as_string(hide_password=False)
+
+
+@asynccontextmanager
+async def create_worker_database(
+    database_url: str,
+    default_test_db: str = "test_db",
+) -> AsyncGenerator[str, None]:
+    """Create and drop a per-worker database for pytest-xdist isolation.
+
+    Derives a worker-specific database URL using :func:`worker_database_url`,
+    then delegates to :func:`~fastapi_toolsets.db.create_database` to create
+    and drop it.  Intended for use as a **session-scoped** fixture.
+
+    When running under xdist the database name is suffixed with the worker
+    name (e.g. ``_gw0``).  Otherwise it is suffixed with *default_test_db*.
+
+    Args:
+        database_url: Original database connection URL (used as the server
+            connection and as the base for the worker database name).
+        default_test_db: Suffix appended to the database name when
+            ``PYTEST_XDIST_WORKER`` is not set. Defaults to ``"test_db"``.
+
+    Yields:
+        The worker-specific database URL.
+
+    Example:
+        ```python
+        from fastapi_toolsets.pytest import create_worker_database, create_db_session
+
+        DATABASE_URL = "postgresql+asyncpg://postgres:postgres@localhost/test_db"
+
+        @pytest.fixture(scope="session")
+        async def worker_db_url():
+            async with create_worker_database(DATABASE_URL) as url:
+                yield url
+
+        @pytest.fixture
+        async def db_session(worker_db_url):
+            async with create_db_session(
+                worker_db_url, Base, cleanup=True
+            ) as session:
+                yield session
+        ```
+    """
+    worker_url = worker_database_url(
+        database_url=database_url, default_test_db=default_test_db
+    )
+    worker_db_name: str = make_url(worker_url).database  # type: ignore[assignment]
+
+    engine = create_async_engine(database_url, isolation_level="AUTOCOMMIT")
+    try:
+        async with engine.connect() as conn:
+            await conn.execute(text(f"DROP DATABASE IF EXISTS {worker_db_name}"))
+        await create_database(db_name=worker_db_name, server_url=database_url)
+
+        yield worker_url
+
+        async with engine.connect() as conn:
+            await conn.execute(text(f"DROP DATABASE IF EXISTS {worker_db_name}"))
+    finally:
+        await engine.dispose()
 
 
 @asynccontextmanager
@@ -156,160 +283,3 @@ async def create_db_session(
                 await conn.run_sync(base.metadata.drop_all)
     finally:
         await engine.dispose()
-
-
-def _get_xdist_worker(default_test_db: str) -> str:
-    """Return the pytest-xdist worker name, or *default_test_db* when not running under xdist.
-
-    Reads the ``PYTEST_XDIST_WORKER`` environment variable that xdist sets
-    automatically in each worker process (e.g. ``"gw0"``, ``"gw1"``).
-    When xdist is not installed or not active, the variable is absent and
-    *default_test_db* is returned instead.
-
-    Args:
-        default_test_db: Fallback value returned when ``PYTEST_XDIST_WORKER``
-            is not set.
-    """
-    return os.environ.get("PYTEST_XDIST_WORKER", default_test_db)
-
-
-def worker_database_url(database_url: str, default_test_db: str) -> str:
-    """Derive a per-worker database URL for pytest-xdist parallel runs.
-
-    Appends ``_{worker_name}`` to the database name so each xdist worker
-    operates on its own database.  When not running under xdist,
-    ``_{default_test_db}`` is appended instead.
-
-    The worker name is read from the ``PYTEST_XDIST_WORKER`` environment
-    variable (set automatically by xdist in each worker process).
-
-    Args:
-        database_url: Original database connection URL.
-        default_test_db: Suffix appended to the database name when
-            ``PYTEST_XDIST_WORKER`` is not set.
-
-    Returns:
-        A database URL with a worker- or default-specific database name.
-
-    Example:
-        ```python
-        # With PYTEST_XDIST_WORKER="gw0":
-        url = worker_database_url(
-            "postgresql+asyncpg://user:pass@localhost/test_db",
-            default_test_db="test",
-        )
-        # "postgresql+asyncpg://user:pass@localhost/test_db_gw0"
-
-        # Without PYTEST_XDIST_WORKER:
-        url = worker_database_url(
-            "postgresql+asyncpg://user:pass@localhost/test_db",
-            default_test_db="test",
-        )
-        # "postgresql+asyncpg://user:pass@localhost/test_db_test"
-        ```
-    """
-    worker = _get_xdist_worker(default_test_db=default_test_db)
-
-    url = make_url(database_url)
-    url = url.set(database=f"{url.database}_{worker}")
-    return url.render_as_string(hide_password=False)
-
-
-@asynccontextmanager
-async def create_worker_database(
-    database_url: str,
-    default_test_db: str = "test_db",
-) -> AsyncGenerator[str, None]:
-    """Create and drop a per-worker database for pytest-xdist isolation.
-
-    Intended for use as a **session-scoped** fixture.  Connects to the server
-    using the original *database_url* (with ``AUTOCOMMIT`` isolation for DDL),
-    creates a dedicated database for the worker, and yields the worker-specific
-    URL.  On cleanup the worker database is dropped.
-
-    When running under xdist the database name is suffixed with the worker
-    name (e.g. ``_gw0``).  Otherwise it is suffixed with *default_test_db*.
-
-    Args:
-        database_url: Original database connection URL.
-        default_test_db: Suffix appended to the database name when
-            ``PYTEST_XDIST_WORKER`` is not set. Defaults to ``"test_db"``.
-
-    Yields:
-        The worker-specific database URL.
-
-    Example:
-        ```python
-        from fastapi_toolsets.pytest import (
-            create_worker_database, create_db_session,
-        )
-
-        DATABASE_URL = "postgresql+asyncpg://postgres:postgres@localhost/test_db"
-
-        @pytest.fixture(scope="session")
-        async def worker_db_url():
-            async with create_worker_database(DATABASE_URL) as url:
-                yield url
-
-        @pytest.fixture
-        async def db_session(worker_db_url):
-            async with create_db_session(
-                worker_db_url, Base, cleanup=True
-            ) as session:
-                yield session
-        ```
-    """
-    worker_url = worker_database_url(
-        database_url=database_url, default_test_db=default_test_db
-    )
-    worker_db_name = make_url(worker_url).database
-
-    engine = create_async_engine(
-        database_url,
-        isolation_level="AUTOCOMMIT",
-    )
-    try:
-        async with engine.connect() as conn:
-            await conn.execute(text(f"DROP DATABASE IF EXISTS {worker_db_name}"))
-            await conn.execute(text(f"CREATE DATABASE {worker_db_name}"))
-
-        yield worker_url
-
-        async with engine.connect() as conn:
-            await conn.execute(text(f"DROP DATABASE IF EXISTS {worker_db_name}"))
-    finally:
-        await engine.dispose()
-
-
-async def cleanup_tables(
-    session: AsyncSession,
-    base: type[DeclarativeBase],
-) -> None:
-    """Truncate all tables for fast between-test cleanup.
-
-    Executes a single ``TRUNCATE … RESTART IDENTITY CASCADE`` statement
-    across every table in *base*'s metadata, which is significantly faster
-    than dropping and re-creating tables between tests.
-
-    This is a no-op when the metadata contains no tables.
-
-    Args:
-        session: An active async database session.
-        base: SQLAlchemy DeclarativeBase class containing model metadata.
-
-    Example:
-        ```python
-        @pytest.fixture
-        async def db_session(worker_db_url):
-            async with create_db_session(worker_db_url, Base) as session:
-                yield session
-                await cleanup_tables(session, Base)
-        ```
-    """
-    tables = base.metadata.sorted_tables
-    if not tables:
-        return
-
-    table_names = ", ".join(f'"{t.name}"' for t in tables)
-    await session.execute(text(f"TRUNCATE {table_names} RESTART IDENTITY CASCADE"))
-    await session.commit()

src/fastapi_toolsets/schemas.py

@@ -1,24 +1,26 @@
 """Base Pydantic schemas for API responses."""
 
 from enum import Enum
-from typing import Any, ClassVar, Generic, TypeVar
+from typing import Annotated, Any, ClassVar, Generic, Literal, TypeVar, Union
 
-from pydantic import BaseModel, ConfigDict
+from pydantic import BaseModel, ConfigDict, Field
+
+from .types import DataT
 
 __all__ = [
     "ApiError",
     "CursorPagination",
+    "CursorPaginatedResponse",
     "ErrorResponse",
     "OffsetPagination",
-    "Pagination",
+    "OffsetPaginatedResponse",
     "PaginatedResponse",
+    "PaginationType",
     "PydanticBase",
     "Response",
     "ResponseStatus",
 ]
 
-DataT = TypeVar("DataT")
-
 
 class PydanticBase(BaseModel):
     """Base class for all Pydantic models with common configuration."""
@@ -108,10 +110,6 @@ class OffsetPagination(PydanticBase):
     has_more: bool
 
 
-# Backward-compatible - will be removed in v2.0
-Pagination = OffsetPagination
-
-
 class CursorPagination(PydanticBase):
     """Pagination metadata for cursor-based list responses.
 
@@ -128,9 +126,66 @@ class CursorPagination(PydanticBase):
     has_more: bool
 
 
+class PaginationType(str, Enum):
+    """Pagination strategy selector for :meth:`.AsyncCrud.paginate`."""
+
+    OFFSET = "offset"
+    CURSOR = "cursor"
+
+
 class PaginatedResponse(BaseResponse, Generic[DataT]):
-    """Paginated API response for list endpoints."""
+    """Paginated API response for list endpoints.
+
+    Base class and return type for endpoints that support both pagination
+    strategies.  Use :class:`OffsetPaginatedResponse` or
+    :class:`CursorPaginatedResponse` when the strategy is fixed.
+
+    When used as ``PaginatedResponse[T]`` in a return annotation, subscripting
+    returns ``Annotated[Union[CursorPaginatedResponse[T], OffsetPaginatedResponse[T]], Field(discriminator="pagination_type")]``
+    so FastAPI emits a proper ``oneOf`` + discriminator in the OpenAPI schema.
+    """
 
     data: list[DataT]
     pagination: OffsetPagination | CursorPagination
+    pagination_type: PaginationType | None = None
     filter_attributes: dict[str, list[Any]] | None = None
+
+    _discriminated_union_cache: ClassVar[dict[Any, Any]] = {}
+
+    def __class_getitem__(  # type: ignore[invalid-method-override]
+        cls, item: type[Any] | tuple[type[Any], ...]
+    ) -> type[Any]:
+        if cls is PaginatedResponse and not isinstance(item, TypeVar):
+            cached = cls._discriminated_union_cache.get(item)
+            if cached is None:
+                cached = Annotated[
+                    Union[CursorPaginatedResponse[item], OffsetPaginatedResponse[item]],  # type: ignore[invalid-type-form]
+                    Field(discriminator="pagination_type"),
+                ]
+                cls._discriminated_union_cache[item] = cached
+            return cached  # type: ignore[invalid-return-type]
+        return super().__class_getitem__(item)
+
+
+class OffsetPaginatedResponse(PaginatedResponse[DataT]):
+    """Paginated response with typed offset-based pagination metadata.
+
+    The ``pagination_type`` field is always ``"offset"`` and acts as a
+    discriminator, allowing frontend clients to narrow the union type returned
+    by a unified ``paginate()`` endpoint.
+    """
+
+    pagination: OffsetPagination
+    pagination_type: Literal[PaginationType.OFFSET] = PaginationType.OFFSET
+
+
+class CursorPaginatedResponse(PaginatedResponse[DataT]):
+    """Paginated response with typed cursor-based pagination metadata.
+
+    The ``pagination_type`` field is always ``"cursor"`` and acts as a
+    discriminator, allowing frontend clients to narrow the union type returned
+    by a unified ``paginate()`` endpoint.
+    """
+
+    pagination: CursorPagination
+    pagination_type: Literal[PaginationType.CURSOR] = PaginationType.CURSOR

src/fastapi_toolsets/types.py

@@ -0,0 +1,27 @@
+"""Shared type aliases for the fastapi-toolsets package."""
+
+from collections.abc import AsyncGenerator, Callable, Mapping
+from typing import Any, TypeVar
+
+from pydantic import BaseModel
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.orm import DeclarativeBase, QueryableAttribute
+from sqlalchemy.orm.attributes import InstrumentedAttribute
+from sqlalchemy.sql.elements import ColumnElement
+
+# Generic TypeVars
+DataT = TypeVar("DataT")
+ModelType = TypeVar("ModelType", bound=DeclarativeBase)
+SchemaType = TypeVar("SchemaType", bound=BaseModel)
+
+# CRUD type aliases
+JoinType = list[tuple[type[DeclarativeBase], Any]]
+M2MFieldType = Mapping[str, QueryableAttribute[Any]]
+OrderByClause = ColumnElement[Any] | QueryableAttribute[Any]
+
+# Search / facet type aliases
+SearchFieldType = InstrumentedAttribute[Any] | tuple[InstrumentedAttribute[Any], ...]
+FacetFieldType = SearchFieldType
+
+# Dependency type aliases
+SessionDependency = Callable[[], AsyncGenerator[AsyncSession, None]] | Any

tests/conftest.py

@@ -92,6 +92,15 @@ class IntRole(Base):
     name: Mapped[str] = mapped_column(String(50), unique=True)
 
 
+class Permission(Base):
+    """Test model with composite primary key."""
+
+    __tablename__ = "permissions"
+
+    subject: Mapped[str] = mapped_column(String(50), primary_key=True)
+    action: Mapped[str] = mapped_column(String(50), primary_key=True)
+
+
 class Event(Base):
     """Test model with DateTime and Date cursor columns."""
 
@@ -162,6 +171,7 @@ class UserRead(PydanticBase):
 
     id: uuid.UUID
     username: str
+    is_active: bool = True
 
 
 class UserUpdate(BaseModel):
@@ -218,12 +228,26 @@ class PostM2MUpdate(BaseModel):
     tag_ids: list[uuid.UUID] | None = None
 
 
+class IntRoleRead(PydanticBase):
+    """Schema for reading an IntRole."""
+
+    id: int
+    name: str
+
+
 class IntRoleCreate(BaseModel):
     """Schema for creating an IntRole."""
 
     name: str
 
 
+class EventRead(PydanticBase):
+    """Schema for reading an Event."""
+
+    id: uuid.UUID
+    name: str
+
+
 class EventCreate(BaseModel):
     """Schema for creating an Event."""
 
@@ -232,6 +256,13 @@ class EventCreate(BaseModel):
     scheduled_date: datetime.date
 
 
+class ProductRead(PydanticBase):
+    """Schema for reading a Product."""
+
+    id: uuid.UUID
+    name: str
+
+
 class ProductCreate(BaseModel):
     """Schema for creating a Product."""
 

tests/test_crud_search.py

@@ -23,6 +23,7 @@ from .conftest import (
     User,
     UserCreate,
     UserCrud,
+    UserRead,
 )
 
 
@@ -42,10 +43,11 @@ class TestPaginateSearch:
             db_session, UserCreate(username="bob_smith", email="bob@test.com")
         )
 
-        result = await UserCrud.paginate(
+        result = await UserCrud.offset_paginate(
             db_session,
             search="doe",
             search_fields=[User.username],
+            schema=UserRead,
         )
 
         assert isinstance(result.pagination, OffsetPagination)
@@ -61,10 +63,11 @@ class TestPaginateSearch:
             db_session, UserCreate(username="company_bob", email="bob@other.com")
         )
 
-        result = await UserCrud.paginate(
+        result = await UserCrud.offset_paginate(
             db_session,
             search="company",
             search_fields=[User.username, User.email],
+            schema=UserRead,
         )
 
         assert isinstance(result.pagination, OffsetPagination)
@@ -89,10 +92,11 @@ class TestPaginateSearch:
             UserCreate(username="user1", email="u1@test.com", role_id=user_role.id),
         )
 
-        result = await UserCrud.paginate(
+        result = await UserCrud.offset_paginate(
             db_session,
             search="admin",
             search_fields=[(User.role, Role.name)],
+            schema=UserRead,
         )
 
         assert isinstance(result.pagination, OffsetPagination)
@@ -108,10 +112,11 @@ class TestPaginateSearch:
         )
 
         # Search "admin" in username OR role.name
-        result = await UserCrud.paginate(
+        result = await UserCrud.offset_paginate(
             db_session,
             search="admin",
             search_fields=[User.username, (User.role, Role.name)],
+            schema=UserRead,
         )
 
         assert isinstance(result.pagination, OffsetPagination)
@@ -124,10 +129,11 @@ class TestPaginateSearch:
             db_session, UserCreate(username="JohnDoe", email="j@test.com")
         )
 
-        result = await UserCrud.paginate(
+        result = await UserCrud.offset_paginate(
             db_session,
             search="johndoe",
             search_fields=[User.username],
+            schema=UserRead,
         )
 
         assert isinstance(result.pagination, OffsetPagination)
@@ -141,19 +147,21 @@ class TestPaginateSearch:
         )
 
         # Should not find (case mismatch)
-        result = await UserCrud.paginate(
+        result = await UserCrud.offset_paginate(
             db_session,
             search=SearchConfig(query="johndoe", case_sensitive=True),
             search_fields=[User.username],
+            schema=UserRead,
         )
         assert isinstance(result.pagination, OffsetPagination)
         assert result.pagination.total_count == 0
 
         # Should find (case match)
-        result = await UserCrud.paginate(
+        result = await UserCrud.offset_paginate(
             db_session,
             search=SearchConfig(query="JohnDoe", case_sensitive=True),
             search_fields=[User.username],
+            schema=UserRead,
         )
         assert isinstance(result.pagination, OffsetPagination)
         assert result.pagination.total_count == 1
@@ -168,11 +176,13 @@ class TestPaginateSearch:
             db_session, UserCreate(username="user2", email="u2@test.com")
         )
 
-        result = await UserCrud.paginate(db_session, search="")
+        result = await UserCrud.offset_paginate(db_session, search="", schema=UserRead)
         assert isinstance(result.pagination, OffsetPagination)
         assert result.pagination.total_count == 2
 
-        result = await UserCrud.paginate(db_session, search=None)
+        result = await UserCrud.offset_paginate(
+            db_session, search=None, schema=UserRead
+        )
         assert isinstance(result.pagination, OffsetPagination)
         assert result.pagination.total_count == 2
 
@@ -188,11 +198,12 @@ class TestPaginateSearch:
             UserCreate(username="inactive_john", email="ij@test.com", is_active=False),
         )
 
-        result = await UserCrud.paginate(
+        result = await UserCrud.offset_paginate(
             db_session,
             filters=[User.is_active == True],  # noqa: E712
             search="john",
             search_fields=[User.username],
+            schema=UserRead,
         )
 
         assert isinstance(result.pagination, OffsetPagination)
@@ -200,13 +211,18 @@ class TestPaginateSearch:
         assert result.data[0].username == "active_john"
 
     @pytest.mark.anyio
-    async def test_search_auto_detect_fields(self, db_session: AsyncSession):
+    async def test_search_explicit_fields(self, db_session: AsyncSession):
-        """Auto-detect searchable fields when not specified."""
+        """Search works when search_fields are passed per call."""
         await UserCrud.create(
             db_session, UserCreate(username="findme", email="other@test.com")
         )
 
-        result = await UserCrud.paginate(db_session, search="findme")
+        result = await UserCrud.offset_paginate(
+            db_session,
+            search="findme",
+            search_fields=[User.username],
+            schema=UserRead,
+        )
 
         assert isinstance(result.pagination, OffsetPagination)
         assert result.pagination.total_count == 1
@@ -218,10 +234,11 @@ class TestPaginateSearch:
             db_session, UserCreate(username="john", email="j@test.com")
         )
 
-        result = await UserCrud.paginate(
+        result = await UserCrud.offset_paginate(
             db_session,
             search="nonexistent",
             search_fields=[User.username],
+            schema=UserRead,
         )
 
         assert isinstance(result.pagination, OffsetPagination)
@@ -237,12 +254,13 @@ class TestPaginateSearch:
                 UserCreate(username=f"user_{i}", email=f"user{i}@test.com"),
             )
 
-        result = await UserCrud.paginate(
+        result = await UserCrud.offset_paginate(
             db_session,
             search="user_",
             search_fields=[User.username],
             page=1,
             items_per_page=5,
+            schema=UserRead,
         )
 
         assert isinstance(result.pagination, OffsetPagination)
@@ -264,10 +282,11 @@ class TestPaginateSearch:
         )
 
         # Search in username, not in role
-        result = await UserCrud.paginate(
+        result = await UserCrud.offset_paginate(
             db_session,
             search="role",
             search_fields=[User.username],
+            schema=UserRead,
         )
 
         assert isinstance(result.pagination, OffsetPagination)
@@ -286,11 +305,12 @@ class TestPaginateSearch:
             db_session, UserCreate(username="bob", email="b@test.com")
         )
 
-        result = await UserCrud.paginate(
+        result = await UserCrud.offset_paginate(
             db_session,
             search="@test.com",
             search_fields=[User.email],
             order_by=User.username,
+            schema=UserRead,
         )
 
         assert isinstance(result.pagination, OffsetPagination)
@@ -310,10 +330,11 @@ class TestPaginateSearch:
         )
 
         # Search by UUID (partial match)
-        result = await UserCrud.paginate(
+        result = await UserCrud.offset_paginate(
             db_session,
             search="12345678",
             search_fields=[User.id, User.username],
+            schema=UserRead,
         )
 
         assert isinstance(result.pagination, OffsetPagination)
@@ -363,10 +384,11 @@ class TestSearchConfig:
         )
 
         # 'john' must be in username AND email
-        result = await UserCrud.paginate(
+        result = await UserCrud.offset_paginate(
             db_session,
             search=SearchConfig(query="john", match_mode="all"),
             search_fields=[User.username, User.email],
+            schema=UserRead,
         )
 
         assert isinstance(result.pagination, OffsetPagination)
@@ -380,9 +402,10 @@ class TestSearchConfig:
             db_session, UserCreate(username="test", email="findme@test.com")
         )
 
-        result = await UserCrud.paginate(
+        result = await UserCrud.offset_paginate(
             db_session,
             search=SearchConfig(query="findme", fields=[User.email]),
+            schema=UserRead,
         )
 
         assert isinstance(result.pagination, OffsetPagination)
@@ -410,7 +433,7 @@ class TestNoSearchableFieldsError:
         from fastapi_toolsets.exceptions import NoSearchableFieldsError
 
         error = NoSearchableFieldsError(User)
-        assert "User" in str(error)
+        assert "User" in error.api_error.desc
         assert error.model is User
 
     def test_error_raised_when_no_fields(self):
@@ -434,7 +457,7 @@ class TestNoSearchableFieldsError:
             build_search_filters(NoStringModel, "test")
 
         assert exc_info.value.model is NoStringModel
-        assert "NoStringModel" in str(exc_info.value)
+        assert "NoStringModel" in exc_info.value.api_error.desc
 
 
 class TestGetSearchableFields:
@@ -478,7 +501,7 @@ class TestFacetsNotSet:
             db_session, UserCreate(username="alice", email="a@test.com")
         )
 
-        result = await UserCrud.offset_paginate(db_session)
+        result = await UserCrud.offset_paginate(db_session, schema=UserRead)
 
         assert result.filter_attributes is None
 
@@ -490,7 +513,7 @@ class TestFacetsNotSet:
             db_session, UserCreate(username="alice", email="a@test.com")
         )
 
-        result = await UserCursorCrud.cursor_paginate(db_session)
+        result = await UserCursorCrud.cursor_paginate(db_session, schema=UserRead)
 
         assert result.filter_attributes is None
 
@@ -509,7 +532,7 @@ class TestFacetsDirectColumn:
             db_session, UserCreate(username="bob", email="b@test.com")
         )
 
-        result = await UserFacetCrud.offset_paginate(db_session)
+        result = await UserFacetCrud.offset_paginate(db_session, schema=UserRead)
 
         assert result.filter_attributes is not None
         # Distinct usernames, sorted
@@ -528,7 +551,7 @@ class TestFacetsDirectColumn:
             db_session, UserCreate(username="bob", email="b@test.com")
         )
 
-        result = await UserFacetCursorCrud.cursor_paginate(db_session)
+        result = await UserFacetCursorCrud.cursor_paginate(db_session, schema=UserRead)
 
         assert result.filter_attributes is not None
         assert set(result.filter_attributes["email"]) == {"a@test.com", "b@test.com"}
@@ -544,7 +567,7 @@ class TestFacetsDirectColumn:
             db_session, UserCreate(username="bob", email="b@test.com")
         )
 
-        result = await UserFacetCrud.offset_paginate(db_session)
+        result = await UserFacetCrud.offset_paginate(db_session, schema=UserRead)
 
         assert result.filter_attributes is not None
         assert "username" in result.filter_attributes
@@ -561,7 +584,7 @@ class TestFacetsDirectColumn:
 
         # Override: ask for email instead of username
         result = await UserFacetCrud.offset_paginate(
-            db_session, facet_fields=[User.email]
+            db_session, facet_fields=[User.email], schema=UserRead
         )
 
         assert result.filter_attributes is not None
@@ -587,6 +610,7 @@ class TestFacetsRespectFilters:
         result = await UserFacetCrud.offset_paginate(
             db_session,
             filters=[User.is_active == True],  # noqa: E712
+            schema=UserRead,
         )
 
         assert result.filter_attributes is not None
@@ -617,7 +641,7 @@ class TestFacetsRelationship:
             db_session, UserCreate(username="charlie", email="c@test.com")
         )
 
-        result = await UserRelFacetCrud.offset_paginate(db_session)
+        result = await UserRelFacetCrud.offset_paginate(db_session, schema=UserRead)
 
         assert result.filter_attributes is not None
         assert set(result.filter_attributes["name"]) == {"admin", "editor"}
@@ -632,7 +656,7 @@ class TestFacetsRelationship:
             db_session, UserCreate(username="norole", email="n@test.com")
         )
 
-        result = await UserRelFacetCrud.offset_paginate(db_session)
+        result = await UserRelFacetCrud.offset_paginate(db_session, schema=UserRead)
 
         assert result.filter_attributes is not None
         assert result.filter_attributes["name"] == []
@@ -656,7 +680,10 @@ class TestFacetsRelationship:
         )
 
         result = await UserSearchFacetCrud.offset_paginate(
-            db_session, search="admin", search_fields=[(User.role, Role.name)]
+            db_session,
+            search="admin",
+            search_fields=[(User.role, Role.name)],
+            schema=UserRead,
         )
 
         assert result.filter_attributes is not None
@@ -678,7 +705,7 @@ class TestFilterBy:
         )
 
         result = await UserFacetCrud.offset_paginate(
-            db_session, filter_by={"username": "alice"}
+            db_session, filter_by={"username": "alice"}, schema=UserRead
         )
 
         assert len(result.data) == 1
@@ -701,7 +728,7 @@ class TestFilterBy:
         )
 
         result = await UserFacetCrud.offset_paginate(
-            db_session, filter_by={"username": ["alice", "bob"]}
+            db_session, filter_by={"username": ["alice", "bob"]}, schema=UserRead
         )
 
         assert isinstance(result.pagination, OffsetPagination)
@@ -726,7 +753,7 @@ class TestFilterBy:
         )
 
         result = await UserRelFacetCrud.offset_paginate(
-            db_session, filter_by={"name": "admin"}
+            db_session, filter_by={"name": "admin"}, schema=UserRead
         )
 
         assert isinstance(result.pagination, OffsetPagination)
@@ -749,6 +776,7 @@ class TestFilterBy:
             db_session,
             filters=[User.is_active == True],  # noqa: E712
             filter_by={"username": ["alice", "alice2"]},
+            schema=UserRead,
         )
 
         # Only alice passes both: is_active=True AND username IN [alice, alice2]
@@ -763,7 +791,7 @@ class TestFilterBy:
 
         with pytest.raises(InvalidFacetFilterError) as exc_info:
             await UserFacetCrud.offset_paginate(
-                db_session, filter_by={"nonexistent": "value"}
+                db_session, filter_by={"nonexistent": "value"}, schema=UserRead
             )
 
         assert exc_info.value.key == "nonexistent"
@@ -795,6 +823,7 @@ class TestFilterBy:
         result = await UserRoleFacetCrud.offset_paginate(
             db_session,
             filter_by={"name": "admin", "id": str(admin.id)},
+            schema=UserRead,
         )
 
         assert isinstance(result.pagination, OffsetPagination)
@@ -815,7 +844,7 @@ class TestFilterBy:
         )
 
         result = await UserFacetCursorCrud.cursor_paginate(
-            db_session, filter_by={"username": "alice"}
+            db_session, filter_by={"username": "alice"}, schema=UserRead
         )
 
         assert len(result.data) == 1
@@ -839,7 +868,7 @@ class TestFilterBy:
         )
 
         result = await UserFacetCrud.offset_paginate(
-            db_session, filter_by=UserFilter(username="alice")
+            db_session, filter_by=UserFilter(username="alice"), schema=UserRead
         )
 
         assert isinstance(result.pagination, OffsetPagination)
@@ -865,7 +894,7 @@ class TestFilterBy:
         )
 
         result = await UserFacetCursorCrud.cursor_paginate(
-            db_session, filter_by=UserFilter(username="alice")
+            db_session, filter_by=UserFilter(username="alice"), schema=UserRead
         )
 
         assert len(result.data) == 1
@@ -974,7 +1003,9 @@ class TestFilterParamsSchema:
 
         dep = UserFacetCrud.filter_params()
         f = await dep(username=["alice"])
-        result = await UserFacetCrud.offset_paginate(db_session, filter_by=f)
+        result = await UserFacetCrud.offset_paginate(
+            db_session, filter_by=f, schema=UserRead
+        )
 
         assert isinstance(result.pagination, OffsetPagination)
         assert result.pagination.total_count == 1
@@ -995,7 +1026,9 @@ class TestFilterParamsSchema:
 
         dep = UserFacetCursorCrud.filter_params()
         f = await dep(username=["alice"])
-        result = await UserFacetCursorCrud.cursor_paginate(db_session, filter_by=f)
+        result = await UserFacetCursorCrud.cursor_paginate(
+            db_session, filter_by=f, schema=UserRead
+        )
 
         assert len(result.data) == 1
         assert result.data[0].username == "alice"
@@ -1013,7 +1046,9 @@ class TestFilterParamsSchema:
 
         dep = UserFacetCrud.filter_params()
         f = await dep()  # all fields None
-        result = await UserFacetCrud.offset_paginate(db_session, filter_by=f)
+        result = await UserFacetCrud.offset_paginate(
+            db_session, filter_by=f, schema=UserRead
+        )
 
         assert isinstance(result.pagination, OffsetPagination)
         assert result.pagination.total_count == 2

tests/test_db.py

@@ -4,18 +4,25 @@ import asyncio
 import uuid
 
 import pytest
+from sqlalchemy import text
+from sqlalchemy.engine import make_url
 from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
+from sqlalchemy.orm import DeclarativeBase
 
 from fastapi_toolsets.db import (
     LockMode,
+    cleanup_tables,
+    create_database,
     create_db_context,
     create_db_dependency,
     get_transaction,
     lock_tables,
     wait_for_row_change,
 )
+from fastapi_toolsets.exceptions import NotFoundError
+from fastapi_toolsets.pytest import create_db_session
 
-from .conftest import DATABASE_URL, Base, Role, RoleCrud, User
+from .conftest import DATABASE_URL, Base, Role, RoleCrud, User, UserCrud
 
 
 class TestCreateDbDependency:
@@ -307,9 +314,9 @@ class TestWaitForRowChange:
 
     @pytest.mark.anyio
     async def test_nonexistent_row_raises(self, db_session: AsyncSession):
-        """Raises LookupError when the row does not exist."""
+        """Raises NotFoundError when the row does not exist."""
         fake_id = uuid.uuid4()
-        with pytest.raises(LookupError, match="not found"):
+        with pytest.raises(NotFoundError, match="not found"):
             await wait_for_row_change(db_session, Role, fake_id, interval=0.05)
 
     @pytest.mark.anyio
@@ -326,7 +333,7 @@ class TestWaitForRowChange:
 
     @pytest.mark.anyio
     async def test_deleted_row_raises(self, db_session: AsyncSession, engine):
-        """Raises LookupError when the row is deleted during polling."""
+        """Raises NotFoundError when the row is deleted during polling."""
         role = Role(name="delete_role")
         db_session.add(role)
         await db_session.commit()
@@ -340,6 +347,86 @@ class TestWaitForRowChange:
                 await other.commit()
 
         delete_task = asyncio.create_task(delete_later())
-        with pytest.raises(LookupError):
+        with pytest.raises(NotFoundError):
             await wait_for_row_change(db_session, Role, role.id, interval=0.05)
         await delete_task
+
+
+class TestCreateDatabase:
+    """Tests for create_database."""
+
+    @pytest.mark.anyio
+    async def test_creates_database(self):
+        """Database is created by create_database."""
+        target_url = (
+            make_url(DATABASE_URL)
+            .set(database="test_create_db_general")
+            .render_as_string(hide_password=False)
+        )
+        expected_db: str = make_url(target_url).database  # type: ignore[assignment]
+
+        engine = create_async_engine(DATABASE_URL, isolation_level="AUTOCOMMIT")
+        try:
+            async with engine.connect() as conn:
+                await conn.execute(text(f"DROP DATABASE IF EXISTS {expected_db}"))
+
+            await create_database(db_name=expected_db, server_url=DATABASE_URL)
+
+            async with engine.connect() as conn:
+                result = await conn.execute(
+                    text("SELECT 1 FROM pg_database WHERE datname = :name"),
+                    {"name": expected_db},
+                )
+                assert result.scalar() == 1
+
+            # Cleanup
+            async with engine.connect() as conn:
+                await conn.execute(text(f"DROP DATABASE IF EXISTS {expected_db}"))
+        finally:
+            await engine.dispose()
+
+
+class TestCleanupTables:
+    """Tests for cleanup_tables helper."""
+
+    @pytest.mark.anyio
+    async def test_truncates_all_tables(self):
+        """All table rows are removed after cleanup_tables."""
+        async with create_db_session(DATABASE_URL, Base, drop_tables=True) as session:
+            role = Role(id=uuid.uuid4(), name="cleanup_role")
+            session.add(role)
+            await session.flush()
+
+            user = User(
+                id=uuid.uuid4(),
+                username="cleanup_user",
+                email="cleanup@test.com",
+                role_id=role.id,
+            )
+            session.add(user)
+            await session.commit()
+
+            # Verify rows exist
+            roles_count = await RoleCrud.count(session)
+            users_count = await UserCrud.count(session)
+            assert roles_count == 1
+            assert users_count == 1
+
+            await cleanup_tables(session, Base)
+
+            # Verify tables are empty
+            roles_count = await RoleCrud.count(session)
+            users_count = await UserCrud.count(session)
+            assert roles_count == 0
+            assert users_count == 0
+
+    @pytest.mark.anyio
+    async def test_noop_for_empty_metadata(self):
+        """cleanup_tables does not raise when metadata has no tables."""
+
+        class EmptyBase(DeclarativeBase):
+            pass
+
+        async with create_db_session(DATABASE_URL, Base, drop_tables=True) as session:
+            # Should not raise
+            await cleanup_tables(session, EmptyBase)

tests/test_dependencies.py

@@ -3,13 +3,17 @@
 import inspect
 import uuid
 from collections.abc import AsyncGenerator
-from typing import Any, cast
+from typing import Annotated, Any, cast
 
 import pytest
 from fastapi.params import Depends
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from fastapi_toolsets.dependencies import BodyDependency, PathDependency
+from fastapi_toolsets.dependencies import (
+    BodyDependency,
+    PathDependency,
+    _unwrap_session_dep,
+)
 
 from .conftest import Role, RoleCreate, RoleCrud, User
 
@@ -19,6 +23,24 @@ async def mock_get_db() -> AsyncGenerator[AsyncSession, None]:
     yield None
 
 
+MockSessionDep = Annotated[AsyncSession, Depends(mock_get_db)]
+
+
+class TestUnwrapSessionDep:
+    def test_plain_callable_returned_as_is(self):
+        """Plain callable is returned unchanged."""
+        assert _unwrap_session_dep(mock_get_db) is mock_get_db
+
+    def test_annotated_with_depends_unwrapped(self):
+        """Annotated form with Depends is unwrapped to the plain callable."""
+        assert _unwrap_session_dep(MockSessionDep) is mock_get_db
+
+    def test_annotated_without_depends_returned_as_is(self):
+        """Annotated form with no Depends falls back to returning session_dep as-is."""
+        annotated_no_dep = Annotated[AsyncSession, "not_a_depends"]
+        assert _unwrap_session_dep(annotated_no_dep) is annotated_no_dep
+
+
 class TestPathDependency:
     """Tests for PathDependency factory."""
 
@@ -95,6 +117,39 @@ class TestPathDependency:
         assert result.id == role.id
         assert result.name == "test_role"
 
+    def test_annotated_session_dep_returns_depends_instance(self):
+        """PathDependency accepts Annotated[AsyncSession, Depends(...)] form."""
+        dep = PathDependency(Role, Role.id, session_dep=MockSessionDep)
+        assert isinstance(dep, Depends)
+
+    def test_annotated_session_dep_signature(self):
+        """PathDependency with Annotated session_dep produces a valid signature."""
+        dep = cast(Any, PathDependency(Role, Role.id, session_dep=MockSessionDep))
+        sig = inspect.signature(dep.dependency)
+
+        assert "role_id" in sig.parameters
+        assert "session" in sig.parameters
+        assert isinstance(sig.parameters["session"].default, Depends)
+
+    def test_annotated_session_dep_unwraps_callable(self):
+        """PathDependency with Annotated form uses the underlying callable, not the Annotated type."""
+        dep = cast(Any, PathDependency(Role, Role.id, session_dep=MockSessionDep))
+        sig = inspect.signature(dep.dependency)
+
+        inner_dep = sig.parameters["session"].default
+        assert inner_dep.dependency is mock_get_db
+
+    @pytest.mark.anyio
+    async def test_annotated_session_dep_fetches_object(self, db_session):
+        """PathDependency with Annotated session_dep correctly fetches object from database."""
+        role = await RoleCrud.create(db_session, RoleCreate(name="annotated_role"))
+
+        dep = cast(Any, PathDependency(Role, Role.id, session_dep=MockSessionDep))
+        result = await dep.dependency(session=db_session, role_id=role.id)
+
+        assert result.id == role.id
+        assert result.name == "annotated_role"
+
 
 class TestBodyDependency:
     """Tests for BodyDependency factory."""
@@ -184,3 +239,39 @@ class TestBodyDependency:
 
         assert result.id == role.id
         assert result.name == "body_test_role"
+
+    def test_annotated_session_dep_returns_depends_instance(self):
+        """BodyDependency accepts Annotated[AsyncSession, Depends(...)] form."""
+        dep = BodyDependency(
+            Role, Role.id, session_dep=MockSessionDep, body_field="role_id"
+        )
+        assert isinstance(dep, Depends)
+
+    def test_annotated_session_dep_unwraps_callable(self):
+        """BodyDependency with Annotated form uses the underlying callable, not the Annotated type."""
+        dep = cast(
+            Any,
+            BodyDependency(
+                Role, Role.id, session_dep=MockSessionDep, body_field="role_id"
+            ),
+        )
+        sig = inspect.signature(dep.dependency)
+
+        inner_dep = sig.parameters["session"].default
+        assert inner_dep.dependency is mock_get_db
+
+    @pytest.mark.anyio
+    async def test_annotated_session_dep_fetches_object(self, db_session):
+        """BodyDependency with Annotated session_dep correctly fetches object from database."""
+        role = await RoleCrud.create(db_session, RoleCreate(name="body_annotated_role"))
+
+        dep = cast(
+            Any,
+            BodyDependency(
+                Role, Role.id, session_dep=MockSessionDep, body_field="role_id"
+            ),
+        )
+        result = await dep.dependency(session=db_session, role_id=role.id)
+
+        assert result.id == role.id
+        assert result.name == "body_annotated_role"

tests/test_example_pagination_search.py

@@ -393,3 +393,105 @@ class TestCursorSorting:
         body = resp.json()
         assert body["error_code"] == "SORT-422"
         assert body["status"] == "FAIL"
+
+
+class TestPaginateUnified:
+    """Tests for the unified GET /articles/ endpoint using paginate()."""
+
+    @pytest.mark.anyio
+    async def test_defaults_to_offset_pagination(
+        self, client: AsyncClient, ex_db_session
+    ):
+        """Without pagination_type, defaults to offset pagination."""
+        await seed(ex_db_session)
+
+        resp = await client.get("/articles/")
+
+        assert resp.status_code == 200
+        body = resp.json()
+        assert body["pagination_type"] == "offset"
+        assert "total_count" in body["pagination"]
+        assert body["pagination"]["total_count"] == 3
+
+    @pytest.mark.anyio
+    async def test_explicit_offset_pagination(self, client: AsyncClient, ex_db_session):
+        """pagination_type=offset returns OffsetPagination metadata."""
+        await seed(ex_db_session)
+
+        resp = await client.get(
+            "/articles/?pagination_type=offset&page=1&items_per_page=2"
+        )
+
+        assert resp.status_code == 200
+        body = resp.json()
+        assert body["pagination_type"] == "offset"
+        assert body["pagination"]["total_count"] == 3
+        assert body["pagination"]["page"] == 1
+        assert body["pagination"]["has_more"] is True
+        assert len(body["data"]) == 2
+
+    @pytest.mark.anyio
+    async def test_cursor_pagination_type(self, client: AsyncClient, ex_db_session):
+        """pagination_type=cursor returns CursorPagination metadata."""
+        await seed(ex_db_session)
+
+        resp = await client.get("/articles/?pagination_type=cursor&items_per_page=2")
+
+        assert resp.status_code == 200
+        body = resp.json()
+        assert body["pagination_type"] == "cursor"
+        assert "next_cursor" in body["pagination"]
+        assert "total_count" not in body["pagination"]
+        assert body["pagination"]["has_more"] is True
+        assert len(body["data"]) == 2
+
+    @pytest.mark.anyio
+    async def test_cursor_pagination_navigate_pages(
+        self, client: AsyncClient, ex_db_session
+    ):
+        """Cursor from first page can be used to fetch the next page."""
+        await seed(ex_db_session)
+
+        first = await client.get("/articles/?pagination_type=cursor&items_per_page=2")
+        assert first.status_code == 200
+        first_body = first.json()
+        next_cursor = first_body["pagination"]["next_cursor"]
+        assert next_cursor is not None
+
+        second = await client.get(
+            f"/articles/?pagination_type=cursor&items_per_page=2&cursor={next_cursor}"
+        )
+        assert second.status_code == 200
+        second_body = second.json()
+        assert second_body["pagination_type"] == "cursor"
+        assert second_body["pagination"]["has_more"] is False
+        assert len(second_body["data"]) == 1
+
+    @pytest.mark.anyio
+    async def test_cursor_pagination_with_search(
+        self, client: AsyncClient, ex_db_session
+    ):
+        """paginate() with cursor type respects search parameter."""
+        await seed(ex_db_session)
+
+        resp = await client.get("/articles/?pagination_type=cursor&search=fastapi")
+
+        assert resp.status_code == 200
+        body = resp.json()
+        assert body["pagination_type"] == "cursor"
+        assert len(body["data"]) == 1
+        assert body["data"][0]["title"] == "FastAPI tips"
+
+    @pytest.mark.anyio
+    async def test_offset_pagination_with_filter(
+        self, client: AsyncClient, ex_db_session
+    ):
+        """paginate() with offset type respects filter_by parameter."""
+        await seed(ex_db_session)
+
+        resp = await client.get("/articles/?pagination_type=offset&status=published")
+
+        assert resp.status_code == 200
+        body = resp.json()
+        assert body["pagination_type"] == "offset"
+        assert body["pagination"]["total_count"] == 2

tests/test_exceptions.py

@@ -2,6 +2,7 @@
 
 import pytest
 from fastapi import FastAPI
+from fastapi.exceptions import HTTPException
 from fastapi.testclient import TestClient
 
 from fastapi_toolsets.exceptions import (
@@ -36,8 +37,8 @@ class TestApiException:
         assert error.api_error.msg == "I'm a teapot"
         assert str(error) == "I'm a teapot"
 
-    def test_custom_detail_message(self):
+    def test_detail_overrides_msg_and_str(self):
-        """Custom detail overrides default message."""
+        """detail sets both str(exc) and api_error.msg; class-level msg is unchanged."""
 
         class CustomError(ApiException):
             api_error = ApiError(
@@ -47,8 +48,172 @@ class TestApiException:
                 err_code="BAD-400",
             )
 
-        error = CustomError("Custom message")
+        error = CustomError("Widget not found")
-        assert str(error) == "Custom message"
+        assert str(error) == "Widget not found"
+        assert error.api_error.msg == "Widget not found"
+        assert CustomError.api_error.msg == "Bad Request"  # class unchanged
+
+    def test_desc_override(self):
+        """desc kwarg overrides api_error.desc on the instance only."""
+
+        class MyError(ApiException):
+            api_error = ApiError(
+                code=400, msg="Error", desc="Default.", err_code="ERR-400"
+            )
+
+        err = MyError(desc="Custom desc.")
+        assert err.api_error.desc == "Custom desc."
+        assert MyError.api_error.desc == "Default."  # class unchanged
+
+    def test_data_override(self):
+        """data kwarg sets api_error.data on the instance only."""
+
+        class MyError(ApiException):
+            api_error = ApiError(
+                code=400, msg="Error", desc="Default.", err_code="ERR-400"
+            )
+
+        err = MyError(data={"key": "value"})
+        assert err.api_error.data == {"key": "value"}
+        assert MyError.api_error.data is None  # class unchanged
+
+    def test_desc_and_data_override(self):
+        """detail, desc and data can all be overridden together."""
+
+        class MyError(ApiException):
+            api_error = ApiError(
+                code=400, msg="Error", desc="Default.", err_code="ERR-400"
+            )
+
+        err = MyError("custom msg", desc="New desc.", data={"x": 1})
+        assert str(err) == "custom msg"
+        assert err.api_error.msg == "custom msg"  # detail also updates msg
+        assert err.api_error.desc == "New desc."
+        assert err.api_error.data == {"x": 1}
+        assert err.api_error.code == 400  # other fields unchanged
+
+    def test_class_api_error_not_mutated_after_instance_override(self):
+        """Raising with desc/data does not mutate the class-level api_error."""
+
+        class MyError(ApiException):
+            api_error = ApiError(
+                code=400, msg="Error", desc="Default.", err_code="ERR-400"
+            )
+
+        MyError(desc="Changed", data={"x": 1})
+        assert MyError.api_error.desc == "Default."
+        assert MyError.api_error.data is None
+
+    def test_subclass_uses_super_with_desc_and_data(self):
+        """Subclasses can delegate detail/desc/data to super().__init__()."""
+
+        class BuildValidationError(ApiException):
+            api_error = ApiError(
+                code=422,
+                msg="Build Validation Error",
+                desc="The build configuration is invalid.",
+                err_code="BUILD-422",
+            )
+
+            def __init__(self, *errors: str) -> None:
+                super().__init__(
+                    f"{len(errors)} validation error(s)",
+                    desc=", ".join(errors),
+                    data={"errors": [{"message": e} for e in errors]},
+                )
+
+        err = BuildValidationError("Field A is required", "Field B is invalid")
+        assert str(err) == "2 validation error(s)"
+        assert err.api_error.msg == "2 validation error(s)"  # detail set msg
+        assert err.api_error.desc == "Field A is required, Field B is invalid"
+        assert err.api_error.data == {
+            "errors": [
+                {"message": "Field A is required"},
+                {"message": "Field B is invalid"},
+            ]
+        }
+        assert err.api_error.code == 422  # other fields unchanged
+
+    def test_detail_desc_data_in_http_response(self):
+        """detail/desc/data overrides all appear correctly in the FastAPI HTTP response."""
+
+        class DynamicError(ApiException):
+            api_error = ApiError(
+                code=400, msg="Error", desc="Default.", err_code="ERR-400"
+            )
+
+            def __init__(self, message: str) -> None:
+                super().__init__(
+                    message,
+                    desc=f"Detail: {message}",
+                    data={"reason": message},
+                )
+
+        app = FastAPI()
+        init_exceptions_handlers(app)
+
+        @app.get("/error")
+        async def raise_error():
+            raise DynamicError("something went wrong")
+
+        client = TestClient(app)
+        response = client.get("/error")
+
+        assert response.status_code == 400
+        body = response.json()
+        assert body["message"] == "something went wrong"
+        assert body["description"] == "Detail: something went wrong"
+        assert body["data"] == {"reason": "something went wrong"}
+
+
+class TestApiExceptionGuard:
+    """Tests for the __init_subclass__ api_error guard."""
+
+    def test_missing_api_error_raises_type_error(self):
+        """Defining a subclass without api_error raises TypeError at class creation time."""
+        with pytest.raises(
+            TypeError, match="must define an 'api_error' class attribute"
+        ):
+
+            class BrokenError(ApiException):
+                pass
+
+    def test_abstract_subclass_skips_guard(self):
+        """abstract=True allows intermediate base classes without api_error."""
+
+        class BaseGroupError(ApiException, abstract=True):
+            pass
+
+        # Concrete child must still define it
+        class ConcreteError(BaseGroupError):
+            api_error = ApiError(
+                code=400, msg="Error", desc="Desc.", err_code="ERR-400"
+            )
+
+        err = ConcreteError()
+        assert err.api_error.code == 400
+
+    def test_abstract_child_still_requires_api_error_on_concrete(self):
+        """Concrete subclass of an abstract class must define api_error."""
+
+        class Base(ApiException, abstract=True):
+            pass
+
+        with pytest.raises(
+            TypeError, match="must define an 'api_error' class attribute"
+        ):
+
+            class Concrete(Base):
+                pass
+
+    def test_inherited_api_error_satisfies_guard(self):
+        """Subclass that inherits api_error from a parent does not need its own."""
+
+        class ConcreteError(NotFoundError):
+            pass
+
+        err = ConcreteError()
+        assert err.api_error.code == 404
 
 
 class TestBuiltInExceptions:
@@ -90,7 +255,7 @@ class TestGenerateErrorResponses:
         assert responses[404]["description"] == "Not Found"
 
     def test_generates_multiple_responses(self):
-        """Generates responses for multiple exceptions."""
+        """Generates responses for multiple exceptions with distinct status codes."""
         responses = generate_error_responses(
             UnauthorizedError,
             ForbiddenError,
@@ -101,15 +266,24 @@ class TestGenerateErrorResponses:
         assert 403 in responses
         assert 404 in responses
 
-    def test_response_has_example(self):
+    def test_response_has_named_example(self):
-        """Generated response includes example."""
+        """Generated response uses named examples keyed by err_code."""
         responses = generate_error_responses(NotFoundError)
-        example = responses[404]["content"]["application/json"]["example"]
+        examples = responses[404]["content"]["application/json"]["examples"]
 
-        assert example["status"] == "FAIL"
+        assert "RES-404" in examples
-        assert example["error_code"] == "RES-404"
+        value = examples["RES-404"]["value"]
-        assert example["message"] == "Not Found"
+        assert value["status"] == "FAIL"
-        assert example["data"] is None
+        assert value["error_code"] == "RES-404"
+        assert value["message"] == "Not Found"
+        assert value["data"] is None
+
+    def test_response_example_has_summary(self):
+        """Each named example carries a summary equal to api_error.msg."""
+        responses = generate_error_responses(NotFoundError)
+        example = responses[404]["content"]["application/json"]["examples"]["RES-404"]
+
+        assert example["summary"] == "Not Found"
 
     def test_response_example_with_data(self):
         """Generated response includes data when set on ApiError."""
@@ -124,9 +298,49 @@ class TestGenerateErrorResponses:
             )
 
         responses = generate_error_responses(ErrorWithData)
-        example = responses[400]["content"]["application/json"]["example"]
+        value = responses[400]["content"]["application/json"]["examples"]["BAD-400"][
+            "value"
+        ]
 
-        assert example["data"] == {"details": "some context"}
+        assert value["data"] == {"details": "some context"}
+
+    def test_two_errors_same_code_both_present(self):
+        """Two exceptions with the same HTTP code produce two named examples."""
+
+        class BadRequestA(ApiException):
+            api_error = ApiError(
+                code=400, msg="Bad A", desc="Reason A.", err_code="ERR-A"
+            )
+
+        class BadRequestB(ApiException):
+            api_error = ApiError(
+                code=400, msg="Bad B", desc="Reason B.", err_code="ERR-B"
+            )
+
+        responses = generate_error_responses(BadRequestA, BadRequestB)
+
+        assert 400 in responses
+        examples = responses[400]["content"]["application/json"]["examples"]
+        assert "ERR-A" in examples
+        assert "ERR-B" in examples
+        assert examples["ERR-A"]["value"]["message"] == "Bad A"
+        assert examples["ERR-B"]["value"]["message"] == "Bad B"
+
+    def test_two_errors_same_code_single_top_level_entry(self):
+        """Two exceptions with the same HTTP code produce exactly one top-level entry."""
+
+        class BadRequestA(ApiException):
+            api_error = ApiError(
+                code=400, msg="Bad A", desc="Reason A.", err_code="ERR-A"
+            )
+
+        class BadRequestB(ApiException):
+            api_error = ApiError(
+                code=400, msg="Bad B", desc="Reason B.", err_code="ERR-B"
+            )
+
+        responses = generate_error_responses(BadRequestA, BadRequestB)
+        assert len([k for k in responses if k == 400]) == 1
 
 
 class TestInitExceptionsHandlers:
@@ -250,13 +464,68 @@ class TestInitExceptionsHandlers:
         assert data["status"] == "FAIL"
         assert data["error_code"] == "SERVER-500"
 
-    def test_custom_openapi_schema(self):
+    def test_handles_http_exception(self):
-        """Customizes OpenAPI schema for 422 responses."""
+        """Handles starlette HTTPException with consistent ErrorResponse envelope."""
         app = FastAPI()
         init_exceptions_handlers(app)
 
+        @app.get("/protected")
+        async def protected():
+            raise HTTPException(status_code=403, detail="Forbidden")
+
+        client = TestClient(app)
+        response = client.get("/protected")
+
+        assert response.status_code == 403
+        data = response.json()
+        assert data["status"] == "FAIL"
+        assert data["error_code"] == "HTTP-403"
+        assert data["message"] == "Forbidden"
+
+    def test_handles_http_exception_404_from_route(self):
+        """HTTPException(404) raised inside a route uses the consistent ErrorResponse envelope."""
+        app = FastAPI()
+        init_exceptions_handlers(app)
+
+        @app.get("/items/{item_id}")
+        async def get_item(item_id: int):
+            raise HTTPException(status_code=404, detail="Item not found")
+
+        client = TestClient(app)
+        response = client.get("/items/99")
+
+        assert response.status_code == 404
+        data = response.json()
+        assert data["status"] == "FAIL"
+        assert data["error_code"] == "HTTP-404"
+        assert data["message"] == "Item not found"
+
+    def test_handles_http_exception_forwards_headers(self):
+        """HTTPException with WWW-Authenticate header forwards it in the response."""
+        app = FastAPI()
+        init_exceptions_handlers(app)
+
+        @app.get("/secure")
+        async def secure():
+            raise HTTPException(
+                status_code=401,
+                detail="Not authenticated",
+                headers={"WWW-Authenticate": "Bearer"},
+            )
+
+        client = TestClient(app)
+        response = client.get("/secure")
+
+        assert response.status_code == 401
+        assert response.headers.get("www-authenticate") == "Bearer"
+
+    def test_custom_openapi_schema(self):
+        """Customises OpenAPI schema for 422 responses using named examples."""
         from pydantic import BaseModel
 
+        app = FastAPI()
+        init_exceptions_handlers(app)
+
         class Item(BaseModel):
             name: str
 
@@ -269,8 +538,128 @@ class TestInitExceptionsHandlers:
         post_op = openapi["paths"]["/items"]["post"]
         assert "422" in post_op["responses"]
         resp_422 = post_op["responses"]["422"]
-        example = resp_422["content"]["application/json"]["example"]
+        examples = resp_422["content"]["application/json"]["examples"]
-        assert example["error_code"] == "VAL-422"
+        assert "VAL-422" in examples
+        assert examples["VAL-422"]["value"]["error_code"] == "VAL-422"
+
+    def test_custom_openapi_preserves_app_metadata(self):
+        """_patched_openapi preserves custom FastAPI app-level metadata."""
+        app = FastAPI(
+            title="My API",
+            version="2.0.0",
+            description="Custom description",
+        )
+        init_exceptions_handlers(app)
+
+        schema = app.openapi()
+        assert schema["info"]["title"] == "My API"
+        assert schema["info"]["version"] == "2.0.0"
+
+    def test_handles_response_validation_error(self):
+        """Handles ResponseValidationError with a structured 422 response."""
+        from pydantic import BaseModel
+
+        class CountResponse(BaseModel):
+            count: int
+
+        app = FastAPI()
+        init_exceptions_handlers(app)
+
+        @app.get("/broken", response_model=CountResponse)
+        async def broken():
+            return {"count": "not-a-number"}  # triggers ResponseValidationError
+
+        client = TestClient(app, raise_server_exceptions=False)
+        response = client.get("/broken")
+
+        assert response.status_code == 422
+        data = response.json()
+        assert data["status"] == "FAIL"
+        assert data["error_code"] == "VAL-422"
+        assert "errors" in data["data"]
+
+    def test_handles_validation_error_with_non_standard_loc(self):
+        """Validation error with empty loc tuple maps the field to 'root'."""
+        from fastapi.exceptions import RequestValidationError
+
+        app = FastAPI()
+        init_exceptions_handlers(app)
+
+        @app.get("/root-error")
+        async def root_error():
+            raise RequestValidationError(
+                [
+                    {
+                        "type": "custom",
+                        "loc": (),
+                        "msg": "root level error",
+                        "input": None,
+                        "url": "",
+                    }
+                ]
+            )
+
+        client = TestClient(app)
+        response = client.get("/root-error")
+
+        assert response.status_code == 422
+        data = response.json()
+        assert data["data"]["errors"][0]["field"] == "root"
+
+    def test_openapi_schema_cached_after_first_call(self):
+        """app.openapi() returns the cached schema on subsequent calls."""
+        from pydantic import BaseModel
+
+        app = FastAPI()
+        init_exceptions_handlers(app)
+
+        class Item(BaseModel):
+            name: str
+
+        @app.post("/items")
+        async def create_item(item: Item):
+            return item
+
+        schema_first = app.openapi()
+        schema_second = app.openapi()
+        assert schema_first is schema_second
+
+    def test_openapi_skips_operations_without_422(self):
+        """_patched_openapi leaves operations that have no 422 response unchanged."""
+        app = FastAPI()
+        init_exceptions_handlers(app)
+
+        @app.get("/ping")
+        async def ping():
+            return {"ok": True}
+
+        schema = app.openapi()
+        get_op = schema["paths"]["/ping"]["get"]
+        assert "422" not in get_op["responses"]
+        assert "200" in get_op["responses"]
+
+    def test_openapi_skips_non_dict_path_item_values(self):
+        """_patched_openapi ignores non-dict values in path items (e.g. path-level parameters)."""
+        from fastapi_toolsets.exceptions.handler import _patched_openapi
+
+        app = FastAPI()
+
+        def fake_openapi() -> dict:
+            return {
+                "paths": {
+                    "/items": {
+                        "parameters": [
+                            {"name": "q", "in": "query"}
+                        ],  # list, not a dict
+                        "get": {"responses": {"200": {"description": "OK"}}},
+                    }
+                }
+            }
+
+        schema = _patched_openapi(app, fake_openapi)
+        # The list value was skipped without error; the GET operation is intact
+        assert schema["paths"]["/items"]["parameters"] == [{"name": "q", "in": "query"}]
+        assert "422" not in schema["paths"]["/items"]["get"]["responses"]
 
 
 class TestExceptionIntegration:
@@ -352,12 +741,12 @@ class TestInvalidOrderFieldError:
         assert error.field == "unknown"
         assert error.valid_fields == ["name", "created_at"]
 
-    def test_message_contains_field_and_valid_fields(self):
+    def test_description_contains_field_and_valid_fields(self):
-        """Exception message mentions the bad field and valid options."""
+        """api_error.desc mentions the bad field and valid options."""
         error = InvalidOrderFieldError("bad_field", ["name", "email"])
-        assert "bad_field" in str(error)
+        assert "bad_field" in error.api_error.desc
-        assert "name" in str(error)
+        assert "name" in error.api_error.desc
-        assert "email" in str(error)
+        assert "email" in error.api_error.desc
 
     def test_handled_as_422_by_exception_handler(self):
         """init_exceptions_handlers turns InvalidOrderFieldError into a 422 response."""

tests/test_fixtures.py

@@ -14,7 +14,9 @@ from fastapi_toolsets.fixtures import (
     load_fixtures_by_context,
 )
 
-from .conftest import Role, User
+from fastapi_toolsets.fixtures.utils import _get_primary_key
+
+from .conftest import IntRole, Permission, Role, User
 
 
 class TestContext:
@@ -597,6 +599,46 @@ class TestLoadFixtures:
         count = await RoleCrud.count(db_session)
         assert count == 2
 
+    @pytest.mark.anyio
+    async def test_skip_existing_skips_if_record_exists(self, db_session: AsyncSession):
+        """SKIP_EXISTING returns empty loaded list when the record already exists."""
+        registry = FixtureRegistry()
+        role_id = uuid.uuid4()
+
+        @registry.register
+        def roles():
+            return [Role(id=role_id, name="admin")]
+
+        # First load — inserts the record.
+        result1 = await load_fixtures(
+            db_session, registry, "roles", strategy=LoadStrategy.SKIP_EXISTING
+        )
+        assert len(result1["roles"]) == 1
+
+        # Remove from identity map so session.get() queries the DB in the second load.
+        db_session.expunge_all()
+
+        # Second load — record exists in DB, nothing should be added.
+        result2 = await load_fixtures(
+            db_session, registry, "roles", strategy=LoadStrategy.SKIP_EXISTING
+        )
+        assert result2["roles"] == []
+
+    @pytest.mark.anyio
+    async def test_skip_existing_null_pk_inserts(self, db_session: AsyncSession):
+        """SKIP_EXISTING inserts when the instance has no PK set (auto-increment)."""
+        registry = FixtureRegistry()
+
+        @registry.register
+        def int_roles():
+            # No id provided — PK is None before INSERT (autoincrement).
+            return [IntRole(name="member")]
+
+        result = await load_fixtures(
+            db_session, registry, "int_roles", strategy=LoadStrategy.SKIP_EXISTING
+        )
+        assert len(result["int_roles"]) == 1
+
 
 class TestLoadFixturesByContext:
     """Tests for load_fixtures_by_context function."""
@@ -755,3 +797,19 @@ class TestGetObjByAttr:
         """Raises StopIteration when value type doesn't match."""
         with pytest.raises(StopIteration):
             get_obj_by_attr(self.roles, "id", "not-a-uuid")
+
+
+class TestGetPrimaryKey:
+    """Unit tests for the _get_primary_key helper (composite PK paths)."""
+
+    def test_composite_pk_all_set(self):
+        """Returns a tuple when all composite PK values are set."""
+        instance = Permission(subject="post", action="read")
+        pk = _get_primary_key(instance)
+        assert pk == ("post", "read")
+
+    def test_composite_pk_partial_none(self):
+        """Returns None when any composite PK value is None."""
+        instance = Permission(subject="post")  # action is None
+        pk = _get_primary_key(instance)
+        assert pk is None

tests/test_metrics.py

@@ -159,6 +159,42 @@ class TestMetricsRegistry:
         assert registry.get_all()[0].func is second
 
 
+class TestGet:
+    """Tests for MetricsRegistry.get method."""
+
+    def test_get_returns_instance_after_init(self):
+        """get() returns the metric instance stored by init_metrics."""
+        app = FastAPI()
+        registry = MetricsRegistry()
+
+        @registry.register
+        def my_gauge():
+            return Gauge("get_test_gauge", "A test gauge")
+
+        init_metrics(app, registry)
+
+        instance = registry.get("my_gauge")
+        assert isinstance(instance, Gauge)
+
+    def test_get_raises_for_registered_but_not_initialized(self):
+        """get() raises KeyError with an informative message when init_metrics was not called."""
+        registry = MetricsRegistry()
+
+        @registry.register
+        def my_counter():
+            return Counter("get_uninit_counter", "A counter")
+
+        with pytest.raises(KeyError, match="not been initialized yet"):
+            registry.get("my_counter")
+
+    def test_get_raises_for_unknown_name(self):
+        """get() raises KeyError when the metric name is not registered at all."""
+        registry = MetricsRegistry()
+
+        with pytest.raises(KeyError, match="Unknown metric"):
+            registry.get("nonexistent")
+
+
 class TestIncludeRegistry:
     """Tests for MetricsRegistry.include_registry method."""
 

tests/test_models.py

@@ -0,0 +1,967 @@
+"""Tests for fastapi_toolsets.models mixins."""
+
+import asyncio
+import uuid
+from contextlib import suppress
+from types import SimpleNamespace
+from unittest.mock import patch
+
+import fastapi_toolsets.models.watched as _watched_module
+import pytest
+from sqlalchemy import String
+from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+
+from fastapi_toolsets.models import (
+    CreatedAtMixin,
+    ModelEvent,
+    TimestampMixin,
+    UUIDMixin,
+    UUIDv7Mixin,
+    UpdatedAtMixin,
+    WatchedFieldsMixin,
+    watch,
+)
+from fastapi_toolsets.models.watched import (
+    _SESSION_CREATES,
+    _SESSION_DELETES,
+    _SESSION_UPDATES,
+    _SESSION_PENDING_NEW,
+    _after_commit,
+    _after_flush,
+    _after_flush_postexec,
+    _after_rollback,
+    _call_callback,
+    _task_error_handler,
+    _upsert_changes,
+)
+
+from .conftest import DATABASE_URL
+
+
+class MixinBase(DeclarativeBase):
+    pass
+
+
+class UUIDModel(MixinBase, UUIDMixin):
+    __tablename__ = "mixin_uuid_models"
+
+    name: Mapped[str] = mapped_column(String(50))
+
+
+class UpdatedAtModel(MixinBase, UpdatedAtMixin):
+    __tablename__ = "mixin_updated_at_models"
+
+    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
+    name: Mapped[str] = mapped_column(String(50))
+
+
+class CreatedAtModel(MixinBase, CreatedAtMixin):
+    __tablename__ = "mixin_created_at_models"
+
+    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
+    name: Mapped[str] = mapped_column(String(50))
+
+
+class TimestampModel(MixinBase, TimestampMixin):
+    __tablename__ = "mixin_timestamp_models"
+
+    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
+    name: Mapped[str] = mapped_column(String(50))
+
+
+class UUIDv7Model(MixinBase, UUIDv7Mixin):
+    __tablename__ = "mixin_uuidv7_models"
+
+    name: Mapped[str] = mapped_column(String(50))
+
+
+class FullMixinModel(MixinBase, UUIDMixin, UpdatedAtMixin):
+    __tablename__ = "mixin_full_models"
+
+    name: Mapped[str] = mapped_column(String(50))
+
+
+# --- WatchedFieldsMixin test models ---
+
+_test_events: list[dict] = []
+
+
+@watch("status")
+class WatchedModel(MixinBase, UUIDMixin, WatchedFieldsMixin):
+    __tablename__ = "mixin_watched_models"
+
+    status: Mapped[str] = mapped_column(String(50))
+    other: Mapped[str] = mapped_column(String(50))
+
+    async def on_create(self) -> None:
+        _test_events.append({"event": "create", "obj_id": self.id})
+
+    async def on_delete(self) -> None:
+        _test_events.append({"event": "delete", "obj_id": self.id})
+
+    async def on_update(self, changes: dict) -> None:
+        _test_events.append({"event": "update", "obj_id": self.id, "changes": changes})
+
+
+@watch("value")
+class OnEventModel(MixinBase, UUIDMixin, WatchedFieldsMixin):
+    """Model that only overrides on_event to test the catch-all path."""
+
+    __tablename__ = "mixin_on_event_models"
+
+    value: Mapped[str] = mapped_column(String(50))
+
+    async def on_event(self, event: ModelEvent, changes: dict | None = None) -> None:
+        _test_events.append({"event": event, "obj_id": self.id, "changes": changes})
+
+
+class WatchAllModel(MixinBase, UUIDMixin, WatchedFieldsMixin):
+    """Model without @watch — watches all mapped fields by default."""
+
+    __tablename__ = "mixin_watch_all_models"
+
+    status: Mapped[str] = mapped_column(String(50))
+    other: Mapped[str] = mapped_column(String(50))
+
+    async def on_update(self, changes: dict) -> None:
+        _test_events.append({"event": "update", "obj_id": self.id, "changes": changes})
+
+
+class NonWatchedModel(MixinBase):
+    __tablename__ = "mixin_non_watched_models"
+
+    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
+    value: Mapped[str] = mapped_column(String(50))
+
+
+_sync_events: list[dict] = []
+
+
+@watch("status")
+class SyncCallbackModel(MixinBase, UUIDMixin, WatchedFieldsMixin):
+    """Model with plain (sync) on_* callbacks."""
+
+    __tablename__ = "mixin_sync_callback_models"
+
+    status: Mapped[str] = mapped_column(String(50))
+
+    def on_create(self) -> None:
+        _sync_events.append({"event": "create", "obj_id": self.id})
+
+    def on_delete(self) -> None:
+        _sync_events.append({"event": "delete", "obj_id": self.id})
+
+    def on_update(self, changes: dict) -> None:
+        _sync_events.append({"event": "update", "changes": changes})
+
+
+@pytest.fixture(scope="function")
+async def mixin_session():
+    engine = create_async_engine(DATABASE_URL, echo=False)
+    async with engine.begin() as conn:
+        await conn.run_sync(MixinBase.metadata.create_all)
+
+    session_factory = async_sessionmaker(engine, expire_on_commit=False)
+    session = session_factory()
+
+    try:
+        yield session
+    finally:
+        await session.close()
+        async with engine.begin() as conn:
+            await conn.run_sync(MixinBase.metadata.drop_all)
+        await engine.dispose()
+
+
+class TestUUIDMixin:
+    @pytest.mark.anyio
+    async def test_uuid_generated_by_db(self, mixin_session):
+        """UUID is generated server-side and populated after flush."""
+        obj = UUIDModel(name="test")
+        mixin_session.add(obj)
+        await mixin_session.flush()
+
+        assert obj.id is not None
+        assert isinstance(obj.id, uuid.UUID)
+
+    @pytest.mark.anyio
+    async def test_uuid_is_primary_key(self):
+        """UUIDMixin adds id as primary key column."""
+        pk_cols = [c.name for c in UUIDModel.__table__.primary_key]
+        assert pk_cols == ["id"]
+
+    @pytest.mark.anyio
+    async def test_each_row_gets_unique_uuid(self, mixin_session):
+        """Each inserted row gets a distinct UUID."""
+        a = UUIDModel(name="a")
+        b = UUIDModel(name="b")
+        mixin_session.add_all([a, b])
+        await mixin_session.flush()
+
+        assert a.id != b.id
+
+    @pytest.mark.anyio
+    async def test_uuid_server_default_set(self):
+        """Column has gen_random_uuid() as server default."""
+        col = UUIDModel.__table__.c["id"]
+        assert col.server_default is not None
+        assert "gen_random_uuid" in str(col.server_default.arg)
+
+
+class TestUpdatedAtMixin:
+    @pytest.mark.anyio
+    async def test_updated_at_set_on_insert(self, mixin_session):
+        """updated_at is populated after insert."""
+        obj = UpdatedAtModel(name="initial")
+        mixin_session.add(obj)
+        await mixin_session.flush()
+        await mixin_session.refresh(obj)
+
+        assert obj.updated_at is not None
+        assert obj.updated_at.tzinfo is not None
+
+    @pytest.mark.anyio
+    async def test_updated_at_changes_on_update(self, mixin_session):
+        """updated_at is updated when the row is modified."""
+        obj = UpdatedAtModel(name="initial")
+        mixin_session.add(obj)
+        await mixin_session.flush()
+        await mixin_session.refresh(obj)
+
+        original_ts = obj.updated_at
+
+        obj.name = "modified"
+        await mixin_session.flush()
+        await mixin_session.refresh(obj)
+
+        assert obj.updated_at >= original_ts
+
+    @pytest.mark.anyio
+    async def test_updated_at_column_is_not_nullable(self):
+        """updated_at column is non-nullable."""
+        col = UpdatedAtModel.__table__.c["updated_at"]
+        assert not col.nullable
+
+    @pytest.mark.anyio
+    async def test_updated_at_has_server_default(self):
+        """updated_at column has a server-side default."""
+        col = UpdatedAtModel.__table__.c["updated_at"]
+        assert col.server_default is not None
+
+    @pytest.mark.anyio
+    async def test_updated_at_has_onupdate(self):
+        """updated_at column has an onupdate clause."""
+        col = UpdatedAtModel.__table__.c["updated_at"]
+        assert col.onupdate is not None
+
+
+class TestCreatedAtMixin:
+    @pytest.mark.anyio
+    async def test_created_at_set_on_insert(self, mixin_session):
+        """created_at is populated after insert."""
+        obj = CreatedAtModel(name="new")
+        mixin_session.add(obj)
+        await mixin_session.flush()
+        await mixin_session.refresh(obj)
+
+        assert obj.created_at is not None
+        assert obj.created_at.tzinfo is not None
+
+    @pytest.mark.anyio
+    async def test_created_at_not_changed_on_update(self, mixin_session):
+        """created_at is not modified when the row is updated."""
+        obj = CreatedAtModel(name="original")
+        mixin_session.add(obj)
+        await mixin_session.flush()
+        await mixin_session.refresh(obj)
+
+        original_ts = obj.created_at
+
+        obj.name = "updated"
+        await mixin_session.flush()
+        await mixin_session.refresh(obj)
+
+        assert obj.created_at == original_ts
+
+    @pytest.mark.anyio
+    async def test_created_at_column_is_not_nullable(self):
+        """created_at column is non-nullable."""
+        col = CreatedAtModel.__table__.c["created_at"]
+        assert not col.nullable
+
+    @pytest.mark.anyio
+    async def test_created_at_has_no_onupdate(self):
+        """created_at column has no onupdate clause."""
+        col = CreatedAtModel.__table__.c["created_at"]
+        assert col.onupdate is None
+
+
+class TestTimestampMixin:
+    @pytest.mark.anyio
+    async def test_both_columns_set_on_insert(self, mixin_session):
+        """created_at and updated_at are both populated after insert."""
+        obj = TimestampModel(name="new")
+        mixin_session.add(obj)
+        await mixin_session.flush()
+        await mixin_session.refresh(obj)
+
+        assert obj.created_at is not None
+        assert obj.updated_at is not None
+
+    @pytest.mark.anyio
+    async def test_created_at_stable_updated_at_changes_on_update(self, mixin_session):
+        """On update: created_at stays the same, updated_at advances."""
+        obj = TimestampModel(name="original")
+        mixin_session.add(obj)
+        await mixin_session.flush()
+        await mixin_session.refresh(obj)
+
+        original_created = obj.created_at
+        original_updated = obj.updated_at
+
+        obj.name = "modified"
+        await mixin_session.flush()
+        await mixin_session.refresh(obj)
+
+        assert obj.created_at == original_created
+        assert obj.updated_at >= original_updated
+
+    @pytest.mark.anyio
+    async def test_timestamp_mixin_has_both_columns(self):
+        """TimestampModel exposes both created_at and updated_at columns."""
+        col_names = {c.name for c in TimestampModel.__table__.columns}
+        assert "created_at" in col_names
+        assert "updated_at" in col_names
+
+
+class TestUUIDv7Mixin:
+    @pytest.mark.anyio
+    async def test_uuid7_generated_by_db(self, mixin_session):
+        """UUIDv7 is generated server-side and populated after flush."""
+        obj = UUIDv7Model(name="test")
+        mixin_session.add(obj)
+        await mixin_session.flush()
+
+        assert obj.id is not None
+        assert isinstance(obj.id, uuid.UUID)
+
+    @pytest.mark.anyio
+    async def test_uuid7_is_primary_key(self):
+        """UUIDv7Mixin adds id as primary key column."""
+        pk_cols = [c.name for c in UUIDv7Model.__table__.primary_key]
+        assert pk_cols == ["id"]
+
+    @pytest.mark.anyio
+    async def test_each_row_gets_unique_uuid7(self, mixin_session):
+        """Each inserted row gets a distinct UUIDv7."""
+        a = UUIDv7Model(name="a")
+        b = UUIDv7Model(name="b")
+        mixin_session.add_all([a, b])
+        await mixin_session.flush()
+
+        assert a.id != b.id
+
+    @pytest.mark.anyio
+    async def test_uuid7_version(self, mixin_session):
+        """Generated UUIDs have version 7."""
+        obj = UUIDv7Model(name="test")
+        mixin_session.add(obj)
+        await mixin_session.flush()
+
+        assert obj.id.version == 7
+
+    @pytest.mark.anyio
+    async def test_uuid7_server_default_set(self):
+        """Column has uuidv7() as server default."""
+        col = UUIDv7Model.__table__.c["id"]
+        assert col.server_default is not None
+        assert "uuidv7" in str(col.server_default.arg)
+
+
+class TestFullMixinModel:
+    @pytest.mark.anyio
+    async def test_combined_mixins_work_together(self, mixin_session):
+        """UUIDMixin and UpdatedAtMixin can be combined on the same model."""
+        obj = FullMixinModel(name="combined")
+        mixin_session.add(obj)
+        await mixin_session.flush()
+        await mixin_session.refresh(obj)
+
+        assert isinstance(obj.id, uuid.UUID)
+        assert obj.updated_at is not None
+        assert obj.updated_at.tzinfo is not None
+
+
+class TestWatchDecorator:
+    def test_registers_specific_fields(self):
+        """@watch("field") stores the field list in _WATCHED_FIELDS."""
+        assert _watched_module._WATCHED_FIELDS.get(WatchedModel) == ["status"]
+
+    def test_no_decorator_not_in_watched_fields(self):
+        """A model without @watch has no entry in _WATCHED_FIELDS (watch all)."""
+        assert WatchAllModel not in _watched_module._WATCHED_FIELDS
+
+    def test_preserves_class_identity(self):
+        """watch returns the same class unchanged."""
+
+        class _Dummy(WatchedFieldsMixin):
+            pass
+
+        result = watch("x")(_Dummy)
+        assert result is _Dummy
+        del _watched_module._WATCHED_FIELDS[_Dummy]
+
+    def test_raises_when_no_fields_given(self):
+        """@watch() with no field names raises ValueError."""
+        with pytest.raises(ValueError, match="@watch requires at least one field name"):
+            watch()
+
+
+class TestUpsertChanges:
+    def test_inserts_new_entry(self):
+        """New key is inserted with the full changes dict."""
+        pending: dict = {}
+        obj = object()
+        changes = {"status": {"old": None, "new": "active"}}
+        _upsert_changes(pending, obj, changes)
+        assert pending[id(obj)] == (obj, changes)
+
+    def test_merges_existing_field_keeps_old_updates_new(self):
+        """When the field already exists, old is preserved and new is overwritten."""
+        obj = object()
+        pending = {
+            id(obj): (obj, {"status": {"old": "initial", "new": "intermediate"}})
+        }
+        _upsert_changes(
+            pending, obj, {"status": {"old": "intermediate", "new": "final"}}
+        )
+        assert pending[id(obj)][1]["status"] == {"old": "initial", "new": "final"}
+
+    def test_adds_new_field_to_existing_entry(self):
+        """A previously unseen field is added alongside existing ones."""
+        obj = object()
+        pending = {id(obj): (obj, {"status": {"old": "a", "new": "b"}})}
+        _upsert_changes(pending, obj, {"role": {"old": "user", "new": "admin"}})
+        fields = pending[id(obj)][1]
+        assert fields["status"] == {"old": "a", "new": "b"}
+        assert fields["role"] == {"old": "user", "new": "admin"}
+
+
+class TestAfterFlush:
+    def test_does_nothing_with_empty_session(self):
+        """_after_flush writes nothing to session.info when all collections are empty."""
+        session = SimpleNamespace(new=[], deleted=[], dirty=[], info={})
+        _after_flush(session, None)
+        assert session.info == {}
+
+    def test_captures_new_watched_mixin_objects(self):
+        """New WatchedFieldsMixin instances are added to _SESSION_PENDING_NEW."""
+        obj = WatchedFieldsMixin()
+        session = SimpleNamespace(new=[obj], deleted=[], dirty=[], info={})
+        _after_flush(session, None)
+        assert session.info[_SESSION_PENDING_NEW] == [obj]
+
+    def test_ignores_new_non_mixin_objects(self):
+        """New objects that are not WatchedFieldsMixin are not captured."""
+        obj = object()
+        session = SimpleNamespace(new=[obj], deleted=[], dirty=[], info={})
+        _after_flush(session, None)
+        assert _SESSION_PENDING_NEW not in session.info
+
+    def test_captures_deleted_watched_mixin_objects(self):
+        """Deleted WatchedFieldsMixin instances are added to _SESSION_DELETES."""
+        obj = WatchedFieldsMixin()
+        session = SimpleNamespace(new=[], deleted=[obj], dirty=[], info={})
+        _after_flush(session, None)
+        assert session.info[_SESSION_DELETES] == [obj]
+
+    def test_ignores_deleted_non_mixin_objects(self):
+        """Deleted objects that are not WatchedFieldsMixin are not captured."""
+        obj = object()
+        session = SimpleNamespace(new=[], deleted=[obj], dirty=[], info={})
+        _after_flush(session, None)
+        assert _SESSION_DELETES not in session.info
+
+
+class TestAfterFlushPostexec:
+    def test_does_nothing_when_no_pending_new(self):
+        """_after_flush_postexec does nothing when _SESSION_PENDING_NEW is absent."""
+        session = SimpleNamespace(info={})
+        _after_flush_postexec(session, None)
+        assert _SESSION_CREATES not in session.info
+
+    def test_moves_pending_new_to_creates(self):
+        """Objects from _SESSION_PENDING_NEW are moved to _SESSION_CREATES."""
+        obj = object()
+        session = SimpleNamespace(info={_SESSION_PENDING_NEW: [obj]})
+        _after_flush_postexec(session, None)
+        assert _SESSION_PENDING_NEW not in session.info
+        assert session.info[_SESSION_CREATES] == [obj]
+
+    def test_extends_existing_creates(self):
+        """Multiple flushes accumulate in _SESSION_CREATES."""
+        a, b = object(), object()
+        session = SimpleNamespace(
+            info={_SESSION_PENDING_NEW: [b], _SESSION_CREATES: [a]}
+        )
+        _after_flush_postexec(session, None)
+        assert session.info[_SESSION_CREATES] == [a, b]
+
+
+class TestAfterRollback:
+    def test_clears_all_session_info_keys(self):
+        """_after_rollback removes all four tracking keys from session.info."""
+        session = SimpleNamespace(
+            info={
+                _SESSION_PENDING_NEW: [object()],
+                _SESSION_CREATES: [object()],
+                _SESSION_DELETES: [object()],
+                _SESSION_UPDATES: {1: ("obj", {"f": {"old": "a", "new": "b"}})},
+            }
+        )
+        _after_rollback(session)
+        assert _SESSION_PENDING_NEW not in session.info
+        assert _SESSION_CREATES not in session.info
+        assert _SESSION_DELETES not in session.info
+        assert _SESSION_UPDATES not in session.info
+
+    def test_tolerates_missing_keys(self):
+        """_after_rollback does not raise when session.info has no pending data."""
+        session = SimpleNamespace(info={})
+        _after_rollback(session)  # must not raise
+
+
+class TestTaskErrorHandler:
+    @pytest.mark.anyio
+    async def test_logs_exception_from_failed_task(self):
+        """_task_error_handler calls _logger.error when the task raised."""
+
+        async def failing() -> None:
+            raise ValueError("boom")
+
+        task = asyncio.create_task(failing())
+        await asyncio.sleep(0)
+
+        with patch.object(_watched_module._logger, "error") as mock_error:
+            _task_error_handler(task)
+            mock_error.assert_called_once()
+
+    @pytest.mark.anyio
+    async def test_ignores_cancelled_task(self):
+        """_task_error_handler does not log when the task was cancelled."""
+
+        async def slow() -> None:
+            await asyncio.sleep(100)
+
+        task = asyncio.create_task(slow())
+        task.cancel()
+        with suppress(asyncio.CancelledError):
+            await task
+
+        with patch.object(_watched_module._logger, "error") as mock_error:
+            _task_error_handler(task)
+            mock_error.assert_not_called()
+
+
+class TestAfterCommitNoLoop:
+    def test_no_task_scheduled_when_no_running_loop(self):
+        """_after_commit silently returns when called outside an async context."""
+        called = []
+        obj = SimpleNamespace(on_create=lambda: called.append("create"))
+        session = SimpleNamespace(info={_SESSION_CREATES: [obj]})
+        _after_commit(session)
+        assert called == []
+
+    def test_returns_early_when_all_pending_empty(self):
+        """_after_commit does nothing when all pending lists are empty."""
+        session = SimpleNamespace(info={})
+        _after_commit(session)  # should not raise
+
+
+class TestWatchedFieldsMixin:
+    @pytest.fixture(autouse=True)
+    def clear_events(self):
+        _test_events.clear()
+        yield
+        _test_events.clear()
+
+    # --- on_create ---
+
+    @pytest.mark.anyio
+    async def test_on_create_fires_after_insert(self, mixin_session):
+        """on_create is called after INSERT commit."""
+        obj = WatchedModel(status="active", other="x")
+        mixin_session.add(obj)
+        await mixin_session.commit()
+        await asyncio.sleep(0)
+
+        creates = [e for e in _test_events if e["event"] == "create"]
+        assert len(creates) == 1
+
+    @pytest.mark.anyio
+    async def test_on_create_server_defaults_populated(self, mixin_session):
+        """id (server default via RETURNING) is available inside on_create."""
+        obj = WatchedModel(status="active", other="x")
+        mixin_session.add(obj)
+        await mixin_session.commit()
+        await asyncio.sleep(0)
+
+        creates = [e for e in _test_events if e["event"] == "create"]
+        assert creates[0]["obj_id"] is not None
+        assert isinstance(creates[0]["obj_id"], uuid.UUID)
+
+    @pytest.mark.anyio
+    async def test_on_create_not_fired_on_update(self, mixin_session):
+        """on_create is NOT called when an existing row is updated."""
+        obj = WatchedModel(status="initial", other="x")
+        mixin_session.add(obj)
+        await mixin_session.commit()
+        await asyncio.sleep(0)
+        _test_events.clear()
+
+        obj.status = "updated"
+        await mixin_session.commit()
+        await asyncio.sleep(0)
+
+        assert not any(e["event"] == "create" for e in _test_events)
+
+    # --- on_delete ---
+
+    @pytest.mark.anyio
+    async def test_on_delete_fires_after_delete(self, mixin_session):
+        """on_delete is called after DELETE commit."""
+        obj = WatchedModel(status="active", other="x")
+        mixin_session.add(obj)
+        await mixin_session.commit()
+        await asyncio.sleep(0)
+        saved_id = obj.id
+        _test_events.clear()
+
+        await mixin_session.delete(obj)
+        await mixin_session.commit()
+        await asyncio.sleep(0)
+
+        deletes = [e for e in _test_events if e["event"] == "delete"]
+        assert len(deletes) == 1
+        assert deletes[0]["obj_id"] == saved_id
+
+    @pytest.mark.anyio
+    async def test_on_delete_not_fired_on_insert(self, mixin_session):
+        """on_delete is NOT called when a new row is inserted."""
+        obj = WatchedModel(status="active", other="x")
+        mixin_session.add(obj)
+        await mixin_session.commit()
+        await asyncio.sleep(0)
+
+        assert not any(e["event"] == "delete" for e in _test_events)
+
+    # --- on_update ---
+
+    @pytest.mark.anyio
+    async def test_on_update_fires_on_update(self, mixin_session):
+        """on_update reports the correct before/after values on UPDATE."""
+        obj = WatchedModel(status="initial", other="x")
+        mixin_session.add(obj)
+        await mixin_session.commit()
+        await asyncio.sleep(0)
+        _test_events.clear()
+
+        obj.status = "updated"
+        await mixin_session.commit()
+        await asyncio.sleep(0)
+
+        changes_events = [e for e in _test_events if e["event"] == "update"]
+        assert len(changes_events) == 1
+        assert changes_events[0]["changes"]["status"] == {
+            "old": "initial",
+            "new": "updated",
+        }
+
+    @pytest.mark.anyio
+    async def test_on_update_not_fired_on_insert(self, mixin_session):
+        """on_update is NOT called on INSERT (on_create handles that)."""
+        obj = WatchedModel(status="active", other="x")
+        mixin_session.add(obj)
+        await mixin_session.commit()
+        await asyncio.sleep(0)
+
+        assert not any(e["event"] == "update" for e in _test_events)
+
+    @pytest.mark.anyio
+    async def test_unwatched_field_update_no_callback(self, mixin_session):
+        """Changing a field not listed in @update does not fire on_update."""
+        obj = WatchedModel(status="active", other="x")
+        mixin_session.add(obj)
+        await mixin_session.commit()
+        await asyncio.sleep(0)
+        _test_events.clear()
+
+        obj.other = "changed"
+        await mixin_session.commit()
+        await asyncio.sleep(0)
+
+        assert _test_events == []
+
+    @pytest.mark.anyio
+    async def test_multiple_flushes_merge_earliest_old_latest_new(self, mixin_session):
+        """Two flushes in one transaction produce a single callback with earliest old / latest new."""
+        obj = WatchedModel(status="initial", other="x")
+        mixin_session.add(obj)
+        await mixin_session.commit()
+        await asyncio.sleep(0)
+        _test_events.clear()
+
+        obj.status = "intermediate"
+        await mixin_session.flush()
+
+        obj.status = "final"
+        await mixin_session.commit()
+        await asyncio.sleep(0)
+
+        changes_events = [e for e in _test_events if e["event"] == "update"]
+        assert len(changes_events) == 1
+        assert changes_events[0]["changes"]["status"] == {
+            "old": "initial",
+            "new": "final",
+        }
+
+    @pytest.mark.anyio
+    async def test_rollback_suppresses_all_callbacks(self, mixin_session):
+        """No callbacks are fired when the transaction is rolled back."""
+        obj = WatchedModel(status="active", other="x")
+        mixin_session.add(obj)
+        await mixin_session.commit()
+        await asyncio.sleep(0)
+        _test_events.clear()
+
+        obj.status = "changed"
+        await mixin_session.flush()
+        await mixin_session.rollback()
+        await asyncio.sleep(0)
+
+        assert _test_events == []
+
+    @pytest.mark.anyio
+    async def test_non_watched_model_no_callback(self, mixin_session):
+        """Dirty objects whose type is not a WatchedFieldsMixin are skipped."""
+        nw = NonWatchedModel(value="x")
+        mixin_session.add(nw)
+        await mixin_session.flush()
+        nw.value = "y"
+        await mixin_session.commit()
+        await asyncio.sleep(0)
+
+        assert _test_events == []
+
+    # --- on_event (catch-all) ---
+
+    @pytest.mark.anyio
+    async def test_on_event_receives_create(self, mixin_session):
+        """on_event is called with ModelEvent.CREATE on INSERT when only on_event is overridden."""
+        obj = OnEventModel(value="x")
+        mixin_session.add(obj)
+        await mixin_session.commit()
+        await asyncio.sleep(0)
+
+        creates = [e for e in _test_events if e["event"] == ModelEvent.CREATE]
+        assert len(creates) == 1
+        assert creates[0]["changes"] is None
+
+    @pytest.mark.anyio
+    async def test_on_event_receives_delete(self, mixin_session):
+        """on_event is called with ModelEvent.DELETE on DELETE when only on_event is overridden."""
+        obj = OnEventModel(value="x")
+        mixin_session.add(obj)
+        await mixin_session.commit()
+        await asyncio.sleep(0)
+        _test_events.clear()
+
+        await mixin_session.delete(obj)
+        await mixin_session.commit()
+        await asyncio.sleep(0)
+
+        deletes = [e for e in _test_events if e["event"] == ModelEvent.DELETE]
+        assert len(deletes) == 1
+        assert deletes[0]["changes"] is None
+
+    @pytest.mark.anyio
+    async def test_on_event_receives_field_change(self, mixin_session):
+        """on_event is called with ModelEvent.UPDATE on UPDATE when only on_event is overridden."""
+        obj = OnEventModel(value="initial")
+        mixin_session.add(obj)
+        await mixin_session.commit()
+        await asyncio.sleep(0)
+        _test_events.clear()
+
+        obj.value = "updated"
+        await mixin_session.commit()
+        await asyncio.sleep(0)
+
+        changes_events = [e for e in _test_events if e["event"] == ModelEvent.UPDATE]
+        assert len(changes_events) == 1
+        assert changes_events[0]["changes"]["value"] == {
+            "old": "initial",
+            "new": "updated",
+        }
+
+
+class TestWatchAll:
+    @pytest.fixture(autouse=True)
+    def clear_events(self):
+        _test_events.clear()
+        yield
+        _test_events.clear()
+
+    @pytest.mark.anyio
+    async def test_watch_all_fires_for_any_field(self, mixin_session):
+        """Model without @watch fires on_update for any changed field."""
+        obj = WatchAllModel(status="initial", other="x")
+        mixin_session.add(obj)
+        await mixin_session.commit()
+        await asyncio.sleep(0)
+        _test_events.clear()
+
+        obj.other = "changed"
+        await mixin_session.commit()
+        await asyncio.sleep(0)
+
+        changes_events = [e for e in _test_events if e["event"] == "update"]
+        assert len(changes_events) == 1
+        assert "other" in changes_events[0]["changes"]
+
+    @pytest.mark.anyio
+    async def test_watch_all_captures_multiple_fields(self, mixin_session):
+        """Model without @watch captures all fields changed in a single commit."""
+        obj = WatchAllModel(status="initial", other="x")
+        mixin_session.add(obj)
+        await mixin_session.commit()
+        await asyncio.sleep(0)
+        _test_events.clear()
+
+        obj.status = "updated"
+        obj.other = "changed"
+        await mixin_session.commit()
+        await asyncio.sleep(0)
+
+        changes_events = [e for e in _test_events if e["event"] == "update"]
+        assert len(changes_events) == 1
+        assert "status" in changes_events[0]["changes"]
+        assert "other" in changes_events[0]["changes"]
+
+
+class TestSyncCallbacks:
+    @pytest.fixture(autouse=True)
+    def clear_events(self):
+        _sync_events.clear()
+        yield
+        _sync_events.clear()
+
+    @pytest.mark.anyio
+    async def test_sync_on_create_fires(self, mixin_session):
+        """Sync on_create is called after INSERT commit."""
+        obj = SyncCallbackModel(status="active")
+        mixin_session.add(obj)
+        await mixin_session.commit()
+        await asyncio.sleep(0)
+
+        creates = [e for e in _sync_events if e["event"] == "create"]
+        assert len(creates) == 1
+        assert isinstance(creates[0]["obj_id"], uuid.UUID)
+
+    @pytest.mark.anyio
+    async def test_sync_on_delete_fires(self, mixin_session):
+        """Sync on_delete is called after DELETE commit."""
+        obj = SyncCallbackModel(status="active")
+        mixin_session.add(obj)
+        await mixin_session.commit()
+        await asyncio.sleep(0)
+        _sync_events.clear()
+
+        await mixin_session.delete(obj)
+        await mixin_session.commit()
+        await asyncio.sleep(0)
+
+        deletes = [e for e in _sync_events if e["event"] == "delete"]
+        assert len(deletes) == 1
+
+    @pytest.mark.anyio
+    async def test_sync_on_update_fires(self, mixin_session):
+        """Sync on_update is called after UPDATE commit with correct changes."""
+        obj = SyncCallbackModel(status="initial")
+        mixin_session.add(obj)
+        await mixin_session.commit()
+        await asyncio.sleep(0)
+        _sync_events.clear()
+
+        obj.status = "updated"
+        await mixin_session.commit()
+        await asyncio.sleep(0)
+
+        updates = [e for e in _sync_events if e["event"] == "update"]
+        assert len(updates) == 1
+        assert updates[0]["changes"]["status"] == {"old": "initial", "new": "updated"}
+
+
+class TestCallCallback:
+    @pytest.mark.anyio
+    async def test_async_callback_scheduled_as_task(self):
+        """_call_callback schedules async functions as tasks."""
+        called = []
+
+        async def async_fn() -> None:
+            called.append("async")
+
+        loop = asyncio.get_running_loop()
+        _call_callback(loop, async_fn)
+        await asyncio.sleep(0)
+        assert called == ["async"]
+
+    @pytest.mark.anyio
+    async def test_sync_callback_called_directly(self):
+        """_call_callback invokes sync functions immediately."""
+        called = []
+
+        def sync_fn() -> None:
+            called.append("sync")
+
+        loop = asyncio.get_running_loop()
+        _call_callback(loop, sync_fn)
+        assert called == ["sync"]
+
+    @pytest.mark.anyio
+    async def test_sync_callback_exception_logged(self):
+        """_call_callback logs exceptions from sync callbacks."""
+
+        def failing_fn() -> None:
+            raise RuntimeError("sync error")
+
+        loop = asyncio.get_running_loop()
+        with patch.object(_watched_module._logger, "error") as mock_error:
+            _call_callback(loop, failing_fn)
+            mock_error.assert_called_once()
+
+    @pytest.mark.anyio
+    async def test_async_callback_with_args(self):
+        """_call_callback passes arguments to async callbacks."""
+        received = []
+
+        async def async_fn(changes: dict) -> None:
+            received.append(changes)
+
+        loop = asyncio.get_running_loop()
+        _call_callback(loop, async_fn, {"status": {"old": "a", "new": "b"}})
+        await asyncio.sleep(0)
+        assert received == [{"status": {"old": "a", "new": "b"}}]
+
+    @pytest.mark.anyio
+    async def test_sync_callback_with_args(self):
+        """_call_callback passes arguments to sync callbacks."""
+        received = []
+
+        def sync_fn(changes: dict) -> None:
+            received.append(changes)
+
+        loop = asyncio.get_running_loop()
+        _call_callback(loop, sync_fn, {"x": 1})
+        assert received == [{"x": 1}]

tests/test_pytest.py

@@ -8,11 +8,10 @@ from httpx import AsyncClient
 from sqlalchemy import select, text
 from sqlalchemy.engine import make_url
 from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine
-from sqlalchemy.orm import DeclarativeBase, selectinload
+from sqlalchemy.orm import selectinload
 
 from fastapi_toolsets.fixtures import Context, FixtureRegistry
 from fastapi_toolsets.pytest import (
-    cleanup_tables,
     create_async_client,
     create_db_session,
     create_worker_database,
@@ -406,7 +405,6 @@ class TestCreateWorkerDatabase:
         ) as url:
             assert make_url(url).database == expected_db
 
-            # Verify the database exists while inside the context
             engine = create_async_engine(DATABASE_URL, isolation_level="AUTOCOMMIT")
             async with engine.connect() as conn:
                 result = await conn.execute(
@@ -416,7 +414,6 @@ class TestCreateWorkerDatabase:
                 assert result.scalar() == 1
             await engine.dispose()
 
-        # After context exit the database should be dropped
         engine = create_async_engine(DATABASE_URL, isolation_level="AUTOCOMMIT")
         async with engine.connect() as conn:
             result = await conn.execute(
@@ -439,7 +436,6 @@ class TestCreateWorkerDatabase:
         async with create_worker_database(DATABASE_URL) as url:
             assert make_url(url).database == expected_db
 
-            # Verify the database exists while inside the context
             engine = create_async_engine(DATABASE_URL, isolation_level="AUTOCOMMIT")
             async with engine.connect() as conn:
                 result = await conn.execute(
@@ -449,7 +445,6 @@ class TestCreateWorkerDatabase:
                 assert result.scalar() == 1
             await engine.dispose()
 
-        # After context exit the database should be dropped
         engine = create_async_engine(DATABASE_URL, isolation_level="AUTOCOMMIT")
         async with engine.connect() as conn:
             result = await conn.execute(
@@ -467,18 +462,15 @@ class TestCreateWorkerDatabase:
             worker_database_url(DATABASE_URL, default_test_db="unused")
         ).database
 
-        # Pre-create the database to simulate a stale leftover
         engine = create_async_engine(DATABASE_URL, isolation_level="AUTOCOMMIT")
         async with engine.connect() as conn:
             await conn.execute(text(f"DROP DATABASE IF EXISTS {expected_db}"))
             await conn.execute(text(f"CREATE DATABASE {expected_db}"))
         await engine.dispose()
 
-        # Should succeed despite the database already existing
         async with create_worker_database(DATABASE_URL) as url:
             assert make_url(url).database == expected_db
 
-        # Verify cleanup after context exit
         engine = create_async_engine(DATABASE_URL, isolation_level="AUTOCOMMIT")
         async with engine.connect() as conn:
             result = await conn.execute(
@@ -487,49 +479,3 @@ class TestCreateWorkerDatabase:
             )
             assert result.scalar() is None
         await engine.dispose()
-
-
-class TestCleanupTables:
-    """Tests for cleanup_tables helper."""
-
-    @pytest.mark.anyio
-    async def test_truncates_all_tables(self):
-        """All table rows are removed after cleanup_tables."""
-        async with create_db_session(DATABASE_URL, Base, drop_tables=True) as session:
-            role = Role(id=uuid.uuid4(), name="cleanup_role")
-            session.add(role)
-            await session.flush()
-
-            user = User(
-                id=uuid.uuid4(),
-                username="cleanup_user",
-                email="cleanup@test.com",
-                role_id=role.id,
-            )
-            session.add(user)
-            await session.commit()
-
-            # Verify rows exist
-            roles_count = await RoleCrud.count(session)
-            users_count = await UserCrud.count(session)
-            assert roles_count == 1
-            assert users_count == 1
-
-            await cleanup_tables(session, Base)
-
-            # Verify tables are empty
-            roles_count = await RoleCrud.count(session)
-            users_count = await UserCrud.count(session)
-            assert roles_count == 0
-            assert users_count == 0
-
-    @pytest.mark.anyio
-    async def test_noop_for_empty_metadata(self):
-        """cleanup_tables does not raise when metadata has no tables."""
-
-        class EmptyBase(DeclarativeBase):
-            pass
-
-        async with create_db_session(DATABASE_URL, Base, drop_tables=True) as session:
-            # Should not raise
-            await cleanup_tables(session, EmptyBase)

tests/test_schemas.py

@@ -6,10 +6,12 @@ from pydantic import ValidationError
 from fastapi_toolsets.schemas import (
     ApiError,
     CursorPagination,
+    CursorPaginatedResponse,
     ErrorResponse,
     OffsetPagination,
+    OffsetPaginatedResponse,
     PaginatedResponse,
-    Pagination,
+    PaginationType,
     Response,
     ResponseStatus,
 )
@@ -199,20 +201,6 @@ class TestOffsetPagination:
         assert data["page"] == 2
         assert data["has_more"] is True
 
-    def test_pagination_alias_is_offset_pagination(self):
-        """Pagination is a backward-compatible alias for OffsetPagination."""
-        assert Pagination is OffsetPagination
-
-    def test_pagination_alias_constructs_offset_pagination(self):
-        """Code using Pagination(...) still works unchanged."""
-        pagination = Pagination(
-            total_count=10,
-            items_per_page=5,
-            page=2,
-            has_more=False,
-        )
-        assert isinstance(pagination, OffsetPagination)
-
 
 class TestCursorPagination:
     """Tests for CursorPagination schema."""
@@ -276,7 +264,7 @@ class TestPaginatedResponse:
 
     def test_create_paginated_response(self):
         """Create PaginatedResponse with data and pagination."""
-        pagination = Pagination(
+        pagination = OffsetPagination(
             total_count=30,
             items_per_page=10,
             page=1,
@@ -294,7 +282,7 @@ class TestPaginatedResponse:
 
     def test_with_custom_message(self):
         """PaginatedResponse with custom message."""
-        pagination = Pagination(
+        pagination = OffsetPagination(
             total_count=5,
             items_per_page=10,
             page=1,
@@ -310,13 +298,13 @@ class TestPaginatedResponse:
 
     def test_empty_data(self):
         """PaginatedResponse with empty data."""
-        pagination = Pagination(
+        pagination = OffsetPagination(
             total_count=0,
             items_per_page=10,
             page=1,
             has_more=False,
         )
-        response = PaginatedResponse[dict](
+        response = PaginatedResponse(
             data=[],
             pagination=pagination,
         )
@@ -325,14 +313,33 @@ class TestPaginatedResponse:
         assert response.data == []
         assert response.pagination.total_count == 0
 
+    def test_class_getitem_with_concrete_type_returns_discriminated_union(self):
+        """PaginatedResponse[T] with a concrete type returns a discriminated Annotated union."""
+        import typing
+
+        alias = PaginatedResponse[dict]
+        args = typing.get_args(alias)
+        # args[0] is the Union, args[1] is the FieldInfo discriminator
+        union_args = typing.get_args(args[0])
+        assert CursorPaginatedResponse[dict] in union_args
+        assert OffsetPaginatedResponse[dict] in union_args
+
+    def test_class_getitem_is_cached(self):
+        """Repeated subscripting with the same type returns the identical cached object."""
+        assert PaginatedResponse[dict] is PaginatedResponse[dict]
+
+    def test_class_getitem_with_typevar_returns_generic(self):
+        """PaginatedResponse[TypeVar] falls through to Pydantic generic parametrisation."""
+        from typing import TypeVar
+
+        T = TypeVar("T")
+        alias = PaginatedResponse[T]
+        # Should be a generic alias, not an Annotated union
+        assert not hasattr(alias, "__metadata__")
+
     def test_generic_type_hint(self):
         """PaginatedResponse supports generic type hints."""
-
+        pagination = OffsetPagination(
-        class UserOut:
-            id: int
-            name: str
-
-        pagination = Pagination(
             total_count=1,
             items_per_page=10,
             page=1,
@@ -347,7 +354,7 @@ class TestPaginatedResponse:
 
     def test_serialization(self):
         """PaginatedResponse serializes correctly."""
-        pagination = Pagination(
+        pagination = OffsetPagination(
             total_count=100,
             items_per_page=10,
             page=5,
@@ -385,15 +392,190 @@ class TestPaginatedResponse:
         )
         assert isinstance(response.pagination, CursorPagination)
 
-    def test_pagination_alias_accepted(self):
+
-        """Constructing PaginatedResponse with Pagination (alias) still works."""
+class TestPaginationType:
-        response = PaginatedResponse(
+    """Tests for PaginationType enum."""
+
+    def test_offset_value(self):
+        """OFFSET has string value 'offset'."""
+        assert PaginationType.OFFSET == "offset"
+        assert PaginationType.OFFSET.value == "offset"
+
+    def test_cursor_value(self):
+        """CURSOR has string value 'cursor'."""
+        assert PaginationType.CURSOR == "cursor"
+        assert PaginationType.CURSOR.value == "cursor"
+
+    def test_is_string_enum(self):
+        """PaginationType is a string enum."""
+        assert isinstance(PaginationType.OFFSET, str)
+        assert isinstance(PaginationType.CURSOR, str)
+
+    def test_members(self):
+        """PaginationType has exactly two members."""
+        assert set(PaginationType) == {PaginationType.OFFSET, PaginationType.CURSOR}
+
+
+class TestOffsetPaginatedResponse:
+    """Tests for OffsetPaginatedResponse schema."""
+
+    def test_pagination_type_is_offset(self):
+        """pagination_type is always PaginationType.OFFSET."""
+        response = OffsetPaginatedResponse(
             data=[],
-            pagination=Pagination(
+            pagination=OffsetPagination(
                 total_count=0, items_per_page=10, page=1, has_more=False
             ),
         )
+        assert response.pagination_type is PaginationType.OFFSET
+
+    def test_pagination_type_serializes_to_string(self):
+        """pagination_type serializes to 'offset' in JSON mode."""
+        response = OffsetPaginatedResponse(
+            data=[],
+            pagination=OffsetPagination(
+                total_count=0, items_per_page=10, page=1, has_more=False
+            ),
+        )
+        assert response.model_dump(mode="json")["pagination_type"] == "offset"
+
+    def test_pagination_field_is_typed(self):
+        """pagination field is OffsetPagination, not the union."""
+        response = OffsetPaginatedResponse(
+            data=[{"id": 1}],
+            pagination=OffsetPagination(
+                total_count=10, items_per_page=5, page=2, has_more=True
+            ),
+        )
         assert isinstance(response.pagination, OffsetPagination)
+        assert response.pagination.total_count == 10
+        assert response.pagination.page == 2
+
+    def test_is_subclass_of_paginated_response(self):
+        """OffsetPaginatedResponse IS a PaginatedResponse."""
+        response = OffsetPaginatedResponse(
+            data=[],
+            pagination=OffsetPagination(
+                total_count=0, items_per_page=10, page=1, has_more=False
+            ),
+        )
+        assert isinstance(response, PaginatedResponse)
+
+    def test_pagination_type_default_cannot_be_overridden_to_cursor(self):
+        """pagination_type rejects values other than OFFSET."""
+        with pytest.raises(ValidationError):
+            OffsetPaginatedResponse(
+                data=[],
+                pagination=OffsetPagination(
+                    total_count=0, items_per_page=10, page=1, has_more=False
+                ),
+                pagination_type=PaginationType.CURSOR,  # type: ignore[arg-type]
+            )
+
+    def test_filter_attributes_defaults_to_none(self):
+        """filter_attributes defaults to None."""
+        response = OffsetPaginatedResponse(
+            data=[],
+            pagination=OffsetPagination(
+                total_count=0, items_per_page=10, page=1, has_more=False
+            ),
+        )
+        assert response.filter_attributes is None
+
+    def test_full_serialization(self):
+        """Full JSON serialization includes all expected fields."""
+        response = OffsetPaginatedResponse(
+            data=[{"id": 1}],
+            pagination=OffsetPagination(
+                total_count=1, items_per_page=10, page=1, has_more=False
+            ),
+            filter_attributes={"status": ["active"]},
+        )
+        data = response.model_dump(mode="json")
+
+        assert data["pagination_type"] == "offset"
+        assert data["status"] == "SUCCESS"
+        assert data["data"] == [{"id": 1}]
+        assert data["pagination"]["total_count"] == 1
+        assert data["filter_attributes"] == {"status": ["active"]}
+
+
+class TestCursorPaginatedResponse:
+    """Tests for CursorPaginatedResponse schema."""
+
+    def test_pagination_type_is_cursor(self):
+        """pagination_type is always PaginationType.CURSOR."""
+        response = CursorPaginatedResponse(
+            data=[],
+            pagination=CursorPagination(
+                next_cursor=None, items_per_page=10, has_more=False
+            ),
+        )
+        assert response.pagination_type is PaginationType.CURSOR
+
+    def test_pagination_type_serializes_to_string(self):
+        """pagination_type serializes to 'cursor' in JSON mode."""
+        response = CursorPaginatedResponse(
+            data=[],
+            pagination=CursorPagination(
+                next_cursor=None, items_per_page=10, has_more=False
+            ),
+        )
+        assert response.model_dump(mode="json")["pagination_type"] == "cursor"
+
+    def test_pagination_field_is_typed(self):
+        """pagination field is CursorPagination, not the union."""
+        response = CursorPaginatedResponse(
+            data=[{"id": 1}],
+            pagination=CursorPagination(
+                next_cursor="abc123",
+                prev_cursor=None,
+                items_per_page=20,
+                has_more=True,
+            ),
+        )
+        assert isinstance(response.pagination, CursorPagination)
+        assert response.pagination.next_cursor == "abc123"
+        assert response.pagination.has_more is True
+
+    def test_is_subclass_of_paginated_response(self):
+        """CursorPaginatedResponse IS a PaginatedResponse."""
+        response = CursorPaginatedResponse(
+            data=[],
+            pagination=CursorPagination(
+                next_cursor=None, items_per_page=10, has_more=False
+            ),
+        )
+        assert isinstance(response, PaginatedResponse)
+
+    def test_pagination_type_default_cannot_be_overridden_to_offset(self):
+        """pagination_type rejects values other than CURSOR."""
+        with pytest.raises(ValidationError):
+            CursorPaginatedResponse(
+                data=[],
+                pagination=CursorPagination(
+                    next_cursor=None, items_per_page=10, has_more=False
+                ),
+                pagination_type=PaginationType.OFFSET,  # type: ignore[arg-type]
+            )
+
+    def test_full_serialization(self):
+        """Full JSON serialization includes all expected fields."""
+        response = CursorPaginatedResponse(
+            data=[{"id": 1}],
+            pagination=CursorPagination(
+                next_cursor="tok_next",
+                prev_cursor="tok_prev",
+                items_per_page=10,
+                has_more=True,
+            ),
+        )
+        data = response.model_dump(mode="json")
+
+        assert data["pagination_type"] == "cursor"
+        assert data["status"] == "SUCCESS"
+        assert data["pagination"]["next_cursor"] == "tok_next"
+        assert data["pagination"]["prev_cursor"] == "tok_prev"
 
 
 class TestFromAttributes:

uv.lock

@@ -113,101 +113,101 @@ wheels = [
 
 [[package]]
 name = "coverage"
-version = "7.13.4"
+version = "7.13.5"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/24/56/95b7e30fa389756cb56630faa728da46a27b8c6eb46f9d557c68fff12b65/coverage-7.13.4.tar.gz", hash = "sha256:e5c8f6ed1e61a8b2dcdf31eb0b9bbf0130750ca79c1c49eb898e2ad86f5ccc91", size = 827239, upload-time = "2026-02-09T12:59:03.86Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/9d/e0/70553e3000e345daff267cec284ce4cbf3fc141b6da229ac52775b5428f1/coverage-7.13.5.tar.gz", hash = "sha256:c81f6515c4c40141f83f502b07bbfa5c240ba25bbe73da7b33f1e5b6120ff179", size = 915967, upload-time = "2026-03-17T10:33:18.341Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/b4/ad/b59e5b451cf7172b8d1043dc0fa718f23aab379bc1521ee13d4bd9bfa960/coverage-7.13.4-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:d490ba50c3f35dd7c17953c68f3270e7ccd1c6642e2d2afe2d8e720b98f5a053", size = 219278, upload-time = "2026-02-09T12:56:31.673Z" },
+    { url = "https://files.pythonhosted.org/packages/4b/37/d24c8f8220ff07b839b2c043ea4903a33b0f455abe673ae3c03bbdb7f212/coverage-7.13.5-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:66a80c616f80181f4d643b0f9e709d97bcea413ecd9631e1dedc7401c8e6695d", size = 219381, upload-time = "2026-03-17T10:30:14.68Z" },
-    { url = "https://files.pythonhosted.org/packages/f1/17/0cb7ca3de72e5f4ef2ec2fa0089beafbcaaaead1844e8b8a63d35173d77d/coverage-7.13.4-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:19bc3c88078789f8ef36acb014d7241961dbf883fd2533d18cb1e7a5b4e28b11", size = 219783, upload-time = "2026-02-09T12:56:33.104Z" },
+    { url = "https://files.pythonhosted.org/packages/35/8b/cd129b0ca4afe886a6ce9d183c44d8301acbd4ef248622e7c49a23145605/coverage-7.13.5-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:145ede53ccbafb297c1c9287f788d1bc3efd6c900da23bf6931b09eafc931587", size = 219880, upload-time = "2026-03-17T10:30:16.231Z" },
-    { url = "https://files.pythonhosted.org/packages/ab/63/325d8e5b11e0eaf6d0f6a44fad444ae58820929a9b0de943fa377fe73e85/coverage-7.13.4-cp311-cp311-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:3998e5a32e62fdf410c0dbd3115df86297995d6e3429af80b8798aad894ca7aa", size = 250200, upload-time = "2026-02-09T12:56:34.474Z" },
+    { url = "https://files.pythonhosted.org/packages/55/2f/e0e5b237bffdb5d6c530ce87cc1d413a5b7d7dfd60fb067ad6d254c35c76/coverage-7.13.5-cp311-cp311-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:0672854dc733c342fa3e957e0605256d2bf5934feeac328da9e0b5449634a642", size = 250303, upload-time = "2026-03-17T10:30:17.748Z" },
-    { url = "https://files.pythonhosted.org/packages/76/53/c16972708cbb79f2942922571a687c52bd109a7bd51175aeb7558dff2236/coverage-7.13.4-cp311-cp311-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:8e264226ec98e01a8e1054314af91ee6cde0eacac4f465cc93b03dbe0bce2fd7", size = 252114, upload-time = "2026-02-09T12:56:35.749Z" },
+    { url = "https://files.pythonhosted.org/packages/92/be/b1afb692be85b947f3401375851484496134c5554e67e822c35f28bf2fbc/coverage-7.13.5-cp311-cp311-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:ec10e2a42b41c923c2209b846126c6582db5e43a33157e9870ba9fb70dc7854b", size = 252218, upload-time = "2026-03-17T10:30:19.804Z" },
-    { url = "https://files.pythonhosted.org/packages/eb/c2/7ab36d8b8cc412bec9ea2d07c83c48930eb4ba649634ba00cb7e4e0f9017/coverage-7.13.4-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:a3aa4e7b9e416774b21797365b358a6e827ffadaaca81b69ee02946852449f00", size = 254220, upload-time = "2026-02-09T12:56:37.796Z" },
+    { url = "https://files.pythonhosted.org/packages/da/69/2f47bb6fa1b8d1e3e5d0c4be8ccb4313c63d742476a619418f85740d597b/coverage-7.13.5-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:be3d4bbad9d4b037791794ddeedd7d64a56f5933a2c1373e18e9e568b9141686", size = 254326, upload-time = "2026-03-17T10:30:21.321Z" },
-    { url = "https://files.pythonhosted.org/packages/d6/4d/cf52c9a3322c89a0e6febdfbc83bb45c0ed3c64ad14081b9503adee702e7/coverage-7.13.4-cp311-cp311-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:71ca20079dd8f27fcf808817e281e90220475cd75115162218d0e27549f95fef", size = 256164, upload-time = "2026-02-09T12:56:39.016Z" },
+    { url = "https://files.pythonhosted.org/packages/d5/d0/79db81da58965bd29dabc8f4ad2a2af70611a57cba9d1ec006f072f30a54/coverage-7.13.5-cp311-cp311-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:4d2afbc5cc54d286bfb54541aa50b64cdb07a718227168c87b9e2fb8f25e1743", size = 256267, upload-time = "2026-03-17T10:30:23.094Z" },
-    { url = "https://files.pythonhosted.org/packages/78/e9/eb1dd17bd6de8289df3580e967e78294f352a5df8a57ff4671ee5fc3dcd0/coverage-7.13.4-cp311-cp311-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:e2f25215f1a359ab17320b47bcdaca3e6e6356652e8256f2441e4ef972052903", size = 250325, upload-time = "2026-02-09T12:56:40.668Z" },
+    { url = "https://files.pythonhosted.org/packages/e5/32/d0d7cc8168f91ddab44c0ce4806b969df5f5fdfdbb568eaca2dbc2a04936/coverage-7.13.5-cp311-cp311-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:3ad050321264c49c2fa67bb599100456fc51d004b82534f379d16445da40fb75", size = 250430, upload-time = "2026-03-17T10:30:25.311Z" },
-    { url = "https://files.pythonhosted.org/packages/71/07/8c1542aa873728f72267c07278c5cc0ec91356daf974df21335ccdb46368/coverage-7.13.4-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:d65b2d373032411e86960604dc4edac91fdfb5dca539461cf2cbe78327d1e64f", size = 251913, upload-time = "2026-02-09T12:56:41.97Z" },
+    { url = "https://files.pythonhosted.org/packages/4d/06/a055311d891ddbe231cd69fdd20ea4be6e3603ffebddf8704b8ca8e10a3c/coverage-7.13.5-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:7300c8a6d13335b29bb76d7651c66af6bd8658517c43499f110ddc6717bfc209", size = 252017, upload-time = "2026-03-17T10:30:27.284Z" },
-    { url = "https://files.pythonhosted.org/packages/74/d7/c62e2c5e4483a748e27868e4c32ad3daa9bdddbba58e1bc7a15e252baa74/coverage-7.13.4-cp311-cp311-musllinux_1_2_i686.whl", hash = "sha256:94eb63f9b363180aff17de3e7c8760c3ba94664ea2695c52f10111244d16a299", size = 249974, upload-time = "2026-02-09T12:56:43.323Z" },
+    { url = "https://files.pythonhosted.org/packages/d6/f6/d0fd2d21e29a657b5f77a2fe7082e1568158340dceb941954f776dce1b7b/coverage-7.13.5-cp311-cp311-musllinux_1_2_i686.whl", hash = "sha256:eb07647a5738b89baab047f14edd18ded523de60f3b30e75c2acc826f79c839a", size = 250080, upload-time = "2026-03-17T10:30:29.481Z" },
-    { url = "https://files.pythonhosted.org/packages/98/9f/4c5c015a6e98ced54efd0f5cf8d31b88e5504ecb6857585fc0161bb1e600/coverage-7.13.4-cp311-cp311-musllinux_1_2_ppc64le.whl", hash = "sha256:e856bf6616714c3a9fbc270ab54103f4e685ba236fa98c054e8f87f266c93505", size = 253741, upload-time = "2026-02-09T12:56:45.155Z" },
+    { url = "https://files.pythonhosted.org/packages/4e/ab/0d7fb2efc2e9a5eb7ddcc6e722f834a69b454b7e6e5888c3a8567ecffb31/coverage-7.13.5-cp311-cp311-musllinux_1_2_ppc64le.whl", hash = "sha256:9adb6688e3b53adffefd4a52d72cbd8b02602bfb8f74dcd862337182fd4d1a4e", size = 253843, upload-time = "2026-03-17T10:30:31.301Z" },
-    { url = "https://files.pythonhosted.org/packages/bd/59/0f4eef89b9f0fcd9633b5d350016f54126ab49426a70ff4c4e87446cabdc/coverage-7.13.4-cp311-cp311-musllinux_1_2_riscv64.whl", hash = "sha256:65dfcbe305c3dfe658492df2d85259e0d79ead4177f9ae724b6fb245198f55d6", size = 249695, upload-time = "2026-02-09T12:56:46.636Z" },
+    { url = "https://files.pythonhosted.org/packages/ba/6f/7467b917bbf5408610178f62a49c0ed4377bb16c1657f689cc61470da8ce/coverage-7.13.5-cp311-cp311-musllinux_1_2_riscv64.whl", hash = "sha256:7c8d4bc913dd70b93488d6c496c77f3aff5ea99a07e36a18f865bca55adef8bd", size = 249802, upload-time = "2026-03-17T10:30:33.358Z" },
-    { url = "https://files.pythonhosted.org/packages/b5/2c/b7476f938deb07166f3eb281a385c262675d688ff4659ad56c6c6b8e2e70/coverage-7.13.4-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:b507778ae8a4c915436ed5c2e05b4a6cecfa70f734e19c22a005152a11c7b6a9", size = 250599, upload-time = "2026-02-09T12:56:48.13Z" },
+    { url = "https://files.pythonhosted.org/packages/75/2c/1172fb689df92135f5bfbbd69fc83017a76d24ea2e2f3a1154007e2fb9f8/coverage-7.13.5-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:0e3c426ffc4cd952f54ee9ffbdd10345709ecc78a3ecfd796a57236bfad0b9b8", size = 250707, upload-time = "2026-03-17T10:30:35.2Z" },
-    { url = "https://files.pythonhosted.org/packages/b8/34/c3420709d9846ee3785b9f2831b4d94f276f38884032dca1457fa83f7476/coverage-7.13.4-cp311-cp311-win32.whl", hash = "sha256:784fc3cf8be001197b652d51d3fd259b1e2262888693a4636e18879f613a62a9", size = 221780, upload-time = "2026-02-09T12:56:50.479Z" },
+    { url = "https://files.pythonhosted.org/packages/67/21/9ac389377380a07884e3b48ba7a620fcd9dbfaf1d40565facdc6b36ec9ef/coverage-7.13.5-cp311-cp311-win32.whl", hash = "sha256:259b69bb83ad9894c4b25be2528139eecba9a82646ebdda2d9db1ba28424a6bf", size = 221880, upload-time = "2026-03-17T10:30:36.775Z" },
-    { url = "https://files.pythonhosted.org/packages/61/08/3d9c8613079d2b11c185b865de9a4c1a68850cfda2b357fae365cf609f29/coverage-7.13.4-cp311-cp311-win_amd64.whl", hash = "sha256:2421d591f8ca05b308cf0092807308b2facbefe54af7c02ac22548b88b95c98f", size = 222715, upload-time = "2026-02-09T12:56:51.815Z" },
+    { url = "https://files.pythonhosted.org/packages/af/7f/4cd8a92531253f9d7c1bbecd9fa1b472907fb54446ca768c59b531248dc5/coverage-7.13.5-cp311-cp311-win_amd64.whl", hash = "sha256:258354455f4e86e3e9d0d17571d522e13b4e1e19bf0f8596bcf9476d61e7d8a9", size = 222816, upload-time = "2026-03-17T10:30:38.891Z" },
-    { url = "https://files.pythonhosted.org/packages/18/1a/54c3c80b2f056164cc0a6cdcb040733760c7c4be9d780fe655f356f433e4/coverage-7.13.4-cp311-cp311-win_arm64.whl", hash = "sha256:79e73a76b854d9c6088fe5d8b2ebe745f8681c55f7397c3c0a016192d681045f", size = 221385, upload-time = "2026-02-09T12:56:53.194Z" },
+    { url = "https://files.pythonhosted.org/packages/12/a6/1d3f6155fb0010ca68eba7fe48ca6c9da7385058b77a95848710ecf189b1/coverage-7.13.5-cp311-cp311-win_arm64.whl", hash = "sha256:bff95879c33ec8da99fc9b6fe345ddb5be6414b41d6d1ad1c8f188d26f36e028", size = 221483, upload-time = "2026-03-17T10:30:40.463Z" },
-    { url = "https://files.pythonhosted.org/packages/d1/81/4ce2fdd909c5a0ed1f6dedb88aa57ab79b6d1fbd9b588c1ac7ef45659566/coverage-7.13.4-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:02231499b08dabbe2b96612993e5fc34217cdae907a51b906ac7fca8027a4459", size = 219449, upload-time = "2026-02-09T12:56:54.889Z" },
+    { url = "https://files.pythonhosted.org/packages/a0/c3/a396306ba7db865bf96fc1fb3b7fd29bcbf3d829df642e77b13555163cd6/coverage-7.13.5-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:460cf0114c5016fa841214ff5564aa4864f11948da9440bc97e21ad1f4ba1e01", size = 219554, upload-time = "2026-03-17T10:30:42.208Z" },
-    { url = "https://files.pythonhosted.org/packages/5d/96/5238b1efc5922ddbdc9b0db9243152c09777804fb7c02ad1741eb18a11c0/coverage-7.13.4-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:40aa8808140e55dc022b15d8aa7f651b6b3d68b365ea0398f1441e0b04d859c3", size = 219810, upload-time = "2026-02-09T12:56:56.33Z" },
+    { url = "https://files.pythonhosted.org/packages/a6/16/a68a19e5384e93f811dccc51034b1fd0b865841c390e3c931dcc4699e035/coverage-7.13.5-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:0e223ce4b4ed47f065bfb123687686512e37629be25cc63728557ae7db261422", size = 219908, upload-time = "2026-03-17T10:30:43.906Z" },
-    { url = "https://files.pythonhosted.org/packages/78/72/2f372b726d433c9c35e56377cf1d513b4c16fe51841060d826b95caacec1/coverage-7.13.4-cp312-cp312-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:5b856a8ccf749480024ff3bd7310adaef57bf31fd17e1bfc404b7940b6986634", size = 251308, upload-time = "2026-02-09T12:56:57.858Z" },
+    { url = "https://files.pythonhosted.org/packages/29/72/20b917c6793af3a5ceb7fb9c50033f3ec7865f2911a1416b34a7cfa0813b/coverage-7.13.5-cp312-cp312-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:6e3370441f4513c6252bf042b9c36d22491142385049243253c7e48398a15a9f", size = 251419, upload-time = "2026-03-17T10:30:45.545Z" },
-    { url = "https://files.pythonhosted.org/packages/5d/a0/2ea570925524ef4e00bb6c82649f5682a77fac5ab910a65c9284de422600/coverage-7.13.4-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:2c048ea43875fbf8b45d476ad79f179809c590ec7b79e2035c662e7afa3192e3", size = 254052, upload-time = "2026-02-09T12:56:59.754Z" },
+    { url = "https://files.pythonhosted.org/packages/8c/49/cd14b789536ac6a4778c453c6a2338bc0a2fb60c5a5a41b4008328b9acc1/coverage-7.13.5-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:03ccc709a17a1de074fb1d11f217342fb0d2b1582ed544f554fc9fc3f07e95f5", size = 254159, upload-time = "2026-03-17T10:30:47.204Z" },
-    { url = "https://files.pythonhosted.org/packages/e8/ac/45dc2e19a1939098d783c846e130b8f862fbb50d09e0af663988f2f21973/coverage-7.13.4-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:b7b38448866e83176e28086674fe7368ab8590e4610fb662b44e345b86d63ffa", size = 255165, upload-time = "2026-02-09T12:57:01.287Z" },
+    { url = "https://files.pythonhosted.org/packages/9d/00/7b0edcfe64e2ed4c0340dac14a52ad0f4c9bd0b8b5e531af7d55b703db7c/coverage-7.13.5-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:3f4818d065964db3c1c66dc0fbdac5ac692ecbc875555e13374fdbe7eedb4376", size = 255270, upload-time = "2026-03-17T10:30:48.812Z" },
-    { url = "https://files.pythonhosted.org/packages/2d/4d/26d236ff35abc3b5e63540d3386e4c3b192168c1d96da5cb2f43c640970f/coverage-7.13.4-cp312-cp312-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:de6defc1c9badbf8b9e67ae90fd00519186d6ab64e5cc5f3d21359c2a9b2c1d3", size = 257432, upload-time = "2026-02-09T12:57:02.637Z" },
+    { url = "https://files.pythonhosted.org/packages/93/89/7ffc4ba0f5d0a55c1e84ea7cee39c9fc06af7b170513d83fbf3bbefce280/coverage-7.13.5-cp312-cp312-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:012d5319e66e9d5a218834642d6c35d265515a62f01157a45bcc036ecf947256", size = 257538, upload-time = "2026-03-17T10:30:50.77Z" },
-    { url = "https://files.pythonhosted.org/packages/ec/55/14a966c757d1348b2e19caf699415a2a4c4f7feaa4bbc6326a51f5c7dd1b/coverage-7.13.4-cp312-cp312-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:7eda778067ad7ffccd23ecffce537dface96212576a07924cbf0d8799d2ded5a", size = 251716, upload-time = "2026-02-09T12:57:04.056Z" },
+    { url = "https://files.pythonhosted.org/packages/81/bd/73ddf85f93f7e6fa83e77ccecb6162d9415c79007b4bc124008a4995e4a7/coverage-7.13.5-cp312-cp312-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:8dd02af98971bdb956363e4827d34425cb3df19ee550ef92855b0acb9c7ce51c", size = 251821, upload-time = "2026-03-17T10:30:52.5Z" },
-    { url = "https://files.pythonhosted.org/packages/77/33/50116647905837c66d28b2af1321b845d5f5d19be9655cb84d4a0ea806b4/coverage-7.13.4-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:e87f6c587c3f34356c3759f0420693e35e7eb0e2e41e4c011cb6ec6ecbbf1db7", size = 253089, upload-time = "2026-02-09T12:57:05.503Z" },
+    { url = "https://files.pythonhosted.org/packages/a0/81/278aff4e8dec4926a0bcb9486320752811f543a3ce5b602cc7a29978d073/coverage-7.13.5-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:f08fd75c50a760c7eb068ae823777268daaf16a80b918fa58eea888f8e3919f5", size = 253191, upload-time = "2026-03-17T10:30:54.543Z" },
-    { url = "https://files.pythonhosted.org/packages/c2/b4/8efb11a46e3665d92635a56e4f2d4529de6d33f2cb38afd47d779d15fc99/coverage-7.13.4-cp312-cp312-musllinux_1_2_i686.whl", hash = "sha256:8248977c2e33aecb2ced42fef99f2d319e9904a36e55a8a68b69207fb7e43edc", size = 251232, upload-time = "2026-02-09T12:57:06.879Z" },
+    { url = "https://files.pythonhosted.org/packages/70/ee/fe1621488e2e0a58d7e94c4800f0d96f79671553488d401a612bebae324b/coverage-7.13.5-cp312-cp312-musllinux_1_2_i686.whl", hash = "sha256:843ea8643cf967d1ac7e8ecd4bb00c99135adf4816c0c0593fdcc47b597fcf09", size = 251337, upload-time = "2026-03-17T10:30:56.663Z" },
-    { url = "https://files.pythonhosted.org/packages/51/24/8cd73dd399b812cc76bb0ac260e671c4163093441847ffe058ac9fda1e32/coverage-7.13.4-cp312-cp312-musllinux_1_2_ppc64le.whl", hash = "sha256:25381386e80ae727608e662474db537d4df1ecd42379b5ba33c84633a2b36d47", size = 255299, upload-time = "2026-02-09T12:57:08.245Z" },
+    { url = "https://files.pythonhosted.org/packages/37/a6/f79fb37aa104b562207cc23cb5711ab6793608e246cae1e93f26b2236ed9/coverage-7.13.5-cp312-cp312-musllinux_1_2_ppc64le.whl", hash = "sha256:9d44d7aa963820b1b971dbecd90bfe5fe8f81cff79787eb6cca15750bd2f79b9", size = 255404, upload-time = "2026-03-17T10:30:58.427Z" },
-    { url = "https://files.pythonhosted.org/packages/03/94/0a4b12f1d0e029ce1ccc1c800944a9984cbe7d678e470bb6d3c6bc38a0da/coverage-7.13.4-cp312-cp312-musllinux_1_2_riscv64.whl", hash = "sha256:ee756f00726693e5ba94d6df2bdfd64d4852d23b09bb0bc700e3b30e6f333985", size = 250796, upload-time = "2026-02-09T12:57:10.142Z" },
+    { url = "https://files.pythonhosted.org/packages/75/f0/ed15262a58ec81ce457ceb717b7f78752a1713556b19081b76e90896e8d4/coverage-7.13.5-cp312-cp312-musllinux_1_2_riscv64.whl", hash = "sha256:7132bed4bd7b836200c591410ae7d97bf7ae8be6fc87d160b2bd881df929e7bf", size = 250903, upload-time = "2026-03-17T10:31:00.093Z" },
-    { url = "https://files.pythonhosted.org/packages/73/44/6002fbf88f6698ca034360ce474c406be6d5a985b3fdb3401128031eef6b/coverage-7.13.4-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:fdfc1e28e7c7cdce44985b3043bc13bbd9c747520f94a4d7164af8260b3d91f0", size = 252673, upload-time = "2026-02-09T12:57:12.197Z" },
+    { url = "https://files.pythonhosted.org/packages/0f/e9/9129958f20e7e9d4d56d51d42ccf708d15cac355ff4ac6e736e97a9393d2/coverage-7.13.5-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:a698e363641b98843c517817db75373c83254781426e94ada3197cabbc2c919c", size = 252780, upload-time = "2026-03-17T10:31:01.916Z" },
-    { url = "https://files.pythonhosted.org/packages/de/c6/a0279f7c00e786be75a749a5674e6fa267bcbd8209cd10c9a450c655dfa7/coverage-7.13.4-cp312-cp312-win32.whl", hash = "sha256:01d4cbc3c283a17fc1e42d614a119f7f438eabb593391283adca8dc86eff1246", size = 221990, upload-time = "2026-02-09T12:57:14.085Z" },
+    { url = "https://files.pythonhosted.org/packages/a4/d7/0ad9b15812d81272db94379fe4c6df8fd17781cc7671fdfa30c76ba5ff7b/coverage-7.13.5-cp312-cp312-win32.whl", hash = "sha256:bdba0a6b8812e8c7df002d908a9a2ea3c36e92611b5708633c50869e6d922fdf", size = 222093, upload-time = "2026-03-17T10:31:03.642Z" },
-    { url = "https://files.pythonhosted.org/packages/77/4e/c0a25a425fcf5557d9abd18419c95b63922e897bc86c1f327f155ef234a9/coverage-7.13.4-cp312-cp312-win_amd64.whl", hash = "sha256:9401ebc7ef522f01d01d45532c68c5ac40fb27113019b6b7d8b208f6e9baa126", size = 222800, upload-time = "2026-02-09T12:57:15.944Z" },
+    { url = "https://files.pythonhosted.org/packages/29/3d/821a9a5799fac2556bcf0bd37a70d1d11fa9e49784b6d22e92e8b2f85f18/coverage-7.13.5-cp312-cp312-win_amd64.whl", hash = "sha256:d2c87e0c473a10bffe991502eac389220533024c8082ec1ce849f4218dded810", size = 222900, upload-time = "2026-03-17T10:31:05.651Z" },
-    { url = "https://files.pythonhosted.org/packages/47/ac/92da44ad9a6f4e3a7debd178949d6f3769bedca33830ce9b1dcdab589a37/coverage-7.13.4-cp312-cp312-win_arm64.whl", hash = "sha256:b1ec7b6b6e93255f952e27ab58fbc68dcc468844b16ecbee881aeb29b6ab4d8d", size = 221415, upload-time = "2026-02-09T12:57:17.497Z" },
+    { url = "https://files.pythonhosted.org/packages/d4/fa/2238c2ad08e35cf4f020ea721f717e09ec3152aea75d191a7faf3ef009a8/coverage-7.13.5-cp312-cp312-win_arm64.whl", hash = "sha256:bf69236a9a81bdca3bff53796237aab096cdbf8d78a66ad61e992d9dac7eb2de", size = 221515, upload-time = "2026-03-17T10:31:07.293Z" },
-    { url = "https://files.pythonhosted.org/packages/db/23/aad45061a31677d68e47499197a131eea55da4875d16c1f42021ab963503/coverage-7.13.4-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:b66a2da594b6068b48b2692f043f35d4d3693fb639d5ea8b39533c2ad9ac3ab9", size = 219474, upload-time = "2026-02-09T12:57:19.332Z" },
+    { url = "https://files.pythonhosted.org/packages/74/8c/74fedc9663dcf168b0a059d4ea756ecae4da77a489048f94b5f512a8d0b3/coverage-7.13.5-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:5ec4af212df513e399cf11610cc27063f1586419e814755ab362e50a85ea69c1", size = 219576, upload-time = "2026-03-17T10:31:09.045Z" },
-    { url = "https://files.pythonhosted.org/packages/a5/70/9b8b67a0945f3dfec1fd896c5cefb7c19d5a3a6d74630b99a895170999ae/coverage-7.13.4-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:3599eb3992d814d23b35c536c28df1a882caa950f8f507cef23d1cbf334995ac", size = 219844, upload-time = "2026-02-09T12:57:20.66Z" },
+    { url = "https://files.pythonhosted.org/packages/0c/c9/44fb661c55062f0818a6ffd2685c67aa30816200d5f2817543717d4b92eb/coverage-7.13.5-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:941617e518602e2d64942c88ec8499f7fbd49d3f6c4327d3a71d43a1973032f3", size = 219942, upload-time = "2026-03-17T10:31:10.708Z" },
-    { url = "https://files.pythonhosted.org/packages/97/fd/7e859f8fab324cef6c4ad7cff156ca7c489fef9179d5749b0c8d321281c2/coverage-7.13.4-cp313-cp313-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:93550784d9281e374fb5a12bf1324cc8a963fd63b2d2f223503ef0fd4aa339ea", size = 250832, upload-time = "2026-02-09T12:57:22.007Z" },
+    { url = "https://files.pythonhosted.org/packages/5f/13/93419671cee82b780bab7ea96b67c8ef448f5f295f36bf5031154ec9a790/coverage-7.13.5-cp313-cp313-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:da305e9937617ee95c2e39d8ff9f040e0487cbf1ac174f777ed5eddd7a7c1f26", size = 250935, upload-time = "2026-03-17T10:31:12.392Z" },
-    { url = "https://files.pythonhosted.org/packages/e4/dc/b2442d10020c2f52617828862d8b6ee337859cd8f3a1f13d607dddda9cf7/coverage-7.13.4-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:b720ce6a88a2755f7c697c23268ddc47a571b88052e6b155224347389fdf6a3b", size = 253434, upload-time = "2026-02-09T12:57:23.339Z" },
+    { url = "https://files.pythonhosted.org/packages/ac/68/1666e3a4462f8202d836920114fa7a5ee9275d1fa45366d336c551a162dd/coverage-7.13.5-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:78e696e1cc714e57e8b25760b33a8b1026b7048d270140d25dafe1b0a1ee05a3", size = 253541, upload-time = "2026-03-17T10:31:14.247Z" },
-    { url = "https://files.pythonhosted.org/packages/5a/88/6728a7ad17428b18d836540630487231f5470fb82454871149502f5e5aa2/coverage-7.13.4-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:7b322db1284a2ed3aa28ffd8ebe3db91c929b7a333c0820abec3d838ef5b3525", size = 254676, upload-time = "2026-02-09T12:57:24.774Z" },
+    { url = "https://files.pythonhosted.org/packages/4e/5e/3ee3b835647be646dcf3c65a7c6c18f87c27326a858f72ab22c12730773d/coverage-7.13.5-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:02ca0eed225b2ff301c474aeeeae27d26e2537942aa0f87491d3e147e784a82b", size = 254780, upload-time = "2026-03-17T10:31:16.193Z" },
-    { url = "https://files.pythonhosted.org/packages/7c/bc/21244b1b8cedf0dff0a2b53b208015fe798d5f2a8d5348dbfece04224fff/coverage-7.13.4-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:f4594c67d8a7c89cf922d9df0438c7c7bb022ad506eddb0fdb2863359ff78242", size = 256807, upload-time = "2026-02-09T12:57:26.125Z" },
+    { url = "https://files.pythonhosted.org/packages/44/b3/cb5bd1a04cfcc49ede6cd8409d80bee17661167686741e041abc7ee1b9a9/coverage-7.13.5-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:04690832cbea4e4663d9149e05dba142546ca05cb1848816760e7f58285c970a", size = 256912, upload-time = "2026-03-17T10:31:17.89Z" },
-    { url = "https://files.pythonhosted.org/packages/97/a0/ddba7ed3251cff51006737a727d84e05b61517d1784a9988a846ba508877/coverage-7.13.4-cp313-cp313-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:53d133df809c743eb8bce33b24bcababb371f4441340578cd406e084d94a6148", size = 251058, upload-time = "2026-02-09T12:57:27.614Z" },
+    { url = "https://files.pythonhosted.org/packages/1b/66/c1dceb7b9714473800b075f5c8a84f4588f887a90eb8645282031676e242/coverage-7.13.5-cp313-cp313-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:0590e44dd2745c696a778f7bab6aa95256de2cbc8b8cff4f7db8ff09813d6969", size = 251165, upload-time = "2026-03-17T10:31:19.605Z" },
-    { url = "https://files.pythonhosted.org/packages/9b/55/e289addf7ff54d3a540526f33751951bf0878f3809b47f6dfb3def69c6f7/coverage-7.13.4-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:76451d1978b95ba6507a039090ba076105c87cc76fc3efd5d35d72093964d49a", size = 252805, upload-time = "2026-02-09T12:57:29.066Z" },
+    { url = "https://files.pythonhosted.org/packages/b7/62/5502b73b97aa2e53ea22a39cf8649ff44827bef76d90bf638777daa27a9d/coverage-7.13.5-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:d7cfad2d6d81dd298ab6b89fe72c3b7b05ec7544bdda3b707ddaecff8d25c161", size = 252908, upload-time = "2026-03-17T10:31:21.312Z" },
-    { url = "https://files.pythonhosted.org/packages/13/4e/cc276b1fa4a59be56d96f1dabddbdc30f4ba22e3b1cd42504c37b3313255/coverage-7.13.4-cp313-cp313-musllinux_1_2_i686.whl", hash = "sha256:7f57b33491e281e962021de110b451ab8a24182589be17e12a22c79047935e23", size = 250766, upload-time = "2026-02-09T12:57:30.522Z" },
+    { url = "https://files.pythonhosted.org/packages/7d/37/7792c2d69854397ca77a55c4646e5897c467928b0e27f2d235d83b5d08c6/coverage-7.13.5-cp313-cp313-musllinux_1_2_i686.whl", hash = "sha256:e092b9499de38ae0fbfbc603a74660eb6ff3e869e507b50d85a13b6db9863e15", size = 250873, upload-time = "2026-03-17T10:31:23.565Z" },
-    { url = "https://files.pythonhosted.org/packages/94/44/1093b8f93018f8b41a8cf29636c9292502f05e4a113d4d107d14a3acd044/coverage-7.13.4-cp313-cp313-musllinux_1_2_ppc64le.whl", hash = "sha256:1731dc33dc276dafc410a885cbf5992f1ff171393e48a21453b78727d090de80", size = 254923, upload-time = "2026-02-09T12:57:31.946Z" },
+    { url = "https://files.pythonhosted.org/packages/a3/23/bc866fb6163be52a8a9e5d708ba0d3b1283c12158cefca0a8bbb6e247a43/coverage-7.13.5-cp313-cp313-musllinux_1_2_ppc64le.whl", hash = "sha256:48c39bc4a04d983a54a705a6389512883d4a3b9862991b3617d547940e9f52b1", size = 255030, upload-time = "2026-03-17T10:31:25.58Z" },
-    { url = "https://files.pythonhosted.org/packages/8b/55/ea2796da2d42257f37dbea1aab239ba9263b31bd91d5527cdd6db5efe174/coverage-7.13.4-cp313-cp313-musllinux_1_2_riscv64.whl", hash = "sha256:bd60d4fe2f6fa7dff9223ca1bbc9f05d2b6697bc5961072e5d3b952d46e1b1ea", size = 250591, upload-time = "2026-02-09T12:57:33.842Z" },
+    { url = "https://files.pythonhosted.org/packages/7d/8b/ef67e1c222ef49860701d346b8bbb70881bef283bd5f6cbba68a39a086c7/coverage-7.13.5-cp313-cp313-musllinux_1_2_riscv64.whl", hash = "sha256:2d3807015f138ffea1ed9afeeb8624fd781703f2858b62a8dd8da5a0994c57b6", size = 250694, upload-time = "2026-03-17T10:31:27.316Z" },
-    { url = "https://files.pythonhosted.org/packages/d4/fa/7c4bb72aacf8af5020675aa633e59c1fbe296d22aed191b6a5b711eb2bc7/coverage-7.13.4-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:9181a3ccead280b828fae232df12b16652702b49d41e99d657f46cc7b1f6ec7a", size = 252364, upload-time = "2026-02-09T12:57:35.743Z" },
+    { url = "https://files.pythonhosted.org/packages/46/0d/866d1f74f0acddbb906db212e096dee77a8e2158ca5e6bb44729f9d93298/coverage-7.13.5-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:ee2aa19e03161671ec964004fb74b2257805d9710bf14a5c704558b9d8dbaf17", size = 252469, upload-time = "2026-03-17T10:31:29.472Z" },
-    { url = "https://files.pythonhosted.org/packages/5c/38/a8d2ec0146479c20bbaa7181b5b455a0c41101eed57f10dd19a78ab44c80/coverage-7.13.4-cp313-cp313-win32.whl", hash = "sha256:f53d492307962561ac7de4cd1de3e363589b000ab69617c6156a16ba7237998d", size = 222010, upload-time = "2026-02-09T12:57:37.25Z" },
+    { url = "https://files.pythonhosted.org/packages/7a/f5/be742fec31118f02ce42b21c6af187ad6a344fed546b56ca60caacc6a9a0/coverage-7.13.5-cp313-cp313-win32.whl", hash = "sha256:ce1998c0483007608c8382f4ff50164bfc5bd07a2246dd272aa4043b75e61e85", size = 222112, upload-time = "2026-03-17T10:31:31.526Z" },
-    { url = "https://files.pythonhosted.org/packages/e2/0c/dbfafbe90a185943dcfbc766fe0e1909f658811492d79b741523a414a6cc/coverage-7.13.4-cp313-cp313-win_amd64.whl", hash = "sha256:e6f70dec1cc557e52df5306d051ef56003f74d56e9c4dd7ddb07e07ef32a84dd", size = 222818, upload-time = "2026-02-09T12:57:38.734Z" },
+    { url = "https://files.pythonhosted.org/packages/66/40/7732d648ab9d069a46e686043241f01206348e2bbf128daea85be4d6414b/coverage-7.13.5-cp313-cp313-win_amd64.whl", hash = "sha256:631efb83f01569670a5e866ceb80fe483e7c159fac6f167e6571522636104a0b", size = 222923, upload-time = "2026-03-17T10:31:33.633Z" },
-    { url = "https://files.pythonhosted.org/packages/04/d1/934918a138c932c90d78301f45f677fb05c39a3112b96fd2c8e60503cdc7/coverage-7.13.4-cp313-cp313-win_arm64.whl", hash = "sha256:fb07dc5da7e849e2ad31a5d74e9bece81f30ecf5a42909d0a695f8bd1874d6af", size = 221438, upload-time = "2026-02-09T12:57:40.223Z" },
+    { url = "https://files.pythonhosted.org/packages/48/af/fea819c12a095781f6ccd504890aaddaf88b8fab263c4940e82c7b770124/coverage-7.13.5-cp313-cp313-win_arm64.whl", hash = "sha256:f4cd16206ad171cbc2470dbea9103cf9a7607d5fe8c242fdf1edf36174020664", size = 221540, upload-time = "2026-03-17T10:31:35.445Z" },
-    { url = "https://files.pythonhosted.org/packages/52/57/ee93ced533bcb3e6df961c0c6e42da2fc6addae53fb95b94a89b1e33ebd7/coverage-7.13.4-cp313-cp313t-macosx_10_13_x86_64.whl", hash = "sha256:40d74da8e6c4b9ac18b15331c4b5ebc35a17069410cad462ad4f40dcd2d50c0d", size = 220165, upload-time = "2026-02-09T12:57:41.639Z" },
+    { url = "https://files.pythonhosted.org/packages/23/d2/17879af479df7fbbd44bd528a31692a48f6b25055d16482fdf5cdb633805/coverage-7.13.5-cp313-cp313t-macosx_10_13_x86_64.whl", hash = "sha256:0428cbef5783ad91fe240f673cc1f76b25e74bbfe1a13115e4aa30d3f538162d", size = 220262, upload-time = "2026-03-17T10:31:37.184Z" },
-    { url = "https://files.pythonhosted.org/packages/c5/e0/969fc285a6fbdda49d91af278488d904dcd7651b2693872f0ff94e40e84a/coverage-7.13.4-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:4223b4230a376138939a9173f1bdd6521994f2aff8047fae100d6d94d50c5a12", size = 220516, upload-time = "2026-02-09T12:57:44.215Z" },
+    { url = "https://files.pythonhosted.org/packages/5b/4c/d20e554f988c8f91d6a02c5118f9abbbf73a8768a3048cb4962230d5743f/coverage-7.13.5-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:e0b216a19534b2427cc201a26c25da4a48633f29a487c61258643e89d28200c0", size = 220617, upload-time = "2026-03-17T10:31:39.245Z" },
-    { url = "https://files.pythonhosted.org/packages/b1/b8/9531944e16267e2735a30a9641ff49671f07e8138ecf1ca13db9fd2560c7/coverage-7.13.4-cp313-cp313t-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:1d4be36a5114c499f9f1f9195e95ebf979460dbe2d88e6816ea202010ba1c34b", size = 261804, upload-time = "2026-02-09T12:57:45.989Z" },
+    { url = "https://files.pythonhosted.org/packages/29/9c/f9f5277b95184f764b24e7231e166dfdb5780a46d408a2ac665969416d61/coverage-7.13.5-cp313-cp313t-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:972a9cd27894afe4bc2b1480107054e062df08e671df7c2f18c205e805ccd806", size = 261912, upload-time = "2026-03-17T10:31:41.324Z" },
-    { url = "https://files.pythonhosted.org/packages/8a/f3/e63df6d500314a2a60390d1989240d5f27318a7a68fa30ad3806e2a9323e/coverage-7.13.4-cp313-cp313t-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:200dea7d1e8095cc6e98cdabe3fd1d21ab17d3cee6dab00cadbb2fe35d9c15b9", size = 263885, upload-time = "2026-02-09T12:57:47.42Z" },
+    { url = "https://files.pythonhosted.org/packages/d5/f6/7f1ab39393eeb50cfe4747ae8ef0e4fc564b989225aa1152e13a180d74f8/coverage-7.13.5-cp313-cp313t-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:4b59148601efcd2bac8c4dbf1f0ad6391693ccf7a74b8205781751637076aee3", size = 263987, upload-time = "2026-03-17T10:31:43.724Z" },
-    { url = "https://files.pythonhosted.org/packages/f3/67/7654810de580e14b37670b60a09c599fa348e48312db5b216d730857ffe6/coverage-7.13.4-cp313-cp313t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:b8eb931ee8e6d8243e253e5ed7336deea6904369d2fd8ae6e43f68abbf167092", size = 266308, upload-time = "2026-02-09T12:57:49.345Z" },
+    { url = "https://files.pythonhosted.org/packages/a0/d7/62c084fb489ed9c6fbdf57e006752e7c516ea46fd690e5ed8b8617c7d52e/coverage-7.13.5-cp313-cp313t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:505d7083c8b0c87a8fa8c07370c285847c1f77739b22e299ad75a6af6c32c5c9", size = 266416, upload-time = "2026-03-17T10:31:45.769Z" },
-    { url = "https://files.pythonhosted.org/packages/37/6f/39d41eca0eab3cc82115953ad41c4e77935286c930e8fad15eaed1389d83/coverage-7.13.4-cp313-cp313t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:75eab1ebe4f2f64d9509b984f9314d4aa788540368218b858dad56dc8f3e5eb9", size = 267452, upload-time = "2026-02-09T12:57:50.811Z" },
+    { url = "https://files.pythonhosted.org/packages/a9/f6/df63d8660e1a0bff6125947afda112a0502736f470d62ca68b288ea762d8/coverage-7.13.5-cp313-cp313t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:60365289c3741e4db327e7baff2a4aaacf22f788e80fa4683393891b70a89fbd", size = 267558, upload-time = "2026-03-17T10:31:48.293Z" },
-    { url = "https://files.pythonhosted.org/packages/50/6d/39c0fbb8fc5cd4d2090811e553c2108cf5112e882f82505ee7495349a6bf/coverage-7.13.4-cp313-cp313t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:c35eb28c1d085eb7d8c9b3296567a1bebe03ce72962e932431b9a61f28facf26", size = 261057, upload-time = "2026-02-09T12:57:52.447Z" },
+    { url = "https://files.pythonhosted.org/packages/5b/02/353ca81d36779bd108f6d384425f7139ac3c58c750dcfaafe5d0bee6436b/coverage-7.13.5-cp313-cp313t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:1b88c69c8ef5d4b6fe7dea66d6636056a0f6a7527c440e890cf9259011f5e606", size = 261163, upload-time = "2026-03-17T10:31:50.125Z" },
-    { url = "https://files.pythonhosted.org/packages/a4/a2/60010c669df5fa603bb5a97fb75407e191a846510da70ac657eb696b7fce/coverage-7.13.4-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:eb88b316ec33760714a4720feb2816a3a59180fd58c1985012054fa7aebee4c2", size = 263875, upload-time = "2026-02-09T12:57:53.938Z" },
+    { url = "https://files.pythonhosted.org/packages/2c/16/2e79106d5749bcaf3aee6d309123548e3276517cd7851faa8da213bc61bf/coverage-7.13.5-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:5b13955d31d1633cf9376908089b7cebe7d15ddad7aeaabcbe969a595a97e95e", size = 263981, upload-time = "2026-03-17T10:31:51.961Z" },
-    { url = "https://files.pythonhosted.org/packages/3e/d9/63b22a6bdbd17f1f96e9ed58604c2a6b0e72a9133e37d663bef185877cf6/coverage-7.13.4-cp313-cp313t-musllinux_1_2_i686.whl", hash = "sha256:7d41eead3cc673cbd38a4417deb7fd0b4ca26954ff7dc6078e33f6ff97bed940", size = 261500, upload-time = "2026-02-09T12:57:56.012Z" },
+    { url = "https://files.pythonhosted.org/packages/29/c7/c29e0c59ffa6942030ae6f50b88ae49988e7e8da06de7ecdbf49c6d4feae/coverage-7.13.5-cp313-cp313t-musllinux_1_2_i686.whl", hash = "sha256:f70c9ab2595c56f81a89620e22899eea8b212a4041bd728ac6f4a28bf5d3ddd0", size = 261604, upload-time = "2026-03-17T10:31:53.872Z" },
-    { url = "https://files.pythonhosted.org/packages/70/bf/69f86ba1ad85bc3ad240e4c0e57a2e620fbc0e1645a47b5c62f0e941ad7f/coverage-7.13.4-cp313-cp313t-musllinux_1_2_ppc64le.whl", hash = "sha256:fb26a934946a6afe0e326aebe0730cdff393a8bc0bbb65a2f41e30feddca399c", size = 265212, upload-time = "2026-02-09T12:57:57.5Z" },
+    { url = "https://files.pythonhosted.org/packages/40/48/097cdc3db342f34006a308ab41c3a7c11c3f0d84750d340f45d88a782e00/coverage-7.13.5-cp313-cp313t-musllinux_1_2_ppc64le.whl", hash = "sha256:084b84a8c63e8d6fc7e3931b316a9bcafca1458d753c539db82d31ed20091a87", size = 265321, upload-time = "2026-03-17T10:31:55.997Z" },
-    { url = "https://files.pythonhosted.org/packages/ae/f2/5f65a278a8c2148731831574c73e42f57204243d33bedaaf18fa79c5958f/coverage-7.13.4-cp313-cp313t-musllinux_1_2_riscv64.whl", hash = "sha256:dae88bc0fc77edaa65c14be099bd57ee140cf507e6bfdeea7938457ab387efb0", size = 260398, upload-time = "2026-02-09T12:57:59.027Z" },
+    { url = "https://files.pythonhosted.org/packages/bb/1f/4994af354689e14fd03a75f8ec85a9a68d94e0188bbdab3fc1516b55e512/coverage-7.13.5-cp313-cp313t-musllinux_1_2_riscv64.whl", hash = "sha256:ad14385487393e386e2ea988b09d62dd42c397662ac2dabc3832d71253eee479", size = 260502, upload-time = "2026-03-17T10:31:58.308Z" },
-    { url = "https://files.pythonhosted.org/packages/ef/80/6e8280a350ee9fea92f14b8357448a242dcaa243cb2c72ab0ca591f66c8c/coverage-7.13.4-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:845f352911777a8e722bfce168958214951e07e47e5d5d9744109fa5fe77f79b", size = 262584, upload-time = "2026-02-09T12:58:01.129Z" },
+    { url = "https://files.pythonhosted.org/packages/22/c6/9bb9ef55903e628033560885f5c31aa227e46878118b63ab15dc7ba87797/coverage-7.13.5-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:7f2c47b36fe7709a6e83bfadf4eefb90bd25fbe4014d715224c4316f808e59a2", size = 262688, upload-time = "2026-03-17T10:32:00.141Z" },
-    { url = "https://files.pythonhosted.org/packages/22/63/01ff182fc95f260b539590fb12c11ad3e21332c15f9799cb5e2386f71d9f/coverage-7.13.4-cp313-cp313t-win32.whl", hash = "sha256:2fa8d5f8de70688a28240de9e139fa16b153cc3cbb01c5f16d88d6505ebdadf9", size = 222688, upload-time = "2026-02-09T12:58:02.736Z" },
+    { url = "https://files.pythonhosted.org/packages/14/4f/f5df9007e50b15e53e01edea486814783a7f019893733d9e4d6caad75557/coverage-7.13.5-cp313-cp313t-win32.whl", hash = "sha256:67e9bc5449801fad0e5dff329499fb090ba4c5800b86805c80617b4e29809b2a", size = 222788, upload-time = "2026-03-17T10:32:02.246Z" },
-    { url = "https://files.pythonhosted.org/packages/a9/43/89de4ef5d3cd53b886afa114065f7e9d3707bdb3e5efae13535b46ae483d/coverage-7.13.4-cp313-cp313t-win_amd64.whl", hash = "sha256:9351229c8c8407645840edcc277f4a2d44814d1bc34a2128c11c2a031d45a5dd", size = 223746, upload-time = "2026-02-09T12:58:05.362Z" },
+    { url = "https://files.pythonhosted.org/packages/e1/98/aa7fccaa97d0f3192bec013c4e6fd6d294a6ed44b640e6bb61f479e00ed5/coverage-7.13.5-cp313-cp313t-win_amd64.whl", hash = "sha256:da86cdcf10d2519e10cabb8ac2de03da1bcb6e4853790b7fbd48523332e3a819", size = 223851, upload-time = "2026-03-17T10:32:04.416Z" },
-    { url = "https://files.pythonhosted.org/packages/35/39/7cf0aa9a10d470a5309b38b289b9bb07ddeac5d61af9b664fe9775a4cb3e/coverage-7.13.4-cp313-cp313t-win_arm64.whl", hash = "sha256:30b8d0512f2dc8c8747557e8fb459d6176a2c9e5731e2b74d311c03b78451997", size = 222003, upload-time = "2026-02-09T12:58:06.952Z" },
+    { url = "https://files.pythonhosted.org/packages/3d/8b/e5c469f7352651e5f013198e9e21f97510b23de957dd06a84071683b4b60/coverage-7.13.5-cp313-cp313t-win_arm64.whl", hash = "sha256:0ecf12ecb326fe2c339d93fc131816f3a7367d223db37817208905c89bded911", size = 222104, upload-time = "2026-03-17T10:32:06.65Z" },
-    { url = "https://files.pythonhosted.org/packages/92/11/a9cf762bb83386467737d32187756a42094927150c3e107df4cb078e8590/coverage-7.13.4-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:300deaee342f90696ed186e3a00c71b5b3d27bffe9e827677954f4ee56969601", size = 219522, upload-time = "2026-02-09T12:58:08.623Z" },
+    { url = "https://files.pythonhosted.org/packages/8e/77/39703f0d1d4b478bfd30191d3c14f53caf596fac00efb3f8f6ee23646439/coverage-7.13.5-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:fbabfaceaeb587e16f7008f7795cd80d20ec548dc7f94fbb0d4ec2e038ce563f", size = 219621, upload-time = "2026-03-17T10:32:08.589Z" },
-    { url = "https://files.pythonhosted.org/packages/d3/28/56e6d892b7b052236d67c95f1936b6a7cf7c3e2634bf27610b8cbd7f9c60/coverage-7.13.4-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:29e3220258d682b6226a9b0925bc563ed9a1ebcff3cad30f043eceea7eaf2689", size = 219855, upload-time = "2026-02-09T12:58:10.176Z" },
+    { url = "https://files.pythonhosted.org/packages/e2/3e/51dff36d99ae14639a133d9b164d63e628532e2974d8b1edb99dd1ebc733/coverage-7.13.5-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:9bb2a28101a443669a423b665939381084412b81c3f8c0fcfbac57f4e30b5b8e", size = 219953, upload-time = "2026-03-17T10:32:10.507Z" },
-    { url = "https://files.pythonhosted.org/packages/e5/69/233459ee9eb0c0d10fcc2fe425a029b3fa5ce0f040c966ebce851d030c70/coverage-7.13.4-cp314-cp314-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:391ee8f19bef69210978363ca930f7328081c6a0152f1166c91f0b5fdd2a773c", size = 250887, upload-time = "2026-02-09T12:58:12.503Z" },
+    { url = "https://files.pythonhosted.org/packages/6a/6c/1f1917b01eb647c2f2adc9962bd66c79eb978951cab61bdc1acab3290c07/coverage-7.13.5-cp314-cp314-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:bd3a2fbc1c6cccb3c5106140d87cc6a8715110373ef42b63cf5aea29df8c217a", size = 250992, upload-time = "2026-03-17T10:32:12.41Z" },
-    { url = "https://files.pythonhosted.org/packages/06/90/2cdab0974b9b5bbc1623f7876b73603aecac11b8d95b85b5b86b32de5eab/coverage-7.13.4-cp314-cp314-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:0dd7ab8278f0d58a0128ba2fca25824321f05d059c1441800e934ff2efa52129", size = 253396, upload-time = "2026-02-09T12:58:14.615Z" },
+    { url = "https://files.pythonhosted.org/packages/22/e5/06b1f88f42a5a99df42ce61208bdec3bddb3d261412874280a19796fc09c/coverage-7.13.5-cp314-cp314-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:6c36ddb64ed9d7e496028d1d00dfec3e428e0aabf4006583bb1839958d280510", size = 253503, upload-time = "2026-03-17T10:32:14.449Z" },
-    { url = "https://files.pythonhosted.org/packages/ac/15/ea4da0f85bf7d7b27635039e649e99deb8173fe551096ea15017f7053537/coverage-7.13.4-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:78cdf0d578b15148b009ccf18c686aa4f719d887e76e6b40c38ffb61d264a552", size = 254745, upload-time = "2026-02-09T12:58:16.162Z" },
+    { url = "https://files.pythonhosted.org/packages/80/28/2a148a51e5907e504fa7b85490277734e6771d8844ebcc48764a15e28155/coverage-7.13.5-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:380e8e9084d8eb38db3a9176a1a4f3c0082c3806fa0dc882d1d87abc3c789247", size = 254852, upload-time = "2026-03-17T10:32:16.56Z" },
-    { url = "https://files.pythonhosted.org/packages/99/11/bb356e86920c655ca4d61daee4e2bbc7258f0a37de0be32d233b561134ff/coverage-7.13.4-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:48685fee12c2eb3b27c62f2658e7ea21e9c3239cba5a8a242801a0a3f6a8c62a", size = 257055, upload-time = "2026-02-09T12:58:17.892Z" },
+    { url = "https://files.pythonhosted.org/packages/61/77/50e8d3d85cc0b7ebe09f30f151d670e302c7ff4a1bf6243f71dd8b0981fa/coverage-7.13.5-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:e808af52a0513762df4d945ea164a24b37f2f518cbe97e03deaa0ee66139b4d6", size = 257161, upload-time = "2026-03-17T10:32:19.004Z" },
-    { url = "https://files.pythonhosted.org/packages/c9/0f/9ae1f8cb17029e09da06ca4e28c9e1d5c1c0a511c7074592e37e0836c915/coverage-7.13.4-cp314-cp314-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:4e83efc079eb39480e6346a15a1bcb3e9b04759c5202d157e1dd4303cd619356", size = 250911, upload-time = "2026-02-09T12:58:19.495Z" },
+    { url = "https://files.pythonhosted.org/packages/3b/c4/b5fd1d4b7bf8d0e75d997afd3925c59ba629fc8616f1b3aae7605132e256/coverage-7.13.5-cp314-cp314-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:e301d30dd7e95ae068671d746ba8c34e945a82682e62918e41b2679acd2051a0", size = 251021, upload-time = "2026-03-17T10:32:21.344Z" },
-    { url = "https://files.pythonhosted.org/packages/89/3a/adfb68558fa815cbc29747b553bc833d2150228f251b127f1ce97e48547c/coverage-7.13.4-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:ecae9737b72408d6a950f7e525f30aca12d4bd8dd95e37342e5beb3a2a8c4f71", size = 252754, upload-time = "2026-02-09T12:58:21.064Z" },
+    { url = "https://files.pythonhosted.org/packages/f8/66/6ea21f910e92d69ef0b1c3346ea5922a51bad4446c9126db2ae96ee24c4c/coverage-7.13.5-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:800bc829053c80d240a687ceeb927a94fd108bbdc68dfbe505d0d75ab578a882", size = 252858, upload-time = "2026-03-17T10:32:23.506Z" },
-    { url = "https://files.pythonhosted.org/packages/32/b1/540d0c27c4e748bd3cd0bd001076ee416eda993c2bae47a73b7cc9357931/coverage-7.13.4-cp314-cp314-musllinux_1_2_i686.whl", hash = "sha256:ae4578f8528569d3cf303fef2ea569c7f4c4059a38c8667ccef15c6e1f118aa5", size = 250720, upload-time = "2026-02-09T12:58:22.622Z" },
+    { url = "https://files.pythonhosted.org/packages/9e/ea/879c83cb5d61aa2a35fb80e72715e92672daef8191b84911a643f533840c/coverage-7.13.5-cp314-cp314-musllinux_1_2_i686.whl", hash = "sha256:0b67af5492adb31940ee418a5a655c28e48165da5afab8c7fa6fd72a142f8740", size = 250823, upload-time = "2026-03-17T10:32:25.516Z" },
-    { url = "https://files.pythonhosted.org/packages/c7/95/383609462b3ffb1fe133014a7c84fc0dd01ed55ac6140fa1093b5af7ebb1/coverage-7.13.4-cp314-cp314-musllinux_1_2_ppc64le.whl", hash = "sha256:6fdef321fdfbb30a197efa02d48fcd9981f0d8ad2ae8903ac318adc653f5df98", size = 254994, upload-time = "2026-02-09T12:58:24.548Z" },
+    { url = "https://files.pythonhosted.org/packages/8a/fb/616d95d3adb88b9803b275580bdeee8bd1b69a886d057652521f83d7322f/coverage-7.13.5-cp314-cp314-musllinux_1_2_ppc64le.whl", hash = "sha256:c9136ff29c3a91e25b1d1552b5308e53a1e0653a23e53b6366d7c2dcbbaf8a16", size = 255099, upload-time = "2026-03-17T10:32:27.944Z" },
-    { url = "https://files.pythonhosted.org/packages/f7/ba/1761138e86c81680bfc3c49579d66312865457f9fe405b033184e5793cb3/coverage-7.13.4-cp314-cp314-musllinux_1_2_riscv64.whl", hash = "sha256:2b0f6ccf3dbe577170bebfce1318707d0e8c3650003cb4b3a9dd744575daa8b5", size = 250531, upload-time = "2026-02-09T12:58:26.271Z" },
+    { url = "https://files.pythonhosted.org/packages/1c/93/25e6917c90ec1c9a56b0b26f6cad6408e5f13bb6b35d484a0d75c9cf000d/coverage-7.13.5-cp314-cp314-musllinux_1_2_riscv64.whl", hash = "sha256:cff784eef7f0b8f6cb28804fbddcfa99f89efe4cc35fb5627e3ac58f91ed3ac0", size = 250638, upload-time = "2026-03-17T10:32:29.914Z" },
-    { url = "https://files.pythonhosted.org/packages/f8/8e/05900df797a9c11837ab59c4d6fe94094e029582aab75c3309a93e6fb4e3/coverage-7.13.4-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:75fcd519f2a5765db3f0e391eb3b7d150cce1a771bf4c9f861aeab86c767a3c0", size = 252189, upload-time = "2026-02-09T12:58:27.807Z" },
+    { url = "https://files.pythonhosted.org/packages/fc/7b/dc1776b0464145a929deed214aef9fb1493f159b59ff3c7eeeedf91eddd0/coverage-7.13.5-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:68a4953be99b17ac3c23b6efbc8a38330d99680c9458927491d18700ef23ded0", size = 252295, upload-time = "2026-03-17T10:32:31.981Z" },
-    { url = "https://files.pythonhosted.org/packages/00/bd/29c9f2db9ea4ed2738b8a9508c35626eb205d51af4ab7bf56a21a2e49926/coverage-7.13.4-cp314-cp314-win32.whl", hash = "sha256:8e798c266c378da2bd819b0677df41ab46d78065fb2a399558f3f6cae78b2fbb", size = 222258, upload-time = "2026-02-09T12:58:29.441Z" },
+    { url = "https://files.pythonhosted.org/packages/ea/fb/99cbbc56a26e07762a2740713f3c8f9f3f3106e3a3dd8cc4474954bccd34/coverage-7.13.5-cp314-cp314-win32.whl", hash = "sha256:35a31f2b1578185fbe6aa2e74cea1b1d0bbf4c552774247d9160d29b80ed56cc", size = 222360, upload-time = "2026-03-17T10:32:34.233Z" },
-    { url = "https://files.pythonhosted.org/packages/a7/4d/1f8e723f6829977410efeb88f73673d794075091c8c7c18848d273dc9d73/coverage-7.13.4-cp314-cp314-win_amd64.whl", hash = "sha256:245e37f664d89861cf2329c9afa2c1fe9e6d4e1a09d872c947e70718aeeac505", size = 223073, upload-time = "2026-02-09T12:58:31.026Z" },
+    { url = "https://files.pythonhosted.org/packages/8d/b7/4758d4f73fb536347cc5e4ad63662f9d60ba9118cb6785e9616b2ce5d7fa/coverage-7.13.5-cp314-cp314-win_amd64.whl", hash = "sha256:2aa055ae1857258f9e0045be26a6d62bdb47a72448b62d7b55f4820f361a2633", size = 223174, upload-time = "2026-03-17T10:32:36.369Z" },
-    { url = "https://files.pythonhosted.org/packages/51/5b/84100025be913b44e082ea32abcf1afbf4e872f5120b7a1cab1d331b1e13/coverage-7.13.4-cp314-cp314-win_arm64.whl", hash = "sha256:ad27098a189e5838900ce4c2a99f2fe42a0bf0c2093c17c69b45a71579e8d4a2", size = 221638, upload-time = "2026-02-09T12:58:32.599Z" },
+    { url = "https://files.pythonhosted.org/packages/2c/f2/24d84e1dfe70f8ac9fdf30d338239860d0d1d5da0bda528959d0ebc9da28/coverage-7.13.5-cp314-cp314-win_arm64.whl", hash = "sha256:1b11eef33edeae9d142f9b4358edb76273b3bfd30bc3df9a4f95d0e49caf94e8", size = 221739, upload-time = "2026-03-17T10:32:38.736Z" },
-    { url = "https://files.pythonhosted.org/packages/a7/e4/c884a405d6ead1370433dad1e3720216b4f9fd8ef5b64bfd984a2a60a11a/coverage-7.13.4-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:85480adfb35ffc32d40918aad81b89c69c9cc5661a9b8a81476d3e645321a056", size = 220246, upload-time = "2026-02-09T12:58:34.181Z" },
+    { url = "https://files.pythonhosted.org/packages/60/5b/4a168591057b3668c2428bff25dd3ebc21b629d666d90bcdfa0217940e84/coverage-7.13.5-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:10a0c37f0b646eaff7cce1874c31d1f1ccb297688d4c747291f4f4c70741cc8b", size = 220351, upload-time = "2026-03-17T10:32:41.196Z" },
-    { url = "https://files.pythonhosted.org/packages/81/5c/4d7ed8b23b233b0fffbc9dfec53c232be2e695468523242ea9fd30f97ad2/coverage-7.13.4-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:79be69cf7f3bf9b0deeeb062eab7ac7f36cd4cc4c4dd694bd28921ba4d8596cc", size = 220514, upload-time = "2026-02-09T12:58:35.704Z" },
+    { url = "https://files.pythonhosted.org/packages/f5/21/1fd5c4dbfe4a58b6b99649125635df46decdfd4a784c3cd6d410d303e370/coverage-7.13.5-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:b5db73ba3c41c7008037fa731ad5459fc3944cb7452fc0aa9f822ad3533c583c", size = 220612, upload-time = "2026-03-17T10:32:43.204Z" },
-    { url = "https://files.pythonhosted.org/packages/2f/6f/3284d4203fd2f28edd73034968398cd2d4cb04ab192abc8cff007ea35679/coverage-7.13.4-cp314-cp314t-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:caa421e2684e382c5d8973ac55e4f36bed6821a9bad5c953494de960c74595c9", size = 261877, upload-time = "2026-02-09T12:58:37.864Z" },
+    { url = "https://files.pythonhosted.org/packages/d6/fe/2a924b3055a5e7e4512655a9d4609781b0d62334fa0140c3e742926834e2/coverage-7.13.5-cp314-cp314t-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:750db93a81e3e5a9831b534be7b1229df848b2e125a604fe6651e48aa070e5f9", size = 261985, upload-time = "2026-03-17T10:32:45.514Z" },
-    { url = "https://files.pythonhosted.org/packages/09/aa/b672a647bbe1556a85337dc95bfd40d146e9965ead9cc2fe81bde1e5cbce/coverage-7.13.4-cp314-cp314t-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:14375934243ee05f56c45393fe2ce81fe5cc503c07cee2bdf1725fb8bef3ffaf", size = 264004, upload-time = "2026-02-09T12:58:39.492Z" },
+    { url = "https://files.pythonhosted.org/packages/d7/0d/c8928f2bd518c45990fe1a2ab8db42e914ef9b726c975facc4282578c3eb/coverage-7.13.5-cp314-cp314t-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:9ddb4f4a5479f2539644be484da179b653273bca1a323947d48ab107b3ed1f29", size = 264107, upload-time = "2026-03-17T10:32:47.971Z" },
-    { url = "https://files.pythonhosted.org/packages/79/a1/aa384dbe9181f98bba87dd23dda436f0c6cf2e148aecbb4e50fc51c1a656/coverage-7.13.4-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:25a41c3104d08edb094d9db0d905ca54d0cd41c928bb6be3c4c799a54753af55", size = 266408, upload-time = "2026-02-09T12:58:41.852Z" },
+    { url = "https://files.pythonhosted.org/packages/ef/ae/4ae35bbd9a0af9d820362751f0766582833c211224b38665c0f8de3d487f/coverage-7.13.5-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:d8a7a2049c14f413163e2bdabd37e41179b1d1ccb10ffc6ccc4b7a718429c607", size = 266513, upload-time = "2026-03-17T10:32:50.1Z" },
-    { url = "https://files.pythonhosted.org/packages/53/5e/5150bf17b4019bc600799f376bb9606941e55bd5a775dc1e096b6ffea952/coverage-7.13.4-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:6f01afcff62bf9a08fb32b2c1d6e924236c0383c02c790732b6537269e466a72", size = 267544, upload-time = "2026-02-09T12:58:44.093Z" },
+    { url = "https://files.pythonhosted.org/packages/9c/20/d326174c55af36f74eac6ae781612d9492f060ce8244b570bb9d50d9d609/coverage-7.13.5-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:e1c85e0b6c05c592ea6d8768a66a254bfb3874b53774b12d4c89c481eb78cb90", size = 267650, upload-time = "2026-03-17T10:32:52.391Z" },
-    { url = "https://files.pythonhosted.org/packages/e0/ed/f1de5c675987a4a7a672250d2c5c9d73d289dbf13410f00ed7181d8017dd/coverage-7.13.4-cp314-cp314t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:eb9078108fbf0bcdde37c3f4779303673c2fa1fe8f7956e68d447d0dd426d38a", size = 260980, upload-time = "2026-02-09T12:58:45.721Z" },
+    { url = "https://files.pythonhosted.org/packages/7a/5e/31484d62cbd0eabd3412e30d74386ece4a0837d4f6c3040a653878bfc019/coverage-7.13.5-cp314-cp314t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:777c4d1eff1b67876139d24288aaf1817f6c03d6bae9c5cc8d27b83bcfe38fe3", size = 261089, upload-time = "2026-03-17T10:32:54.544Z" },
-    { url = "https://files.pythonhosted.org/packages/b3/e3/fe758d01850aa172419a6743fe76ba8b92c29d181d4f676ffe2dae2ba631/coverage-7.13.4-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:0e086334e8537ddd17e5f16a344777c1ab8194986ec533711cbe6c41cde841b6", size = 263871, upload-time = "2026-02-09T12:58:47.334Z" },
+    { url = "https://files.pythonhosted.org/packages/e9/d8/49a72d6de146eebb0b7e48cc0f4bc2c0dd858e3d4790ab2b39a2872b62bd/coverage-7.13.5-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:6697e29b93707167687543480a40f0db8f356e86d9f67ddf2e37e2dfd91a9dab", size = 263982, upload-time = "2026-03-17T10:32:56.803Z" },
-    { url = "https://files.pythonhosted.org/packages/b6/76/b829869d464115e22499541def9796b25312b8cf235d3bb00b39f1675395/coverage-7.13.4-cp314-cp314t-musllinux_1_2_i686.whl", hash = "sha256:725d985c5ab621268b2edb8e50dfe57633dc69bda071abc470fed55a14935fd3", size = 261472, upload-time = "2026-02-09T12:58:48.995Z" },
+    { url = "https://files.pythonhosted.org/packages/06/3b/0351f1bd566e6e4dd39e978efe7958bde1d32f879e85589de147654f57bb/coverage-7.13.5-cp314-cp314t-musllinux_1_2_i686.whl", hash = "sha256:8fdf453a942c3e4d99bd80088141c4c6960bb232c409d9c3558e2dbaa3998562", size = 261579, upload-time = "2026-03-17T10:32:59.466Z" },
-    { url = "https://files.pythonhosted.org/packages/14/9e/caedb1679e73e2f6ad240173f55218488bfe043e38da577c4ec977489915/coverage-7.13.4-cp314-cp314t-musllinux_1_2_ppc64le.whl", hash = "sha256:3c06f0f1337c667b971ca2f975523347e63ec5e500b9aa5882d91931cd3ef750", size = 265210, upload-time = "2026-02-09T12:58:51.178Z" },
+    { url = "https://files.pythonhosted.org/packages/5d/ce/796a2a2f4017f554d7810f5c573449b35b1e46788424a548d4d19201b222/coverage-7.13.5-cp314-cp314t-musllinux_1_2_ppc64le.whl", hash = "sha256:32ca0c0114c9834a43f045a87dcebd69d108d8ffb666957ea65aa132f50332e2", size = 265316, upload-time = "2026-03-17T10:33:01.847Z" },
-    { url = "https://files.pythonhosted.org/packages/3a/10/0dd02cb009b16ede425b49ec344aba13a6ae1dc39600840ea6abcb085ac4/coverage-7.13.4-cp314-cp314t-musllinux_1_2_riscv64.whl", hash = "sha256:590c0ed4bf8e85f745e6b805b2e1c457b2e33d5255dd9729743165253bc9ad39", size = 260319, upload-time = "2026-02-09T12:58:53.081Z" },
+    { url = "https://files.pythonhosted.org/packages/3d/16/d5ae91455541d1a78bc90abf495be600588aff8f6db5c8b0dae739fa39c9/coverage-7.13.5-cp314-cp314t-musllinux_1_2_riscv64.whl", hash = "sha256:8769751c10f339021e2638cd354e13adeac54004d1941119b2c96fe5276d45ea", size = 260427, upload-time = "2026-03-17T10:33:03.945Z" },
-    { url = "https://files.pythonhosted.org/packages/92/8e/234d2c927af27c6d7a5ffad5bd2cf31634c46a477b4c7adfbfa66baf7ebb/coverage-7.13.4-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:eb30bf180de3f632cd043322dad5751390e5385108b2807368997d1a92a509d0", size = 262638, upload-time = "2026-02-09T12:58:55.258Z" },
+    { url = "https://files.pythonhosted.org/packages/48/11/07f413dba62db21fb3fad5d0de013a50e073cc4e2dc4306e770360f6dfc8/coverage-7.13.5-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:cec2d83125531bd153175354055cdb7a09987af08a9430bd173c937c6d0fba2a", size = 262745, upload-time = "2026-03-17T10:33:06.285Z" },
-    { url = "https://files.pythonhosted.org/packages/2f/64/e5547c8ff6964e5965c35a480855911b61509cce544f4d442caa759a0702/coverage-7.13.4-cp314-cp314t-win32.whl", hash = "sha256:c4240e7eded42d131a2d2c4dec70374b781b043ddc79a9de4d55ca71f8e98aea", size = 223040, upload-time = "2026-02-09T12:58:56.936Z" },
+    { url = "https://files.pythonhosted.org/packages/91/15/d792371332eb4663115becf4bad47e047d16234b1aff687b1b18c58d60ae/coverage-7.13.5-cp314-cp314t-win32.whl", hash = "sha256:0cd9ed7a8b181775459296e402ca4fb27db1279740a24e93b3b41942ebe4b215", size = 223146, upload-time = "2026-03-17T10:33:08.756Z" },
-    { url = "https://files.pythonhosted.org/packages/c7/96/38086d58a181aac86d503dfa9c47eb20715a79c3e3acbdf786e92e5c09a8/coverage-7.13.4-cp314-cp314t-win_amd64.whl", hash = "sha256:4c7d3cc01e7350f2f0f6f7036caaf5673fb56b6998889ccfe9e1c1fe75a9c932", size = 224148, upload-time = "2026-02-09T12:58:58.645Z" },
+    { url = "https://files.pythonhosted.org/packages/db/51/37221f59a111dca5e85be7dbf09696323b5b9f13ff65e0641d535ed06ea8/coverage-7.13.5-cp314-cp314t-win_amd64.whl", hash = "sha256:301e3b7dfefecaca37c9f1aa6f0049b7d4ab8dd933742b607765d757aca77d43", size = 224254, upload-time = "2026-03-17T10:33:11.174Z" },
-    { url = "https://files.pythonhosted.org/packages/ce/72/8d10abd3740a0beb98c305e0c3faf454366221c0f37a8bcf8f60020bb65a/coverage-7.13.4-cp314-cp314t-win_arm64.whl", hash = "sha256:23e3f687cf945070d1c90f85db66d11e3025665d8dafa831301a0e0038f3db9b", size = 222172, upload-time = "2026-02-09T12:59:00.396Z" },
+    { url = "https://files.pythonhosted.org/packages/54/83/6acacc889de8987441aa7d5adfbdbf33d288dad28704a67e574f1df9bcbb/coverage-7.13.5-cp314-cp314t-win_arm64.whl", hash = "sha256:9dacc2ad679b292709e0f5fc1ac74a6d4d5562e424058962c7bb0c658ad25e45", size = 222276, upload-time = "2026-03-17T10:33:13.466Z" },
-    { url = "https://files.pythonhosted.org/packages/0d/4a/331fe2caf6799d591109bb9c08083080f6de90a823695d412a935622abb2/coverage-7.13.4-py3-none-any.whl", hash = "sha256:1af1641e57cf7ba1bd67d677c9abdbcd6cc2ab7da3bca7fa1e2b7e50e65f2ad0", size = 211242, upload-time = "2026-02-09T12:59:02.032Z" },
+    { url = "https://files.pythonhosted.org/packages/9e/ee/a4cf96b8ce1e566ed238f0659ac2d3f007ed1d14b181bcb684e19561a69a/coverage-7.13.5-py3-none-any.whl", hash = "sha256:34b02417cf070e173989b3db962f7ed56d2f644307b2cf9d5a0f258e13084a61", size = 211346, upload-time = "2026-03-17T10:33:15.691Z" },
 ]
 
 [package.optional-dependencies]
@@ -235,7 +235,7 @@ wheels = [
 
 [[package]]
 name = "fastapi"
-version = "0.133.1"
+version = "0.135.1"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "annotated-doc" },
@@ -244,14 +244,14 @@ dependencies = [
     { name = "typing-extensions" },
     { name = "typing-inspection" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/22/6f/0eafed8349eea1fa462238b54a624c8b408cd1ba2795c8e64aa6c34f8ab7/fastapi-0.133.1.tar.gz", hash = "sha256:ed152a45912f102592976fde6cbce7dae1a8a1053da94202e51dd35d184fadd6", size = 378741, upload-time = "2026-02-25T18:18:17.398Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/e7/7b/f8e0211e9380f7195ba3f3d40c292594fd81ba8ec4629e3854c353aaca45/fastapi-0.135.1.tar.gz", hash = "sha256:d04115b508d936d254cea545b7312ecaa58a7b3a0f84952535b4c9afae7668cd", size = 394962, upload-time = "2026-03-01T18:18:29.369Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/d2/c9/a175a7779f3599dfa4adfc97a6ce0e157237b3d7941538604aadaf97bfb6/fastapi-0.133.1-py3-none-any.whl", hash = "sha256:658f34ba334605b1617a65adf2ea6461901bdb9af3a3080d63ff791ecf7dc2e2", size = 109029, upload-time = "2026-02-25T18:18:18.578Z" },
+    { url = "https://files.pythonhosted.org/packages/e4/72/42e900510195b23a56bde950d26a51f8b723846bfcaa0286e90287f0422b/fastapi-0.135.1-py3-none-any.whl", hash = "sha256:46e2fc5745924b7c840f71ddd277382af29ce1cdb7d5eab5bf697e3fb9999c9e", size = 116999, upload-time = "2026-03-01T18:18:30.831Z" },
 ]
 
 [[package]]
 name = "fastapi-toolsets"
-version = "1.3.0"
+version = "2.3.0"
 source = { editable = "." }
 dependencies = [
     { name = "asyncpg" },
@@ -285,6 +285,7 @@ dev = [
     { name = "coverage" },
     { name = "fastapi-toolsets", extra = ["all"] },
     { name = "httpx" },
+    { name = "mike" },
     { name = "mkdocstrings-python" },
     { name = "pytest" },
     { name = "pytest-anyio" },
@@ -295,6 +296,7 @@ dev = [
     { name = "zensical" },
 ]
 docs = [
+    { name = "mike" },
     { name = "mkdocstrings-python" },
     { name = "zensical" },
 ]
@@ -327,6 +329,7 @@ dev = [
     { name = "coverage", specifier = ">=7.0.0" },
     { name = "fastapi-toolsets", extras = ["all"] },
     { name = "httpx", specifier = ">=0.25.0" },
+    { name = "mike", specifier = ">=2.0.0" },
     { name = "mkdocstrings-python", specifier = ">=2.0.2" },
     { name = "pytest", specifier = ">=8.0.0" },
     { name = "pytest-anyio", specifier = ">=0.0.0" },
@@ -334,11 +337,12 @@ dev = [
     { name = "pytest-xdist", specifier = ">=3.0.0" },
     { name = "ruff", specifier = ">=0.1.0" },
     { name = "ty", specifier = ">=0.0.1a0" },
-    { name = "zensical", specifier = ">=0.0.23" },
+    { name = "zensical", specifier = ">=0.0.28" },
 ]
 docs = [
+    { name = "mike", specifier = ">=2.0.0" },
     { name = "mkdocstrings-python", specifier = ">=2.0.2" },
-    { name = "zensical", specifier = ">=0.0.23" },
+    { name = "zensical", specifier = ">=0.0.28" },
 ]
 tests = [
     { name = "coverage", specifier = ">=7.0.0" },
@@ -601,6 +605,23 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/2c/19/04f9b178c2d8a15b076c8b5140708fa6ffc5601fb6f1e975537072df5b2a/mergedeep-1.3.4-py3-none-any.whl", hash = "sha256:70775750742b25c0d8f36c55aed03d24c3384d17c951b3175d898bd778ef0307", size = 6354, upload-time = "2021-02-05T18:55:29.583Z" },
 ]
 
+[[package]]
+name = "mike"
+version = "2.1.4"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "jinja2" },
+    { name = "mkdocs" },
+    { name = "pyparsing" },
+    { name = "pyyaml" },
+    { name = "pyyaml-env-tag" },
+    { name = "verspec" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/ec/09/de1cab0018eb5f1fbd9dcc26b6e61f9453c5ec2eb790949d6ed75e1ffe55/mike-2.1.4.tar.gz", hash = "sha256:75d549420b134603805a65fc67f7dcd9fcd0ad1454fb2c893d9e844cba1aa6e4", size = 38190, upload-time = "2026-03-08T02:46:29.187Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/48/f7/10f5e101db25741b91e4f4792c5d97b4fa834ead5cf509ae91097d939424/mike-2.1.4-py3-none-any.whl", hash = "sha256:39933e992e155dd70f2297e749a0ed78d8fd7942bc33a3666195d177758a280e", size = 33820, upload-time = "2026-03-08T02:46:28.149Z" },
+]
+
 [[package]]
 name = "mkdocs"
 version = "1.6.1"
@@ -863,6 +884,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/6f/2c/5b079febdc65e1c3fb2729bf958d18b45be7113828528e8a0b5850dd819a/pymdown_extensions-10.21-py3-none-any.whl", hash = "sha256:91b879f9f864d49794c2d9534372b10150e6141096c3908a455e45ca72ad9d3f", size = 268877, upload-time = "2026-02-15T20:44:05.464Z" },
 ]
 
+[[package]]
+name = "pyparsing"
+version = "3.3.2"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/f3/91/9c6ee907786a473bf81c5f53cf703ba0957b23ab84c264080fb5a450416f/pyparsing-3.3.2.tar.gz", hash = "sha256:c777f4d763f140633dcb6d8a3eda953bf7a214dc4eff598413c070bcdc117cbc", size = 6851574, upload-time = "2026-01-21T03:57:59.36Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/10/bd/c038d7cc38edc1aa5bf91ab8068b63d4308c66c4c8bb3cbba7dfbc049f9c/pyparsing-3.3.2-py3-none-any.whl", hash = "sha256:850ba148bd908d7e2411587e247a1e4f0327839c40e2e5e6d05a007ecc69911d", size = 122781, upload-time = "2026-01-21T03:57:55.912Z" },
+]
+
 [[package]]
 name = "pytest"
 version = "9.0.2"
@@ -1013,27 +1043,27 @@ wheels = [
 
 [[package]]
 name = "ruff"
-version = "0.15.2"
+version = "0.15.6"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/06/04/eab13a954e763b0606f460443fcbf6bb5a0faf06890ea3754ff16523dce5/ruff-0.15.2.tar.gz", hash = "sha256:14b965afee0969e68bb871eba625343b8673375f457af4abe98553e8bbb98342", size = 4558148, upload-time = "2026-02-19T22:32:20.271Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/51/df/f8629c19c5318601d3121e230f74cbee7a3732339c52b21daa2b82ef9c7d/ruff-0.15.6.tar.gz", hash = "sha256:8394c7bb153a4e3811a4ecdacd4a8e6a4fa8097028119160dffecdcdf9b56ae4", size = 4597916, upload-time = "2026-03-12T23:05:47.51Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/2f/70/3a4dc6d09b13cb3e695f28307e5d889b2e1a66b7af9c5e257e796695b0e6/ruff-0.15.2-py3-none-linux_armv6l.whl", hash = "sha256:120691a6fdae2f16d65435648160f5b81a9625288f75544dc40637436b5d3c0d", size = 10430565, upload-time = "2026-02-19T22:32:41.824Z" },
+    { url = "https://files.pythonhosted.org/packages/9e/2f/4e03a7e5ce99b517e98d3b4951f411de2b0fa8348d39cf446671adcce9a2/ruff-0.15.6-py3-none-linux_armv6l.whl", hash = "sha256:7c98c3b16407b2cf3d0f2b80c80187384bc92c6774d85fefa913ecd941256fff", size = 10508953, upload-time = "2026-03-12T23:05:17.246Z" },
-    { url = "https://files.pythonhosted.org/packages/71/0b/bb8457b56185ece1305c666dc895832946d24055be90692381c31d57466d/ruff-0.15.2-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:a89056d831256099658b6bba4037ac6dd06f49d194199215befe2bb10457ea5e", size = 10820354, upload-time = "2026-02-19T22:32:07.366Z" },
+    { url = "https://files.pythonhosted.org/packages/70/60/55bcdc3e9f80bcf39edf0cd272da6fa511a3d94d5a0dd9e0adf76ceebdb4/ruff-0.15.6-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:ee7dcfaad8b282a284df4aa6ddc2741b3f4a18b0555d626805555a820ea181c3", size = 10942257, upload-time = "2026-03-12T23:05:23.076Z" },
-    { url = "https://files.pythonhosted.org/packages/2d/c1/e0532d7f9c9e0b14c46f61b14afd563298b8b83f337b6789ddd987e46121/ruff-0.15.2-py3-none-macosx_11_0_arm64.whl", hash = "sha256:e36dee3a64be0ebd23c86ffa3aa3fd3ac9a712ff295e192243f814a830b6bd87", size = 10170767, upload-time = "2026-02-19T22:32:13.188Z" },
+    { url = "https://files.pythonhosted.org/packages/e7/f9/005c29bd1726c0f492bfa215e95154cf480574140cb5f867c797c18c790b/ruff-0.15.6-py3-none-macosx_11_0_arm64.whl", hash = "sha256:3bd9967851a25f038fc8b9ae88a7fbd1b609f30349231dffaa37b6804923c4bb", size = 10322683, upload-time = "2026-03-12T23:05:33.738Z" },
-    { url = "https://files.pythonhosted.org/packages/47/e8/da1aa341d3af017a21c7a62fb5ec31d4e7ad0a93ab80e3a508316efbcb23/ruff-0.15.2-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:a9fb47b6d9764677f8c0a193c0943ce9a05d6763523f132325af8a858eadc2b9", size = 10529591, upload-time = "2026-02-19T22:32:02.547Z" },
+    { url = "https://files.pythonhosted.org/packages/5f/74/2f861f5fd7cbb2146bddb5501450300ce41562da36d21868c69b7a828169/ruff-0.15.6-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:13f4594b04e42cd24a41da653886b04d2ff87adbf57497ed4f728b0e8a4866f8", size = 10660986, upload-time = "2026-03-12T23:05:53.245Z" },
-    { url = "https://files.pythonhosted.org/packages/93/74/184fbf38e9f3510231fbc5e437e808f0b48c42d1df9434b208821efcd8d6/ruff-0.15.2-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:f376990f9d0d6442ea9014b19621d8f2aaf2b8e39fdbfc79220b7f0c596c9b80", size = 10260771, upload-time = "2026-02-19T22:32:36.938Z" },
+    { url = "https://files.pythonhosted.org/packages/c1/a1/309f2364a424eccb763cdafc49df843c282609f47fe53aa83f38272389e0/ruff-0.15.6-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:e2ed8aea2f3fe57886d3f00ea5b8aae5bf68d5e195f487f037a955ff9fbaac9e", size = 10332177, upload-time = "2026-03-12T23:05:56.145Z" },
-    { url = "https://files.pythonhosted.org/packages/05/ac/605c20b8e059a0bc4b42360414baa4892ff278cec1c91fff4be0dceedefd/ruff-0.15.2-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:2dcc987551952d73cbf5c88d9fdee815618d497e4df86cd4c4824cc59d5dd75f", size = 11045791, upload-time = "2026-02-19T22:32:31.642Z" },
+    { url = "https://files.pythonhosted.org/packages/30/41/7ebf1d32658b4bab20f8ac80972fb19cd4e2c6b78552be263a680edc55ac/ruff-0.15.6-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:70789d3e7830b848b548aae96766431c0dc01a6c78c13381f423bf7076c66d15", size = 11170783, upload-time = "2026-03-12T23:06:01.742Z" },
-    { url = "https://files.pythonhosted.org/packages/fd/52/db6e419908f45a894924d410ac77d64bdd98ff86901d833364251bd08e22/ruff-0.15.2-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:42a47fd785cbe8c01b9ff45031af875d101b040ad8f4de7bbb716487c74c9a77", size = 11879271, upload-time = "2026-02-19T22:32:29.305Z" },
+    { url = "https://files.pythonhosted.org/packages/76/be/6d488f6adca047df82cd62c304638bcb00821c36bd4881cfca221561fdfc/ruff-0.15.6-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:542aaf1de3154cea088ced5a819ce872611256ffe2498e750bbae5247a8114e9", size = 12044201, upload-time = "2026-03-12T23:05:28.697Z" },
-    { url = "https://files.pythonhosted.org/packages/3e/d8/7992b18f2008bdc9231d0f10b16df7dda964dbf639e2b8b4c1b4e91b83af/ruff-0.15.2-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:cbe9f49354866e575b4c6943856989f966421870e85cd2ac94dccb0a9dcb2fea", size = 11303707, upload-time = "2026-02-19T22:32:22.492Z" },
+    { url = "https://files.pythonhosted.org/packages/71/68/e6f125df4af7e6d0b498f8d373274794bc5156b324e8ab4bf5c1b4fc0ec7/ruff-0.15.6-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:1c22e6f02c16cfac3888aa636e9eba857254d15bbacc9906c9689fdecb1953ab", size = 11421561, upload-time = "2026-03-12T23:05:31.236Z" },
-    { url = "https://files.pythonhosted.org/packages/d7/02/849b46184bcfdd4b64cde61752cc9a146c54759ed036edd11857e9b8443b/ruff-0.15.2-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:b7a672c82b5f9887576087d97be5ce439f04bbaf548ee987b92d3a7dede41d3a", size = 11149151, upload-time = "2026-02-19T22:32:44.234Z" },
+    { url = "https://files.pythonhosted.org/packages/f1/9f/f85ef5fd01a52e0b472b26dc1b4bd228b8f6f0435975442ffa4741278703/ruff-0.15.6-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:98893c4c0aadc8e448cfa315bd0cc343a5323d740fe5f28ef8a3f9e21b381f7e", size = 11310928, upload-time = "2026-03-12T23:05:45.288Z" },
-    { url = "https://files.pythonhosted.org/packages/70/04/f5284e388bab60d1d3b99614a5a9aeb03e0f333847e2429bebd2aaa1feec/ruff-0.15.2-py3-none-manylinux_2_31_riscv64.whl", hash = "sha256:72ecc64f46f7019e2bcc3cdc05d4a7da958b629a5ab7033195e11a438403d956", size = 11091132, upload-time = "2026-02-19T22:32:24.691Z" },
+    { url = "https://files.pythonhosted.org/packages/8c/26/b75f8c421f5654304b89471ed384ae8c7f42b4dff58fa6ce1626d7f2b59a/ruff-0.15.6-py3-none-manylinux_2_31_riscv64.whl", hash = "sha256:70d263770d234912374493e8cc1e7385c5d49376e41dfa51c5c3453169dc581c", size = 11235186, upload-time = "2026-03-12T23:05:50.677Z" },
-    { url = "https://files.pythonhosted.org/packages/fa/ae/88d844a21110e14d92cf73d57363fab59b727ebeabe78009b9ccb23500af/ruff-0.15.2-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:8dcf243b15b561c655c1ef2f2b0050e5d50db37fe90115507f6ff37d865dc8b4", size = 10504717, upload-time = "2026-02-19T22:32:26.75Z" },
+    { url = "https://files.pythonhosted.org/packages/fc/d4/d5a6d065962ff7a68a86c9b4f5500f7d101a0792078de636526c0edd40da/ruff-0.15.6-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:55a1ad63c5a6e54b1f21b7514dfadc0c7fb40093fa22e95143cf3f64ebdcd512", size = 10635231, upload-time = "2026-03-12T23:05:37.044Z" },
-    { url = "https://files.pythonhosted.org/packages/64/27/867076a6ada7f2b9c8292884ab44d08fd2ba71bd2b5364d4136f3cd537e1/ruff-0.15.2-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:dab6941c862c05739774677c6273166d2510d254dac0695c0e3f5efa1b5585de", size = 10263122, upload-time = "2026-02-19T22:32:10.036Z" },
+    { url = "https://files.pythonhosted.org/packages/d6/56/7c3acf3d50910375349016cf33de24be021532042afbed87942858992491/ruff-0.15.6-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:8dc473ba093c5ec238bb1e7429ee676dca24643c471e11fbaa8a857925b061c0", size = 10340357, upload-time = "2026-03-12T23:06:04.748Z" },
-    { url = "https://files.pythonhosted.org/packages/e7/ef/faf9321d550f8ebf0c6373696e70d1758e20ccdc3951ad7af00c0956be7c/ruff-0.15.2-py3-none-musllinux_1_2_i686.whl", hash = "sha256:1b9164f57fc36058e9a6806eb92af185b0697c9fe4c7c52caa431c6554521e5c", size = 10735295, upload-time = "2026-02-19T22:32:39.227Z" },
+    { url = "https://files.pythonhosted.org/packages/06/54/6faa39e9c1033ff6a3b6e76b5df536931cd30caf64988e112bbf91ef5ce5/ruff-0.15.6-py3-none-musllinux_1_2_i686.whl", hash = "sha256:85b042377c2a5561131767974617006f99f7e13c63c111b998f29fc1e58a4cfb", size = 10860583, upload-time = "2026-03-12T23:05:58.978Z" },
-    { url = "https://files.pythonhosted.org/packages/2f/55/e8089fec62e050ba84d71b70e7834b97709ca9b7aba10c1a0b196e493f97/ruff-0.15.2-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:80d24fcae24d42659db7e335b9e1531697a7102c19185b8dc4a028b952865fd8", size = 11241641, upload-time = "2026-02-19T22:32:34.617Z" },
+    { url = "https://files.pythonhosted.org/packages/cb/1e/509a201b843b4dfb0b32acdedf68d951d3377988cae43949ba4c4133a96a/ruff-0.15.6-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:cef49e30bc5a86a6a92098a7fbf6e467a234d90b63305d6f3ec01225a9d092e0", size = 11410976, upload-time = "2026-03-12T23:05:39.955Z" },
-    { url = "https://files.pythonhosted.org/packages/23/01/1c30526460f4d23222d0fabd5888868262fd0e2b71a00570ca26483cd993/ruff-0.15.2-py3-none-win32.whl", hash = "sha256:fd5ff9e5f519a7e1bd99cbe8daa324010a74f5e2ebc97c6242c08f26f3714f6f", size = 10507885, upload-time = "2026-02-19T22:32:15.635Z" },
+    { url = "https://files.pythonhosted.org/packages/6c/25/3fc9114abf979a41673ce877c08016f8e660ad6cf508c3957f537d2e9fa9/ruff-0.15.6-py3-none-win32.whl", hash = "sha256:bbf67d39832404812a2d23020dda68fee7f18ce15654e96fb1d3ad21a5fe436c", size = 10616872, upload-time = "2026-03-12T23:05:42.451Z" },
-    { url = "https://files.pythonhosted.org/packages/5c/10/3d18e3bbdf8fc50bbb4ac3cc45970aa5a9753c5cb51bf9ed9a3cd8b79fa3/ruff-0.15.2-py3-none-win_amd64.whl", hash = "sha256:d20014e3dfa400f3ff84830dfb5755ece2de45ab62ecea4af6b7262d0fb4f7c5", size = 11623725, upload-time = "2026-02-19T22:32:04.947Z" },
+    { url = "https://files.pythonhosted.org/packages/89/7a/09ece68445ceac348df06e08bf75db72d0e8427765b96c9c0ffabc1be1d9/ruff-0.15.6-py3-none-win_amd64.whl", hash = "sha256:aee25bc84c2f1007ecb5037dff75cef00414fdf17c23f07dc13e577883dca406", size = 11787271, upload-time = "2026-03-12T23:05:20.168Z" },
-    { url = "https://files.pythonhosted.org/packages/6d/78/097c0798b1dab9f8affe73da9642bb4500e098cb27fd8dc9724816ac747b/ruff-0.15.2-py3-none-win_arm64.whl", hash = "sha256:cabddc5822acdc8f7b5527b36ceac55cc51eec7b1946e60181de8fe83ca8876e", size = 10941649, upload-time = "2026-02-19T22:32:18.108Z" },
+    { url = "https://files.pythonhosted.org/packages/7f/d0/578c47dd68152ddddddf31cd7fc67dc30b7cdf639a86275fda821b0d9d98/ruff-0.15.6-py3-none-win_arm64.whl", hash = "sha256:c34de3dd0b0ba203be50ae70f5910b17188556630e2178fd7d79fc030eb0d837", size = 11060497, upload-time = "2026-03-12T23:05:25.968Z" },
 ]
 
 [[package]]
@@ -1177,26 +1207,26 @@ wheels = [
 
 [[package]]
 name = "ty"
-version = "0.0.18"
+version = "0.0.23"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/74/15/9682700d8d60fdca7afa4febc83a2354b29cdcd56e66e19c92b521db3b39/ty-0.0.18.tar.gz", hash = "sha256:04ab7c3db5dcbcdac6ce62e48940d3a0124f377c05499d3f3e004e264ae94b83", size = 5214774, upload-time = "2026-02-20T21:51:31.173Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/75/ba/d3c998ff4cf6b5d75b39356db55fe1b7caceecc522b9586174e6a5dee6f7/ty-0.0.23.tar.gz", hash = "sha256:5fb05db58f202af366f80ef70f806e48f5237807fe424ec787c9f289e3f3a4ef", size = 5341461, upload-time = "2026-03-13T12:34:23.125Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/ae/d8/920460d4c22ea68fcdeb0b2fb53ea2aeb9c6d7875bde9278d84f2ac767b6/ty-0.0.18-py3-none-linux_armv6l.whl", hash = "sha256:4e5e91b0a79857316ef893c5068afc4b9872f9d257627d9bc8ac4d2715750d88", size = 10280825, upload-time = "2026-02-20T21:51:25.03Z" },
+    { url = "https://files.pythonhosted.org/packages/f4/21/aab32603dfdfacd4819e52fa8c6074e7bd578218a5142729452fc6a62db6/ty-0.0.23-py3-none-linux_armv6l.whl", hash = "sha256:e810eef1a5f1cfc0731a58af8d2f334906a96835829767aed00026f1334a8dd7", size = 10329096, upload-time = "2026-03-13T12:34:09.432Z" },
-    { url = "https://files.pythonhosted.org/packages/83/56/62587de582d3d20d78fcdddd0594a73822ac5a399a12ef512085eb7a4de6/ty-0.0.18-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:ee0e578b3f8416e2d5416da9553b78fd33857868aa1384cb7fefeceee5ff102d", size = 10118324, upload-time = "2026-02-20T21:51:22.27Z" },
+    { url = "https://files.pythonhosted.org/packages/9f/a9/dd3287a82dce3df546ec560296208d4905dcf06346b6e18c2f3c63523bd1/ty-0.0.23-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:e43d36bd89a151ddcad01acaeff7dcc507cb73ff164c1878d2d11549d39a061c", size = 10156631, upload-time = "2026-03-13T12:34:53.122Z" },
-    { url = "https://files.pythonhosted.org/packages/2f/2d/dbdace8d432a0755a7417f659bfd5b8a4261938ecbdfd7b42f4c454f5aa9/ty-0.0.18-py3-none-macosx_11_0_arm64.whl", hash = "sha256:3f7a0487d36b939546a91d141f7fc3dbea32fab4982f618d5b04dc9d5b6da21e", size = 9605861, upload-time = "2026-02-20T21:51:16.066Z" },
+    { url = "https://files.pythonhosted.org/packages/0f/01/3f25909b02fac29bb0a62b2251f8d62e65d697781ffa4cf6b47a4c075c85/ty-0.0.23-py3-none-macosx_11_0_arm64.whl", hash = "sha256:bd6a340969577b4645f231572c4e46012acba2d10d4c0c6570fe1ab74e76ae00", size = 9653211, upload-time = "2026-03-13T12:34:15.049Z" },
-    { url = "https://files.pythonhosted.org/packages/6b/d9/de11c0280f778d5fc571393aada7fe9b8bc1dd6a738f2e2c45702b8b3150/ty-0.0.18-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:d5e2fa8d45f57ca487a470e4bf66319c09b561150e98ae2a6b1a97ef04c1a4eb", size = 10092701, upload-time = "2026-02-20T21:51:26.862Z" },
+    { url = "https://files.pythonhosted.org/packages/d5/60/bfc0479572a6f4b90501c869635faf8d84c8c68ffc5dd87d04f049affabc/ty-0.0.23-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:341441783e626eeb7b1ec2160432956aed5734932ab2d1c26f94d0c98b229937", size = 10156143, upload-time = "2026-03-13T12:34:34.468Z" },
-    { url = "https://files.pythonhosted.org/packages/0f/94/068d4d591d791041732171e7b63c37a54494b2e7d28e88d2167eaa9ad875/ty-0.0.18-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:d75652e9e937f7044b1aca16091193e7ef11dac1c7ec952b7fb8292b7ba1f5f2", size = 10109203, upload-time = "2026-02-20T21:51:11.59Z" },
+    { url = "https://files.pythonhosted.org/packages/3a/81/8a93e923535a340f54bea20ff196f6b2787782b2f2f399bd191c4bc132d6/ty-0.0.23-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:8ce1dc66c26d4167e2c78d12fa870ef5a7ec9cc344d2baaa6243297cfa88bd52", size = 10136632, upload-time = "2026-03-13T12:34:28.832Z" },
-    { url = "https://files.pythonhosted.org/packages/34/e4/526a4aa56dc0ca2569aaa16880a1ab105c3b416dd70e87e25a05688999f3/ty-0.0.18-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:563c868edceb8f6ddd5e91113c17d3676b028f0ed380bdb3829b06d9beb90e58", size = 10614200, upload-time = "2026-02-20T21:51:20.298Z" },
+    { url = "https://files.pythonhosted.org/packages/da/cb/2ac81c850c58acc9f976814404d28389c9c1c939676e32287b9cff61381e/ty-0.0.23-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:bae1e7a294bf8528836f7617dc5c360ea2dddb63789fc9471ae6753534adca05", size = 10655025, upload-time = "2026-03-13T12:34:37.105Z" },
-    { url = "https://files.pythonhosted.org/packages/fd/3d/b68ab20a34122a395880922587fbfc3adf090d22e0fb546d4d20fe8c2621/ty-0.0.18-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:502e2a1f948bec563a0454fc25b074bf5cf041744adba8794d024277e151d3b0", size = 11153232, upload-time = "2026-02-20T21:51:14.121Z" },
+    { url = "https://files.pythonhosted.org/packages/b5/9b/bac771774c198c318ae699fc013d8cd99ed9caf993f661fba11238759244/ty-0.0.23-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:d2b162768764d9dc177c83fb497a51532bb67cbebe57b8fa0f2668436bf53f3c", size = 11230107, upload-time = "2026-03-13T12:34:20.751Z" },
-    { url = "https://files.pythonhosted.org/packages/68/ea/678243c042343fcda7e6af36036c18676c355878dcdcd517639586d2cf9e/ty-0.0.18-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:cc881dea97021a3aa29134a476937fd8054775c4177d01b94db27fcfb7aab65b", size = 10832934, upload-time = "2026-02-20T21:51:32.92Z" },
+    { url = "https://files.pythonhosted.org/packages/14/09/7644fb0e297265e18243f878aca343593323b9bb19ed5278dcbc63781be0/ty-0.0.23-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:d28384e48ca03b34e4e2beee0e230c39bbfb68994bb44927fec61ef3642900da", size = 10934177, upload-time = "2026-03-13T12:34:17.904Z" },
-    { url = "https://files.pythonhosted.org/packages/d8/bd/7f8d647cef8b7b346c0163230a37e903c7461c7248574840b977045c77df/ty-0.0.18-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:421fcc3bc64cab56f48edb863c7c1c43649ec4d78ff71a1acb5366ad723b6021", size = 10700888, upload-time = "2026-02-20T21:51:09.673Z" },
+    { url = "https://files.pythonhosted.org/packages/18/14/69a25a0cad493fb6a947302471b579a03516a3b00e7bece77fdc6b4afb9b/ty-0.0.23-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:559d9a299df793cb7a7902caed5eda8a720ff69164c31c979673e928f02251ee", size = 10752487, upload-time = "2026-03-13T12:34:31.785Z" },
-    { url = "https://files.pythonhosted.org/packages/6e/06/cb3620dc48c5d335ba7876edfef636b2f4498eff4a262ff90033b9e88408/ty-0.0.18-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:0fe5038a7136a0e638a2fb1ad06e3d3c4045314c6ba165c9c303b9aeb4623d6c", size = 10078965, upload-time = "2026-02-20T21:51:07.678Z" },
+    { url = "https://files.pythonhosted.org/packages/9d/2a/42fc3cbccf95af0a62308ebed67e084798ab7a85ef073c9986ef18032743/ty-0.0.23-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:32a7b8a14a98e1d20a9d8d2af23637ed7efdb297ac1fa2450b8e465d05b94482", size = 10133007, upload-time = "2026-03-13T12:34:42.838Z" },
-    { url = "https://files.pythonhosted.org/packages/60/27/c77a5a84533fa3b685d592de7b4b108eb1f38851c40fac4e79cc56ec7350/ty-0.0.18-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:d123600a52372677613a719bbb780adeb9b68f47fb5f25acb09171de390e0035", size = 10134659, upload-time = "2026-02-20T21:51:18.311Z" },
+    { url = "https://files.pythonhosted.org/packages/e1/69/307833f1b52fa3670e0a1d496e43ef7df556ecde838192d3fcb9b35e360d/ty-0.0.23-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:6f803b9b9cca87af793467973b9abdd4b83e6b96d9b5e749d662cff7ead70b6d", size = 10169698, upload-time = "2026-03-13T12:34:12.351Z" },
-    { url = "https://files.pythonhosted.org/packages/43/6e/60af6b88c73469e628ba5253a296da6984e0aa746206f3034c31f1a04ed1/ty-0.0.18-py3-none-musllinux_1_2_i686.whl", hash = "sha256:bb4bc11d32a1bf96a829bf6b9696545a30a196ac77bbc07cc8d3dfee35e03723", size = 10297494, upload-time = "2026-02-20T21:51:39.631Z" },
+    { url = "https://files.pythonhosted.org/packages/89/ae/5dd379ec22d0b1cba410d7af31c366fcedff191d5b867145913a64889f66/ty-0.0.23-py3-none-musllinux_1_2_i686.whl", hash = "sha256:4a0bf086ec8e2197b7ea7ebfcf4be36cb6a52b235f8be61647ef1b2d99d6ffd3", size = 10346080, upload-time = "2026-03-13T12:34:40.012Z" },
-    { url = "https://files.pythonhosted.org/packages/33/90/612dc0b68224c723faed6adac2bd3f930a750685db76dfe17e6b9e534a83/ty-0.0.18-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:dda2efbf374ba4cd704053d04e32f2f784e85c2ddc2400006b0f96f5f7e4b667", size = 10791944, upload-time = "2026-02-20T21:51:37.13Z" },
+    { url = "https://files.pythonhosted.org/packages/98/c7/dfc83203d37998620bba9c4873a080c8850a784a8a46f56f8163c5b4e320/ty-0.0.23-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:252539c3fcd7aeb9b8d5c14e2040682c3e1d7ff640906d63fd2c4ce35865a4ba", size = 10848162, upload-time = "2026-03-13T12:34:45.421Z" },
-    { url = "https://files.pythonhosted.org/packages/0d/da/f4ada0fd08a9e4138fe3fd2bcd3797753593f423f19b1634a814b9b2a401/ty-0.0.18-py3-none-win32.whl", hash = "sha256:c5768607c94977dacddc2f459ace6a11a408a0f57888dd59abb62d28d4fee4f7", size = 9677964, upload-time = "2026-02-20T21:51:42.039Z" },
+    { url = "https://files.pythonhosted.org/packages/89/08/05481511cfbcc1fd834b6c67aaae090cb609a079189ddf2032139ccfc490/ty-0.0.23-py3-none-win32.whl", hash = "sha256:51b591d19eef23bbc3807aef77d38fa1f003c354e1da908aa80ea2dca0993f77", size = 9748283, upload-time = "2026-03-13T12:34:50.607Z" },
-    { url = "https://files.pythonhosted.org/packages/5e/fa/090ed9746e5c59fc26d8f5f96dc8441825171f1f47752f1778dad690b08b/ty-0.0.18-py3-none-win_amd64.whl", hash = "sha256:b78d0fa1103d36fc2fce92f2092adace52a74654ab7884d54cdaec8eb5016a4d", size = 10636576, upload-time = "2026-02-20T21:51:29.159Z" },
+    { url = "https://files.pythonhosted.org/packages/31/2e/eaed4ff5c85e857a02415084c394e02c30476b65e158eec1938fdaa9a205/ty-0.0.23-py3-none-win_amd64.whl", hash = "sha256:1e137e955f05c501cfbb81dd2190c8fb7d01ec037c7e287024129c722a83c9ad", size = 10698355, upload-time = "2026-03-13T12:34:26.134Z" },
-    { url = "https://files.pythonhosted.org/packages/92/4f/5dd60904c8105cda4d0be34d3a446c180933c76b84ae0742e58f02133713/ty-0.0.18-py3-none-win_arm64.whl", hash = "sha256:01770c3c82137c6b216aa3251478f0b197e181054ee92243772de553d3586398", size = 10095449, upload-time = "2026-02-20T21:51:34.914Z" },
+    { url = "https://files.pythonhosted.org/packages/91/29/b32cb7b4c7d56b9ed50117f8ad6e45834aec293e4cb14749daab4e9236d5/ty-0.0.23-py3-none-win_arm64.whl", hash = "sha256:a0399bd13fd2cd6683fd0a2d59b9355155d46546d8203e152c556ddbdeb20842", size = 10155890, upload-time = "2026-03-13T12:34:48.082Z" },
 ]
 
 [[package]]
@@ -1235,6 +1265,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/dc/9b/47798a6c91d8bdb567fe2698fe81e0c6b7cb7ef4d13da4114b41d239f65d/typing_inspection-0.4.2-py3-none-any.whl", hash = "sha256:4ed1cacbdc298c220f1bd249ed5287caa16f34d44ef4e9c3d0cbad5b521545e7", size = 14611, upload-time = "2025-10-01T02:14:40.154Z" },
 ]
 
+[[package]]
+name = "verspec"
+version = "0.1.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/e7/44/8126f9f0c44319b2efc65feaad589cadef4d77ece200ae3c9133d58464d0/verspec-0.1.0.tar.gz", hash = "sha256:c4504ca697b2056cdb4bfa7121461f5a0e81809255b41c03dda4ba823637c01e", size = 27123, upload-time = "2020-11-30T02:24:09.646Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/a4/ce/3b6fee91c85626eaf769d617f1be9d2e15c1cca027bbdeb2e0d751469355/verspec-0.1.0-py3-none-any.whl", hash = "sha256:741877d5633cc9464c45a469ae2a31e801e6dbbaa85b9675d481cda100f11c31", size = 19640, upload-time = "2020-11-30T02:24:08.387Z" },
+]
+
 [[package]]
 name = "watchdog"
 version = "6.0.0"
@@ -1264,7 +1303,7 @@ wheels = [
 
 [[package]]
 name = "zensical"
-version = "0.0.23"
+version = "0.0.28"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "click" },
@@ -1274,18 +1313,18 @@ dependencies = [
     { name = "pymdown-extensions" },
     { name = "pyyaml" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/a3/ab/a65452b4e769552fd5a78c4996d6cf322630d896ddfd55c5433d96485e8b/zensical-0.0.23.tar.gz", hash = "sha256:5c4fc3aaf075df99d8cf41b9f2566e4d588180d9a89493014d3607dfe50ac4bc", size = 3822451, upload-time = "2026-02-11T21:24:38.373Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/14/0a/ed78749cd30c8b72f6b3f85de7f4da45ddcbbd006222aa63f7d6e27d68db/zensical-0.0.28.tar.gz", hash = "sha256:af7d75a1b297721dfc9b897f729b601e56b3e566990a989e9e3e373a8cd04c40", size = 3842655, upload-time = "2026-03-19T14:28:09.17Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/66/86/035aa02bd36d26a03a1885bc22a73d4fe61ba0e21d0033cc42baf13d24f6/zensical-0.0.23-cp310-abi3-macosx_10_12_x86_64.whl", hash = "sha256:35d6d3eb803fe73a67187a1a25443408bd02a8dd50e151f4a4bafd40de3f0928", size = 12242966, upload-time = "2026-02-11T21:24:05.894Z" },
+    { url = "https://files.pythonhosted.org/packages/ce/c5/05e6a8b8ecfc255ff59414c71e1904b1ceaf3ccbc26f14b90ce82aaab16e/zensical-0.0.28-cp310-abi3-macosx_10_12_x86_64.whl", hash = "sha256:2db2997dd124dc9361b9d3228925df9e51281af9529c26187a865407588f8abb", size = 12302942, upload-time = "2026-03-19T14:27:32.009Z" },
-    { url = "https://files.pythonhosted.org/packages/be/68/335dfbb7efc972964f0610736a0ad243dd8a5dcc2ec76b9ddb84c847a4a4/zensical-0.0.23-cp310-abi3-macosx_11_0_arm64.whl", hash = "sha256:5973267460a190f348f24d445ff0c01e8ed334fd075947687b305e68257f6b18", size = 12125173, upload-time = "2026-02-11T21:24:08.507Z" },
+    { url = "https://files.pythonhosted.org/packages/10/aa/c10fcbee69bcca8a545b1a868e3fec2560b984f68e91cbbce3eaee0814ff/zensical-0.0.28-cp310-abi3-macosx_11_0_arm64.whl", hash = "sha256:5c6e5ea5c057492a1473a68f0e71359d663057d7d864b32a8fd429c8ea390346", size = 12186436, upload-time = "2026-03-19T14:27:34.866Z" },
-    { url = "https://files.pythonhosted.org/packages/25/9c/d567da04fbeb077df5cf06a94f947af829ebef0ff5ca7d0ba4910a6cbdf6/zensical-0.0.23-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:953adf1f0b346a6c65fc6e05e6cc1c38a6440fec29c50c76fb29700cc1927006", size = 12489636, upload-time = "2026-02-11T21:24:10.91Z" },
+    { url = "https://files.pythonhosted.org/packages/c2/ea/d0aaa0f0ed1b7a69aeec5f25ce2ff2ea7b13e581c9115d51a4a50bc7bf57/zensical-0.0.28-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:d2ee8a1d29b61de61e6b0f9123fa395c06c24c94e509170c7f7f9ccddaeaaad4", size = 12545239, upload-time = "2026-03-19T14:27:37.613Z" },
-    { url = "https://files.pythonhosted.org/packages/fe/6e/481a3ecf8a7b63a35c67f5be1ea548185d55bb1dacead54f76a9550197b2/zensical-0.0.23-cp310-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:49c1cbd6131dafa056be828e081759184f9b8dd24b99bf38d1e77c8c31b0c720", size = 12421313, upload-time = "2026-02-11T21:24:13.9Z" },
+    { url = "https://files.pythonhosted.org/packages/d9/b1/508ea4de8b5c93a2ceb4d536314041a19a520866a5ce61c55d64417afaa9/zensical-0.0.28-cp310-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:7cef68b363c0d3598d37a1090bfc5c6267e36a87a55e9fb6a6f9d7f2768f1dfd", size = 12488943, upload-time = "2026-03-19T14:27:40.663Z" },
-    { url = "https://files.pythonhosted.org/packages/ba/aa/a95481547f708432636f5f8155917c90d877c244c62124a084f7448b60b2/zensical-0.0.23-cp310-abi3-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:f5b7fe22c5d33b2b91899c5df7631ad4ce9cccfabac2560cc92ba73eafe2d297", size = 12761031, upload-time = "2026-02-11T21:24:17.016Z" },
+    { url = "https://files.pythonhosted.org/packages/1d/35/9c1878845dfcec655f538ef523c606e585d38b84415d65009b83ebc356b2/zensical-0.0.28-cp310-abi3-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:f3175440fd526cf0273859d0de355e769ba43e082e09deb04b6f6afd77af6c91", size = 12840468, upload-time = "2026-03-19T14:27:43.758Z" },
-    { url = "https://files.pythonhosted.org/packages/c1/9f/ce1c5af9afd11fe3521a90441aba48c484f98730c6d833d69ee4387ae2e9/zensical-0.0.23-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:9a3679d6bf6374f503afb74d9f6061da5de83c25922f618042b63a30b16f0389", size = 12527415, upload-time = "2026-02-11T21:24:19.558Z" },
+    { url = "https://files.pythonhosted.org/packages/d0/1f/50f0ca6db76dc7888f9e0f0103c8faaaa6ee25a2c1e3664f2db5cc7bf24b/zensical-0.0.28-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:0887436c5fd8fe7008c0d93407876695db67bcf55c8aec9fb36c339d82bb7fce", size = 12591152, upload-time = "2026-03-19T14:27:46.629Z" },
-    { url = "https://files.pythonhosted.org/packages/a8/b8/13a5d4d99f3b77e7bf4e791ef991a611ca2f108ed7eddf20858544ab0a91/zensical-0.0.23-cp310-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:54d981e21a19c3dcec6e7fa77c4421db47389dfdff20d29fea70df8e1be4062e", size = 12665352, upload-time = "2026-02-11T21:24:22.703Z" },
+    { url = "https://files.pythonhosted.org/packages/f1/6b/621b7031c24c9fb0d38c2c488d79d73fcc2e645330c27fbab4ecccc06528/zensical-0.0.28-cp310-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:b8a0ca92e04687f71aa20c9ae80fe8b840125545657e6b7c0f83adecd04d512e", size = 12723744, upload-time = "2026-03-19T14:27:50.101Z" },
-    { url = "https://files.pythonhosted.org/packages/ad/84/3d0a187ed941826ca26b19a661c41685d8017b2a019afa0d353eb2ebbdba/zensical-0.0.23-cp310-abi3-musllinux_1_2_armv7l.whl", hash = "sha256:afde7865cc3c79c99f6df4a911d638fb2c3b472a1b81367d47163f8e3c36f910", size = 12689042, upload-time = "2026-02-11T21:24:26.118Z" },
+    { url = "https://files.pythonhosted.org/packages/8d/89/a8bdd6a8423e0bb4f8792793681cbe101cdfbb1e0c1128b3226afe53af5f/zensical-0.0.28-cp310-abi3-musllinux_1_2_armv7l.whl", hash = "sha256:acb31723ca82c367d1c41a6a7b0f52ce1ed87f0ee437de2ee2fc2e284e120e44", size = 12760416, upload-time = "2026-03-19T14:27:52.667Z" },
-    { url = "https://files.pythonhosted.org/packages/f0/65/12466408f428f2cf7140b32d484753db0891debae3c956f4c076b51eeb17/zensical-0.0.23-cp310-abi3-musllinux_1_2_i686.whl", hash = "sha256:c484674d7b0a3e6d39db83914db932249bccdef2efaf8a5669671c66c16f584d", size = 12834779, upload-time = "2026-02-11T21:24:28.788Z" },
+    { url = "https://files.pythonhosted.org/packages/86/07/af4ec58b63a14c0fb6b21c8c875f34effa71d4258530a3e3d301b1c518b9/zensical-0.0.28-cp310-abi3-musllinux_1_2_i686.whl", hash = "sha256:3680b3a75560881e7fa32b450cf6de09895680b84d0dd2b611cb5fa552fdfc49", size = 12907390, upload-time = "2026-03-19T14:27:56.71Z" },
-    { url = "https://files.pythonhosted.org/packages/a9/ab/0771ac6ffb30e4f04c20374e3beca9e71c3f81112219cdbd86cdc0e3d337/zensical-0.0.23-cp310-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:927d12fe2851f355fb3206809e04641d6651bdd2ff4afe9c205721aa3a32aa82", size = 12797057, upload-time = "2026-02-11T21:24:31.383Z" },
+    { url = "https://files.pythonhosted.org/packages/61/70/1b3f319ac2c05bdcd27ae73ae315a893683eb286a42a746e7e572e2675f6/zensical-0.0.28-cp310-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:93e1bc47981b50bcd9c4098edc66fb86fd881c5b52b355db92dcef626cc0b468", size = 12864434, upload-time = "2026-03-19T14:28:00.443Z" },
-    { url = "https://files.pythonhosted.org/packages/4b/ce/fbd45c00a1cba15508ea3c29b121b4be010254eb65c1512bf11f4478496c/zensical-0.0.23-cp310-abi3-win32.whl", hash = "sha256:ffb79db4244324e9cc063d16adff25a40b145153e5e76d75e0012ba3c05af25d", size = 11837823, upload-time = "2026-02-11T21:24:33.869Z" },
+    { url = "https://files.pythonhosted.org/packages/8b/21/be7c94b25e0f4281a6b5fbd471236e33c44b832a830fedad40a6c119f290/zensical-0.0.28-cp310-abi3-win32.whl", hash = "sha256:eee014ca1290463cf8471e3e1b05b7c627ac7afa0881635024d23d4794675980", size = 11888008, upload-time = "2026-03-19T14:28:03.565Z" },
-    { url = "https://files.pythonhosted.org/packages/37/82/0aebaa8e7d2e6314a85d9b7ff3f7fc74837a94086b56a9d5d8f2240e9b9c/zensical-0.0.23-cp310-abi3-win_amd64.whl", hash = "sha256:a8cfe240dca75231e8e525985366d010d09ee73aec0937930e88f7230694ce01", size = 12036837, upload-time = "2026-02-11T21:24:36.163Z" },
+    { url = "https://files.pythonhosted.org/packages/de/88/5ce79445489edae6c1a3ff9e06b4885bea5d8e8bb8e26e1aa1b24395c337/zensical-0.0.28-cp310-abi3-win_amd64.whl", hash = "sha256:6077a85ee1f0154dbfe542db36789322fe8625d716235a000d4e0a8969b14175", size = 12094496, upload-time = "2026-03-19T14:28:06.311Z" },
 ]

zensical.toml

@@ -77,6 +77,10 @@ md_in_html = {}
 "pymdownx.tasklist" = {custom_checkbox = true}
 "pymdownx.tilde" = {}
 
+[project.markdown_extensions.pymdownx.emoji]
+emoji_index = "zensical.extensions.emoji.twemoji"
+emoji_generator = "zensical.extensions.emoji.to_svg"
+
 [project.markdown_extensions."pymdownx.highlight"]
 anchor_linenums = true
 line_spans = "__span"
@@ -95,3 +99,49 @@ permalink = true
 [project.markdown_extensions."pymdownx.snippets"]
 base_path = ["."]
 check_paths = true
+
+[[project.nav]]
+Home = "index.md"
+
+[[project.nav]]
+Modules = [
+    {CLI = "module/cli.md"},
+    {CRUD = "module/crud.md"},
+    {Database = "module/db.md"},
+    {Dependencies = "module/dependencies.md"},
+    {Exceptions = "module/exceptions.md"},
+    {Fixtures = "module/fixtures.md"},
+    {Logger = "module/logger.md"},
+    {Metrics = "module/metrics.md"},
+    {Models = "module/models.md"},
+    {Pytest = "module/pytest.md"},
+    {Schemas = "module/schemas.md"},
+]
+
+[[project.nav]]
+Reference = [
+    {CLI = "reference/cli.md"},
+    {CRUD = "reference/crud.md"},
+    {Database = "reference/db.md"},
+    {Dependencies = "reference/dependencies.md"},
+    {Exceptions = "reference/exceptions.md"},
+    {Fixtures = "reference/fixtures.md"},
+    {Logger = "reference/logger.md"},
+    {Metrics = "reference/metrics.md"},
+    {Models = "reference/models.md"},
+    {Pytest = "reference/pytest.md"},
+    {Schemas = "reference/schemas.md"},
+]
+
+[[project.nav]]
+Examples = [
+    {"Pagination & Search" = "examples/pagination-search.md"},
+]
+
+[[project.nav]]
+Migration = [
+    {"v2.0" = "migration/v2.md"},
+]
+
+[[project.nav]]
+"Changelog ↗" = "https://github.com/d3vyce/fastapi-toolsets/releases"