Metadata-Version: 2.4
Name: strawberry-chemist
Version: 0.2.1
Summary: Strawberry GraphQL helpers for SQLAlchemy models.
Project-URL: Homepage, https://github.com/MeRuslan/strawberry-chemist
Project-URL: Repository, https://github.com/MeRuslan/strawberry-chemist
Project-URL: Issues, https://github.com/MeRuslan/strawberry-chemist/issues
Project-URL: Changelog, https://github.com/MeRuslan/strawberry-chemist/blob/main/CHANGELOG.md
Project-URL: Documentation, https://meruslan.github.io/strawberry-chemist/
Author: strawberry-chemist contributors
License: MIT License
        
        Copyright (c) 2026 strawberry-chemist contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: async,graphql,sqlalchemy,strawberry
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Database
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: bidict>=0.23.1
Requires-Dist: graphql-core>=3.2.6
Requires-Dist: greenlet>=3.2.2
Requires-Dist: sqlalchemy>=2.0.41
Requires-Dist: strawberry-graphql~=0.311.1
Description-Content-Type: text/markdown

# 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

```bash
pip install strawberry-chemist
```

Supported Python versions:

- `3.11`
- `3.12`

## Quick example

```python
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/](docs/). The published site is intended for
GitHub Pages and is built with MkDocs.

Useful entrypoints:

- [Overview](docs/index.md)
- [Getting Started](docs/getting-started.md)
- [API Surface](docs/api-surface.md)
- [Examples](docs/examples.md)

Serve the docs locally:

```bash
uv sync --group dev
uv run mkdocs serve
```

Build the docs locally:

```bash
uv run mkdocs build --strict
```

## Runnable examples

The contract examples under `examples/v0_2_api/` can run in two modes.

Against the current checkout:

```bash
scripts/run-example-local 03_connections_filters_and_ordering
```

Against the pinned published package:

```bash
scripts/run-example-published 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:

```bash
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](docs/examples.md).

## Development

Run the default non-Postgres test suite:

```bash
uv run pytest
```

Run formatting and type checks:

```bash
uv run pre-commit run --all-files
uv run mypy
```

Release notes live in [CHANGELOG.md](CHANGELOG.md). Current limitations are
documented in [LIMITATIONS.md](LIMITATIONS.md).
