Skip to content

# `models`

Here's the reference for the SQLAlchemy model mixins provided by the `models` module.

You can import them directly from `fastapi_toolsets.models`:

    from fastapi_toolsets.models import (
        ModelEvent,
        UUIDMixin,
        UUIDv7Mixin,
        CreatedAtMixin,
        UpdatedAtMixin,
        TimestampMixin,
        WatchedFieldsMixin,
        watch,
    )

## `fastapi_toolsets.models.ModelEvent`

Bases: `str`, `Enum`

Event types emitted by :class:`WatchedFieldsMixin`.

## `fastapi_toolsets.models.UUIDMixin`

Mixin that adds a UUID primary key auto-generated by the database.

## `fastapi_toolsets.models.UUIDv7Mixin`

Mixin that adds a UUIDv7 primary key auto-generated by the database.

## `fastapi_toolsets.models.CreatedAtMixin`

Mixin that adds a `created_at` timestamp column.

## `fastapi_toolsets.models.UpdatedAtMixin`

Mixin that adds an `updated_at` timestamp column.

## `fastapi_toolsets.models.TimestampMixin`

Bases: `CreatedAtMixin`, `UpdatedAtMixin`

Mixin that combines `created_at` and `updated_at` timestamp columns.

## `fastapi_toolsets.models.WatchedFieldsMixin`

Mixin that enables lifecycle callbacks for SQLAlchemy models.

### `on_create()`

Called after INSERT commit.

### `on_delete()`

Called after DELETE commit.

### `on_event(event, changes=None)`

Catch-all callback fired for every lifecycle event.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`event` | `ModelEvent` | The event type (:attr:`ModelEvent.CREATE`, :attr:`ModelEvent.DELETE`, or :attr:`ModelEvent.UPDATE`). | required
`changes` | `dict[str, dict[str, Any]] | None` | Field changes for :attr:`ModelEvent.UPDATE`, `None` otherwise. | `None`

### `on_update(changes)`

Called after UPDATE commit when watched fields change.

## `fastapi_toolsets.models.watch(*fields)`

Class decorator to filter which fields trigger `on_update`.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`*fields` | `str` | One or more field names to watch. At least one name is required. | `()`

Raises:

Type | Description
--- | ---
`ValueError` | If called with no field names.