API Reference¶

Public imports¶

from schemap import (
    auto_schema,
    AutoBase,
    SchemaMixin,
    SchemaConfig,
    ArchivableMixin,
    CreatedByMixin,
    IntPrimaryKeyMixin,
    SoftDeleteMixin,
    StatusMixin,
    TimestampMixin,
    UUIDPrimaryKeyMixin,
    UpdatedByMixin,
    VersionMixin,
)
from schemap import build_schema

AutoBase¶

Ready-to-use declarative base with auto-generated schemas.

class AutoBase(SchemaMixin, DeclarativeBase)

SchemaMixin¶

Mixin that adds four schema class properties and two conversion methods.

Class properties:

• Schema -- Full schema with all columns.
• CreateSchema -- Excludes PKs, server_defaults, defaults.
• UpdateSchema -- All fields Optional with None default.
• PublicSchema -- Excludes __-prefixed columns.

Schemas are cached per class via cached_classproperty.

Methods:

• from_schema(cls, schema_obj) -- Create ORM instance from Pydantic schema. Uses model_dump(exclude_none=True).
• to_schema(self, schema_cls=None) -- Convert ORM instance to schema. Defaults to .Schema.

Configuration:

Set __schema_config__ = SchemaConfig(...) on any model class to customize its schemas.

auto_schema¶

Decorator that attaches generated schemas to any SQLAlchemy model without changing its base class.

def auto_schema(
    cls: type[T] | None = None,
    *,
    config: SchemaConfig | None = None,
) -> type[T]

Usage:

from schemap import auto_schema, SchemaConfig

# Bare decorator — all defaults
@auto_schema
class User(Base):
    __tablename__ = "users"
    ...

# With config
@auto_schema(config=SchemaConfig(exclude_public=["email"]))
class User(Base):
    ...

Attaches .Schema, .CreateSchema, .UpdateSchema, .PublicSchema, .from_schema(), and .to_schema() to the decorated class. Works with any DeclarativeBase subclass. All three approaches (AutoBase, SchemaMixin, @auto_schema) produce identical schemas.

Schema types: "full" (all columns), "create" (excludes PKs and defaults), "update" (all optional), "public" (excludes __-prefixed columns).

SchemaConfig¶

Dataclass for per-model schema customization. All fields are optional.

• exclude_always: list[str] = []
• exclude_create: list[str] = []
• exclude_update: list[str] = []
• exclude_public: list[str] = []
• field_overrides: dict[str, Any] = {}
• required_always: list[str] = []
• optional_always: list[str] = []
• extra_validators: dict[str, Callable] = {}

build_schema¶

def build_schema(
    model: type[DeclarativeBase],
    schema_type: str = "default",
    config: SchemaConfig | None = None,
) -> type[BaseModel]

Build a Pydantic schema class for any SQLAlchemy model without using AutoBase.

schema_type values: "default", "full", "create", "update", "public".

from schemap import build_schema, SchemaConfig

UserSchema = build_schema(User, "default")
UserCreateSchema = build_schema(User, "create", config=SchemaConfig(exclude_create=["internal_id"]))

Type mapping¶