strawberry-chemist 0.2.2

Strawberry GraphQL helpers for SQLAlchemy models.

strawberry-chemist

strawberry-chemist helps expose SQLAlchemy models through Strawberry without turning your GraphQL schema into generated magic.

The package is intentionally explicit. You still write the Strawberry types you want clients to see. That makes the DTO layer visible, keeps the public contract adaptable, and fits production codebases that care about query shape, permissions, loading behavior, and long-term schema maintenance.

That explicitness does not mean giving up performance. Chemist-managed relationship and connection fields are selection-aware and dataloader-backed, so you can keep explicit DTOs without falling into per-parent N+1 loading.

Chemist focuses on the parts that are repetitive and SQLAlchemy-aware:

• field mapping and renaming
• relationship loading
• root and nested connections
• filtering, ordering, and pagination
• relay IDs and node lookup
• dataloaders and selection-aware loading

Relationships and connections are also deliberately flexible. They can be:

• plain mapped fields
• renamed fields
• server-scoped fields
• relationship-backed computed fields
• root collections
• relationship-backed collections with filtering, ordering, and pagination

Installation

pip install strawberry-chemist

Quick example

import strawberry
import strawberry_chemist as sc


@sc.node(model=BookModel)
class Book:
    title: str
    published_year: int = sc.attr("year")


@sc.filter(model=BookModel)
class BookFilter(sc.FilterSet):
    title: sc.StringFilter = sc.filter_field()


@sc.order(model=BookModel)
class BookOrder:
    published_year = sc.order_field(path="year")


@strawberry.type
class Query:
    node = sc.node_field()
    books: sc.Connection[Book] = sc.connection(
        filter=BookFilter,
        order=BookOrder,
        pagination=sc.CursorPagination(max_limit=20),
    )


schema = strawberry.Schema(query=Query, extensions=sc.extensions())

Your GraphQL context must provide a get_session() async context manager that returns a SQLAlchemy AsyncSession.

Public docs

The public docs live in docs/. The published site is intended for GitHub Pages and is built with MkDocs.

Useful entrypoints:

• Overview
• Getting Started
• API Surface
• Examples

Serve the docs locally:

uv sync --group dev
uv run mkdocs serve

Build the docs locally:

uv run mkdocs build --strict

Runnable examples

Serve a seeded sample schema locally:

uv sync --group dev
make example-serve EXAMPLE=03_connections_filters_and_ordering PORT=8000

The contract examples tests under examples/ can run in two modes.

Against the current checkout:

make example-test EXAMPLE=03_connections_filters_and_ordering

Against the pinned published package:

make example-test-published EXAMPLE=03_connections_filters_and_ordering

Print a sample schema:

make example-schema EXAMPLE=03_connections_filters_and_ordering

If you want to force published-mode testing against a locally built distribution, point the script at a build output directory:

uv run python -m build --outdir /tmp/strawberry-chemist-dist
STRAWBERRY_CHEMIST_FIND_LINKS=/tmp/strawberry-chemist-dist \
  scripts/run-example-published 03_connections_filters_and_ordering

API overview

• Types and fields: @sc.type, @sc.node, sc.attr, @sc.field
• Relationships: sc.relationship(...)
• Collections: sc.connection(...), sc.Connection, sc.OffsetConnection
• Pagination: sc.CursorPagination, sc.OffsetPagination, sc.PaginationPolicy
• Filters: @sc.filter, sc.FilterSet, sc.filter_field, sc.manual_filter
• Ordering: @sc.order, sc.order_field, sc.manual_order
• Relay: sc.node_field(), sc.node_lookup(...)
• Schema integration: sc.extensions()

Each part of the surface has a dedicated public docs page and at least one example reference in docs/examples.md.

Development

Run the default non-Postgres test suite with either:

uv run pytest
make test

Run formatting and type checks:

uv run pre-commit run --all-files
uv run mypy
make mypy
make check

Release notes live in CHANGELOG.md. Current limitations are documented in LIMITATIONS.md.