Quickstart¶

This page takes you from zero to persisting objects. We start with no backend at all, then bind to SQLAlchemy.

Without a backend (NoOpMateria)¶

The default NoOpMateria is active automatically — define transmuters and use them like regular Pydantic models, no setup required. Great for tests and prototyping.

from arcanus.base import BaseTransmuter, Identity
from arcanus.association import (
    Relation,
    RelationCollection,
    Relationship,
    Relationships,
)
from pydantic import Field
from typing import Annotated, Optional


class Author(BaseTransmuter):
    id: Annotated[Optional[int], Identity] = Field(default=None, frozen=True)
    name: str

    books: RelationCollection["Book"] = Relationships()


class Book(BaseTransmuter):
    id: Annotated[Optional[int], Identity] = Field(default=None, frozen=True)
    title: str
    author_id: int | None = None

    author: Relation[Author] = Relationship()


author = Author(id=1, name="Isaac Asimov")
book = Book(id=1, title="Foundation", author=Relation(author))

print(book.author.value.name)  # Isaac Asimov
print(list(author.books))  # [Book(...)]

With SQLAlchemy¶

1. Define ORM models¶

Your SQLAlchemy models are plain, untouched SQLAlchemy:

from sqlalchemy import ForeignKey, Integer, String
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, relationship


class Base(DeclarativeBase): ...


class AuthorModel(Base):
    __tablename__ = "authors"
    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
    name: Mapped[str] = mapped_column(String(100))
    books: Mapped[list["BookModel"]] = relationship(back_populates="author")


class BookModel(Base):
    __tablename__ = "books"
    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
    title: Mapped[str] = mapped_column(String(200))
    author_id: Mapped[int] = mapped_column(ForeignKey(AuthorModel.id))
    author: Mapped[AuthorModel] = relationship(back_populates="books")

2. Bind transmuters with `bless()`¶

from arcanus.base import BaseTransmuter, Identity
from arcanus.association import (
    Relation,
    RelationCollection,
    Relationship,
    Relationships,
)
from arcanus.materia.sqlalchemy import SqlalchemyMateria
from pydantic import Field
from typing import Annotated, Optional

materia = SqlalchemyMateria()


@materia.bless(AuthorModel)
class Author(BaseTransmuter):
    id: Annotated[Optional[int], Identity] = Field(default=None, frozen=True)
    name: str
    books: RelationCollection["Book"] = Relationships()


@materia.bless(BookModel)
class Book(BaseTransmuter):
    id: Annotated[Optional[int], Identity] = Field(default=None, frozen=True)
    title: str
    author_id: int | None = None
    author: Relation[Author] = Relationship()

3. Use the arcanus `Session`¶

Important

Use arcanus.materia.sqlalchemy.Session (not SQLAlchemy's native Session). The arcanus session automatically "blesses" ORM rows into transmuters as they come out of queries.

from sqlalchemy import create_engine
from arcanus.materia.sqlalchemy import Session

engine = create_engine("sqlite://")
Base.metadata.create_all(engine)

Create¶

Adding the book cascades to its author. After a flush, server-generated ids are synced back onto the transmuters automatically.

with Session(engine) as session:
    author = Author(name="Isaac Asimov")
    book = Book(title="Foundation", author=Relation(author))

    session.add(book)  # adding the book also adds its author
    session.flush()  # INSERT; server-generated ids synced to the transmuters
    session.commit()
    print(book.id)  # e.g. 1

Read¶

Every result is a transmuter, not a raw ORM row. Reads are plain SQLAlchemy — session.get and session.execute(select(...)) — and typed column references (Author["name"]) drop straight into a select.

from sqlalchemy import select

with Session(engine) as session:
    author = session.get_one(Author, 1)  # by primary key (raises if missing)

    author = session.execute(  # by filter
        select(Author).filter_by(name="Isaac Asimov")
    ).scalar_one()

    authors = (
        session.execute(  # many, with filter + ordering + paging
            select(Author)
            .where(Author["name"].like("Isaac%"))
            .order_by(Author["name"].asc())
            .limit(10)
        )
        .scalars()
        .all()
    )

    books = (
        session.execute(select(Book).where(Book["title"].like("Found%")))
        .scalars()
        .all()
    )

Typed shortcuts

For common reads, Arcanus also adds typed helpers to the session — one, first, list, count, bulk, partitions — so the above can be one-liners. See Session Helpers.

Navigate relationships¶

Related rows load on access and keep their identity.

with Session(engine) as session:
    author = session.get_one(Author, 1)
    for book in author.books:  # loads on access
        assert book.author.value is author  # same instance — identity preserved

Update & delete¶

Mutating a transmuter syncs to its ORM row in place — no model_dump() round-trip.

with Session(engine) as session:
    book = session.get_one(Book, 1)
    book.title = "Foundation (Revised)"  # synced to the ORM row
    session.commit()

    session.delete(book)  # follows your ORM cascade rules
    session.commit()

Partial models at the boundary¶

Generated .Create / .Update models validate incomplete payloads; shell() / absorb() move between a partial and a full transmuter.

Experimental — for API boundaries (e.g. FastAPI)

The .Create / .Update partials are experimental (the generated surface may change). They exist for request/response boundaries — validating untrusted, incomplete bodies in a FastAPI handler and the like. If you're just working with objects in memory, you don't need them: construct and mutate the transmuter directly.

with Session(engine) as session:
    author = Author.shell(Author.Create(name="New Author"))  # Create excludes the id
    session.add(author)
    session.flush()  # id synced back automatically

    author.absorb(Author.Update(name="Renamed"))  # applies only what's set
    session.commit()

Async¶

Swap Session for AsyncSession and await the I/O — the API is otherwise identical. Awaiting a relationship triggers its lazy load. See Lifecycle & Async.

from sqlalchemy.ext.asyncio import create_async_engine
from arcanus.materia.sqlalchemy import AsyncSession

async with AsyncSession(create_async_engine("sqlite+aiosqlite://")) as session:
    author = await session.get_one(Author, 1)
    books = await author.books  # awaits the lazy load → list[Book]

    session.add(Book(title="Async Book", author=Relation(author)))
    await session.commit()

Next¶

Usage — the full guide, grouped by materia: relationships, loading, querying, and partial schemas in depth.
The Materia System — what bless() does and the design philosophy.
API Reference.