resourcey
A resource-oriented Python web framework built on FastAPI, SQLAlchemy, and Alembic — progressive enhancement with escape hatches to the underlying stack.
Installation
pip install resourcey
uv add resourcey
Optional extras pull in a driver for the parts you use:
| Extra | Adds | For |
|---|---|---|
resourcey[mongodb] |
motor |
the Mongo backend |
resourcey[s3] |
boto3 |
the S3 file-store medium |
resourcey[redis] |
redis |
RedisTrigger / RedisChannel |
resourcey[webhooks] |
httpx |
WebhookTrigger |
resourcey[dev] |
pytest, ruff, mypy, test drivers | working on resourcey itself |
Why?
Most web frameworks either hide the database entirely or make you wire every
layer by hand. resourcey takes a middle path: you declare a resource
with enough metadata to describe how it should be stored, validated, and
exposed, and the framework generates a service for you. When the abstraction
gets in the way, you drop back a rung — to FastAPI, SQLAlchemy, or Alembic —
and nothing breaks.
The guiding principles:
- Resource-oriented. A resource is the central unit. Define it once — for SQL, by declaring your SQLAlchemy model — and derive the DTO, the REST models, the service, and the permission checks from that single declaration.
- Progressive enhancement. Each layer is opt-in. Use the generated service, or write your own route that calls the repository directly, or query SQLAlchemy yourself. The layers compose; they don't trap you.
- Escape hatches. FastAPI, SQLAlchemy, and Alembic are first-class citizens, not implementation details. You can always reach them.
What a resource gives you
Declaring a resource produces:
- A REST service exposing the standard actions:
create,read,update,delete,search,count,batch_read, plus one app-levelPOST /batch-editspanning every resource. - Pydantic models for request/response validation, projected from the resource's DTO declaration — create / update / read / search shapes, never hand-written.
- Persistence, from whichever backend you declared it against. For SQL the workflow is model-first: your SQLAlchemy model is the schema of record and the DTO is inferred from it, so the mapping you already write stays authoritative (and Alembic autogenerates from that same metadata). The Mongo and list backends are DTO-first, since they have no schema of record.
- Search filtering —
searchandcountaccept<field>__<op>query params (?title__contains=ali&id__gt=5). A field is filterable exactly when the read model exposes it, so a hidden field is rejected400; a resource can declare a richer filter viaget_search_filter_type. Filters lower to a storage-agnostic tree and are pushed into the SQLWHEREclause; an unconvertible filter fails loudly unless the resource opts into an in-memory fallback. - Sorting and cursor paging —
?sort=<field>&desc=trueover any sortable (i.e. readable) field, with opaque keyset cursors instead ofoffset. - Caching — an
ETag/Last-Modifiedstrategy chosen from the resource's shape, markedprivatewhenever a response is caller-scoped. - Authorization — pluggable
Policyrules reduce a principal to a per-action filter: API-key / cookie authentication, per-app roles, and a stored users / groups / roles RBAC store.
Storage backends
A resource is declared against one of three backends; the action contract, paging, sort, filters, and cache headers are identical across all three.
| Backend | Base class | Storage |
|---|---|---|
| SQL | resourcey.sql.sql_resource.SqlResource |
SQLAlchemy 2 (async) table |
| Mongo | resourcey.mongo.mongo_resource.MongoResource |
an async motor collection |
| List | resourcey.list.list_resource.ListResource |
an in-process list of Pydantic objects |
(There are no __init__.py re-exports, so import from the module that defines
the class — from resourcey.sql.sql_resource import SqlResource.)
A list-backed resource is read-only: it narrows its actions to
read / search / count / batch_read and serves data already modelled as
Pydantic objects (country codes, feature flags, catalog entries) without
copying it into a table. Because the objects already exist as Pydantic models,
there is no schema generation — the model is projected onto the DTO the REST
shapes derive from, and (being read-only) there is no create/update model and
no columns. The list is the storage, so there is no table and no migration.
from pydantic import BaseModel
from resourcey.core.manifest import Manifest
from resourcey.list.list_resource import ListResource
class Country(BaseModel):
id: str
name: str
iso3: str
countries = [
Country(id="us", name="United States", iso3="USA"),
Country(id="ca", name="Canada", iso3="CAN"),
]
resource = ListResource(countries, path="countries")
manifest = Manifest(resources=(resource,))
That manifest serves GET /countries (search), GET /countries/count,
GET /countries/batch-read, and GET /countries/{id} — and nothing else: a
write route is never mounted, so a POST is a 405.
defensive=True is the default: every object the resource outputs is a deep
copy of the stored object, so a caller cannot mutate the served collection
through a result. Pass defensive=False to serve the stored objects directly.
The core package — DTO, Resource, Service, Manifest
src/resourcey/core/ is a deliberately minimal package that states the
architecture in terms of a DTO, a Resource, a Service, and a
Manifest. It is the foundation every backend and transport layer is built
on.
The split separates the DTO (the data object you work with internally) from the six REST models (the wire shapes), which the older code entangled, and does away with six hand-written models per resource — those are now derived.
Here is a whole manifest against the SQL backend — the ORM models are the only declarations:
from sqlalchemy import ForeignKey
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
from resourcey.core.manifest import Manifest
from resourcey.sql.sql_resource import SqlResource
class Base(DeclarativeBase):
pass
class Thread(Base):
__tablename__ = "threads"
id: Mapped[int] = mapped_column(primary_key=True)
title: Mapped[str]
class Message(Base):
__tablename__ = "messages"
id: Mapped[int] = mapped_column(primary_key=True)
thread_id: Mapped[int] = mapped_column(ForeignKey("threads.id"))
body: Mapped[str]
manifest = Manifest(resources=(SqlResource(Thread), SqlResource(Message)))
From those two classes create_app(manifest) serves POST /threads and
GET /threads (search), GET|PATCH|DELETE /threads/{id}, GET /threads/count,
and GET /threads/batch-read — and the same set for messages — plus
POST /batch-edit, which spans both resources, and the OpenAPI docs.
POST /batch-edit takes one ordered list of create / update / delete
nodes, each naming its target resource, and answers with a positionally aligned
list. Nodes apply in the order given, so a later node sees an earlier node's
write. The first failure aborts the batch; rollback is best effort, holding
wherever the backend provides a shared transaction (SQL resources on one
session factory roll back together). It is mounted by default — pass
create_app(manifest, batch_edit=False) to turn it off, or
batch_edit_path="/ops/edits" to move it. The node count is capped by
batch_edit_max_edits, which defaults to RequestLimitsConfig.max_batch_edits
(APP_MAX_BATCH_EDITS, 100). A resource opts out by declaring no write action,
and a hidden resource is never reachable through it. It is the only batch
write surface: there is no per-resource /batch-edit, and each node is
authorized against its own singular action.
SQLAlchemy is the schema of record: the DTO and the six REST models are inferred from the ORM model, so a developer keeps the mapping they already write. The Mongo backend is DTO-first instead (there is no schema of record); see its section below.
The five files:
-
dto.py— aDTOis a plain declaration class (not a Pydantic model). Fields carry ordinary Pydantic annotations plus aDtoFielddescribing how each projects into the six REST shapes via sixin_*flags (in_create_request,in_create_response,in_update_request,in_update_response,in_read_response,in_search_response— all defaultTrue, superseding the oldercreatable/updatable/readabletriple). Tag a field withAnnotated[T, DtoField(...)]— the canonical Pydantic mechanism; it keeps the real field type (the assignment formkey: str = DtoField(...)is a type error undermypy --strict), and no explicit| Missingis needed because the generator widens every field itself:class MyStoredKey(DTO): id: Annotated[ UUID, DtoField( in_create_request=False, in_update_request=False, default_factory_for_create=uuid4 ), ] key: Annotated[str, DtoField(in_read_response=False)] description: Annotated[str | None, DtoField(default_for_create=None)] created_at: Annotated[ datetime, DtoField( in_create_request=False, in_update_request=False, default_factory_for_create=utc_now ), ] updated_at: Annotated[ datetime, DtoField( in_create_request=False, in_update_request=False, default_factory_for_create=utc_now, default_factory_for_update=utc_now, ), ]
DtoFieldcarries operation-scoped defaults (default_for_create/default_factory_for_createanddefault_for_update/default_factory_for_update), whose precedence is client value → default for that operation →MISSING. Create and update do not want the same default: an omitted update field with no update default is left unchanged (PATCH semantics), while anin_update_request=Falsefield is always omitted and so always takes its update default (the "always overwrite" case — howupdated_atis re-set on every update whilecreated_atis written once). Optionality is never inferred from the annotation: a nullable field with no create default is required on create.DTO.__init_subclass__applies theid/ timestamp conventions and wraps every field asann | Missingdefaulting toMISSING, so an omitted field is distinguishable from an explicitNone. The create request carries concrete defaults; the update request keeps theMISSINGsentinel on the wire boundary so an omitted field is distinguishable from an explicitnull, and the route converts a request into a DTO through the single sanctioned hop (request_to_dto, i.e.model_dump(exclude_unset=True)+model_validate).Missingis a usable annotation type (it carries a Pydantic core schema and serializes tonull), soUUID | Missingvalidates. The six REST models are field-selection projections of the DTO — never hand-written — and the one-time-reveal case (keyin the create response only) is expressible. BothDTOandDtoFieldcarry a free-formmetadata: dict[str, Any], a general-purpose store for extra data thatcorenever reads. A DTO's metadata is inherited and merged down the MRO and is not a field; aDtoField's metadata is per-field and excluded from equality/hash, so differing metadata never churns the derived models.DTO.id_field_nameselects the identifier —idby default, overridable with theid_field_name=class keyword to make another declared field the identifier (a natural key). It is validated at declaration time: a name with no matching field raisesTypeError. The identifier is always immutable (never in an update request); the conventionalidis also server-generated in the SQL backend and so excluded from create requests, while a custom identifier stays client-supplied on create, e.g.class Country(DTO, id_field_name="code")with acode: strfield. -
resource.py—Resourceis a genuine ABC: every method is abstract, socoreholds no backend behaviour and a backend supplies the whole contract. It is generic over the DTO and the identifier type (Resource[T, K]).get_service(ctx)is async and takes an optional call-scopedMutableMapping; awaiting it builds the service (a backend may resolve a connection first) and the returnedServiceis the async context manager that owns the storage, so the call site isasync with await resource.get_service(ctx).get_supported_actions()is the single action declaration (there is noactionsproperty), andget_exposed_resource()composes on top of it — the exposed resource's declaration wins outright. -
service.py—Serviceis generic over the DTO, declares the eight actions, and is the async context manager; a call before__aenter__raises clearly.Actionis the action enum,Editthe create/update/delete union, andForbiddenError/NotFoundError/ServiceErrorlive here. -
errors.py— the framework error baseResourceyErrorand the storage-neutral errors a backend raises and the transport maps:ResourceyConfigError,InvalidInputError,UnsupportedFilterError,ConflictError. -
manifest.py— theManifestowns the resource set and its lifecycle (it may also own app-lifecycle managers, e.g. aSqlSessionManager, entered before the resources and exited after them), and asserts at construction that every resource's supported actions name only realActionmembers (a typo would otherwise silently drop a route).
Storage ownership follows one rule, letting session-per-service and session-per-operation both live:
Whoever opens the storage owns its commit and close. A resource that finds storage already in
ctxreuses it and neither commits nor closes it.
ctx is a plain MutableMapping keyed by module-level sentinels, so a caller
can pre-seed storage (the escape hatch) and every resource in the call adopts
it. AppContext (app-scoped) stays a separate concept. HTTP construction
(create_app) is deliberately not part of core — it belongs to the
transport layer, where the per-request service dependency is built through a
configurable DependencyBuilder (its default, OpenDependencyBuilder, opens
the resource's own service over the request-scoped ctx and applies no
authentication). util is the bottom layer: an isolation test pins the layer
ranks util < core < {sql, mongo, list, view, filestore, http, config, cache, encryption, auth, jobs, tasks, triggers, realtime}, so no module imports a
higher layer at runtime.
Configuration — env-driven edges
core stays config-free (a service is built from the objects it is handed),
while each env-driven edge is a BaseConfig block living with what it
configures: SqlConfig in sql/, EncryptionKeysConfig in encryption/,
FileStoreConfig in filestore/, RealtimeConfig in realtime/,
ApiKeysConfig / IdpConfig / SessionCookieConfig in auth/,
BackgroundTasksConfig in tasks/, JobsConfig in jobs/. All read the one
process-wide prefix, APP by default, so connection n is
APP_SQL_CONNECTIONS_<n>_NAME / _URL / _PASSWORD and the key is
APP_ENCRYPTION_KEY_ID / _VALUE (plus APP_DECRYPTION_KEYS_<n>_* for
rotation). An absent encryption key degrades to a loud dev default
(changeme plus a warning); a partially specified one is a hard
ResourceyConfigError.
An app composes the blocks by inheritance and calls the composed config once at its entry point:
from resourcey.encryption.encryption_config import EncryptionKeysConfig
from resourcey.sql.sql_config import SqlConfig
class AppConfig(SqlConfig, EncryptionKeysConfig):
"""The app's single config object, composed from the framework blocks."""
config = AppConfig.get_instance() # reads APP_* from os.environ
print(config.generate_env_template()) # a commented .env skeleton, secrets redacted
get_instance() caches per class, so AppConfig.get_instance() and
SqlConfig.get_instance() are distinct instances whose values agree (both read
the same env namespace). Framework internals resolve their own block;
SqlResource uses get_encryption_service() / get_sql_session_manager() by
default and accepts an explicit encryption_service= / session_factory= to
override. The framework does no .env loading — use uvicorn --env-file or a
wrapper script to populate the environment. A pluggable medium or channel is
chosen by name with a LazyField (APP_MEDIUM_CLASS, APP_CHANNEL_CLASS), so
swapping the implementation needs no code change.
Stack
| Concern | Tool |
|---|---|
| HTTP | FastAPI |
| Validation | Pydantic v2 |
| ORM | SQLAlchemy 2 (async) |
| Migrations | Alembic |
| Package management | uv |
| Formal specs | Quint |
| Tests | pytest (≥90% coverage enforced) |
Authorization (users, groups, roles)
resourcey.auth secures a resource through two composable seams: an
Authenticator (API-key, cookie, and OAuth / OIDC authenticators) that produces
a Principal, and a PolicyResolver that maps that principal to Policy rules.
The built-ins are AllowAll / DenyAll / ReadOnly / Owner, with a
per-app role vocabulary (RolePolicyResolver) and a store-backed RBAC resolver
(RbacPolicyResolver) over users / groups / roles / role_permissions /
resource_acls tables. An AuthorizedService enforces the reduced filter per
action: a denied create is 403, an out-of-scope read/update/delete is 404,
and a denied search/count yields an empty page / 0.
Who am I — the me endpoint
register_me_routes(app, authenticator=..., user_resource=...) (issue #150)
mounts GET / POST /me after create_app, reading the same Authenticator
the app's builder uses, so it works uniformly across the API-key, cookie, and
OAuth methods. The response is an OIDC UserInfo
object: sub (the caller's internal principal id — always present), plus the
framework's kind / roles / scopes and, for an external-IdP caller,
external_id. When a user_resource is supplied, the caller's own row adds
profile claims (email, preferred_username, …); an unavailable claim is
omitted, never null. The route reads that row directly (not through the
users policy) and can only ever return the id the credential already proved, so
an admin-only users surface does not block a caller from seeing its own me.
It is guarded by the strict principal dependency: an absent or invalid
credential is a 401 regardless of the builder's posture. See
examples/04_simple_roles / 07_oauth.
OAuth / OIDC (external identity providers)
The OAuth method (issue #151) federates to an external IdP. OAuthAuthenticator
verifies an Authorization: Bearer token — issuer-keyed client lookup, JWKS
signature check, and alg pinned to the client row's allowlist (no algorithm
confusion) — maps (iss, sub) through an ExternalIdentity table to a local
user, and validates that user against the local store (a missing / disabled user
is rejected: the local store stays authoritative over the IdP). Provider
configuration and tokens are resources, so they live in the environment
(APP_OAUTH_CLIENTS_<n>_*) or the database; the refresh token lives only,
encrypted at rest, in an oauth_tokens table, and refresh is serialized across
processes with a lease / compare-and-swap column. configure_oauth(...) wires
the whole subsystem in one call and register_oauth_routes mounts the
interactive login / callback / refresh flow (BFF session, PKCE). See
examples/07_oauth.
Configuration
A typed environment-variable parser is bundled in resourcey.util.env_parser
(vendored from the
OpenHands Software Agent SDK,
written by the same author). It supports complex nested types and polymorphism
that pydantic-settings cannot express. There is no runtime dependency on
the SDK.
A DiscriminatedUnionMixin is also bundled in resourcey.util.models for
polymorphic models keyed by a kind discriminator — likewise vendored from
the SDK with no dependency.
Migrations
Database revisions are generated with Alembic
from the current resource models. There is no resourcey migrate wrapper:
SQLAlchemy is the schema of record, so Alembic is driven directly against
Base.metadata (see the examples' migrations/ directories):
alembic revision --autogenerate -m "add widget table"
alembic upgrade head # apply
alembic downgrade -1 # one step back
Generated revisions are drafts. Alembic's autogeneration cannot detect table or column renames — a rename looks like a drop followed by a create, which loses data. Review every generated revision before applying it.
Status
Early-stage. The roadmap is tracked in
GitHub issues. See AGENTS.md
for contributor rules and specs/ for the formal Quint specifications.
License
MIT
Metadata
Release files for resourcey 0.0.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| resourcey-0.0.1.tar.gz | 469.7 kB | With provenance | Details for resourcey-0.0.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| resourcey-0.0.1-py3-none-any.whl | Python 3 | none | any | Details for resourcey-0.0.1-py3-none-any.whl |
Total release size: 779.0 kB
Release files / resourcey-0.0.1.tar.gz
| Download URL | resourcey-0.0.1.tar.gz |
|---|---|
| Size | 469.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a28dd4d4df794a3532ecf0f405cb87f90a3a1822414c7f3956b2005edcc97625
|
|
BLAKE2b-256 checksum How to use checksums |
95d3a1965ea8c577a986ce46809e43893e27f58d5aa1a0f75424e16c38fef504
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 31, 2026.
Transparency logRelease files / resourcey-0.0.1-py3-none-any.whl
| Download URL | resourcey-0.0.1-py3-none-any.whl |
|---|---|
| Size | 309.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6e1dfd04684b726e14183647afefe6c41b3eb223a22d0878aec4bd1153fb4ac6
|
|
BLAKE2b-256 checksum How to use checksums |
13bf184dcf4864deb2d56b07fb18218cb8ea68241222e5cda1a475dae8f74c8c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 31, 2026.
Transparency logSecurity for resourcey 0.0.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for resourcey-0.0.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 31, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.