flat-project-setup

Use when laying a flat-layered service down once — which runtime and development libraries each of its roles brings, with the version floors this family's templates rely on, and the relational migrati

SKILL.md

GitHub

Flat Project Setup — dependencies by role, migration bootstrap

What a flat-layered service needs once, beyond the toolchain every Python project carries: the libraries its roles bring, and the migration bootstrap the first revision cannot be written without. None of it recurs per feature. The project file itself — src layout, ruff, mypy, dependency declarations — is python-toolchain's; what goes inside src/myapp/ is flat-layered; what a schema change looks like after the bootstrap is flat-persistence.

When to use vs. neighbours

  • Starting a flat service, adding a dependency, or justifying one of this family's floors → block A.
  • Laying migrations on a service that has none → block B, once; this skill is one-shot, and flat-persistence's revisions and flat-test-integration-setup's migration fixture both depend on it having run.
  • The pyproject.toml tables, the src layout, the linter and type checker, the sanctioned suppressions, the line length, and whether any dependency may carry a floor → python-toolchain.
  • A second store's migration directory beside migrations/postgres/, and the tool that applies it → flat-persistence, which owns where every store's history lives.
  • The per-change revision that pairs with a table edit, and what a deploy obliges of it → flat-persistence.
  • The packages inside src/myapp/, the settings class each component owns, and the entry point → flat-layered.
  • The pytest configuration block → python-toolchain; the fixtures it loads → flat-test-integration-setup.
  • Which version the distribution itself declares, and what changes it → python-versioning.
  • The interpreter floor, annotation forms, and the comment rules migrations follow → python-style.
  • __init__.py re-exports and import forms → python-packaging.
  • Several distributions in one repository — the workspace root, settings shared at the root → python-workspace; each member's libraries are still chosen by this skill.
  • The family is not settled → architecture-choice. A hexagonal project → hex-project-setup, in the pyhouse-hex plugin.

A. Dependencies by role — uv

pyproject.toml is python-toolchain's template, taken as written; uv init --package --build-backend hatch myapp lays it. Then delete the main it writes into src/myapp/__init__.py and the [project.scripts] entry that points at it. A service that runs a single process starts it from __main__.py; a service with several processes declares one console script per process in their place (flat-layered). What this family adds is which libraries arrive, each with uv add or uv add --dev, and the floors its own templates rely on.

Dependencies are chosen by the roles the service actually has. The settings library and the structured logger are always present — every process reads configuration and logs. The rest arrive with the role that needs them and not before:

Role present Runtime dependencies it brings Development dependencies it brings
any pydantic, pydantic-settings, structlog python-toolchain's development group, as written
a client over HTTP httpx2>=2 (2.0: the first release carrying the client API; the only earlier one is an empty 0.0.0 placeholder) —
data access on a relational store sqlalchemy[asyncio]>=2 (2.0: inline type annotations under mypy --strict), asyncpg testcontainers[postgres]>=4.15 (4.15: testcontainers.community)
a relational store whose schema this service owns alembic —
a service that mints row ids uuid6 —
an HTTP trigger fastapi, uvicorn httpx2>=2, the in-process test client, unless the client-over-HTTP row already brings it
a durable-execution engine, once earned the engine's SDK the engine's test harness
a vendor SDK client that SDK, with the client that wraps it whatever double the SDK ships

A service with no datastore carries no Core library, no driver and no migration tool; one that only reads a table another service owns carries the Core library and the driver and no migration tool; one with no HTTP trigger carries no web framework. A dependency nothing imports is a stray package.

Each floor is written with the API beside it, as a comment on its line — "sqlalchemy[asyncio]>=2", # 2.0: inline type annotations under mypy --strict. The three above are there because this family's templates call exactly those names — httpx2's client, the strictly typed engine and the container module. A service whose own code calls none of a floor's names drops the floor and its comment together; one that relies on something newer raises the floor and names that instead (python-toolchain rule 9).

B. The migration bootstrap — Alembic over SQLAlchemy async

Laid only when the service owns the schema of a relational store, and once. alembic upgrade head — and the integration suite that replays it — cannot run without the config and the environment. The history lives in migrations/postgres/, the directory named for the store it versions, because a second store's history would sit beside it (flat-persistence); alembic.ini stays at the distribution root, beside pyproject.toml, where every alembic command and the integration suite run from. The tool lays both, run from the distribution root:

alembic init -t async migrations/postgres

It writes alembic.ini with script_location already pointing at migrations/postgres, and in that directory env.py, script.py.mako, a README and an empty versions/. The README is deleted. What it writes is the tool's generic starting point, not this family's bootstrap; before the first revision, the generated files are changed to do what follows.

Nothing in alembic.ini names a database. The sqlalchemy.url line init writes is deleted, and so is every logging section — [loggers], [handlers], [formatters] and the [logger_*], [handler_*], [formatter_*] sections they list — which only the generated logging setup reads; the rest may stay as generated.

The migration environment is the migration run's process definition, so it is the one place outside the service's own entrypoints that builds the data-access component's settings. env.py is changed so that:

  • the engine comes from the data-access package's engine factory, given the dsn that component's own settings class derives (flat-persistence; flat-layered rules 6 and 7), in place of the generated engine built from the ini section;
  • the engine is disposed however the run ends, not only after a clean one;
  • target_metadata is the data-access package's one MetaData; left at the generated None, autogenerate refuses to run;
  • every table module is imported, one line each, because a table module's names are bare objects the data-access package does not re-export (python-packaging), and autogenerate compares only the tables that registered; a new table module adds its line in the same change that adds the module;
  • logging is configured as every other process definition of the service configures it — the service's own logging setup, called once before the run — in place of the generated fileConfig call on alembic.ini, which would give the tool's records their own handler and format beside the service's structured stream (python-logging rule 3);
  • offline mode is refused rather than half-supported — the generated offline branch is replaced by an error, because every migration runs against a live connection;
  • the tool's explanatory comments go, as they do from any source file (python-style, Comments).

The revision template is kept as init writes it, with three edits: its annotations, its import order and its comments. The generated script.py.mako annotates its revision identifiers with typing.Union and typing.Sequence and places from alembic import op ahead of import sqlalchemy as sa, so every revision it rendered would break python-style's annotation forms and fail the linter's import sort. Its annotations become str | Sequence[str] | None with Sequence from collections.abc, import sqlalchemy as sa moves ahead of from alembic import op — the order the linter's import sort requires — and the tool's explanatory comments go (python-style, Comments); nothing else in it changes.

This block sanctions two lint suppressions, the ones python-toolchain rule 5 leaves to it. The inline unused-import suppression on the environment's registration imports: they exist only for their side effect, and without it the linter deletes them and autogenerate stops seeing the schema. And the per-file statement-count ignore on migrations/**/versions/*.py, the line python-toolchain's template marks: a revision's body is generated DDL, one statement per column and constraint, not authored logic, and a wide table is not a function to split; every other bound stays on for revisions.

The root of the chain

Where a chain is rooted, and when a baseline exists at all, is persistence rule 20; under Alembic it is spelled as follows. Greenfield, versions/ starts empty, and the first table's revision is autogenerated from the metadata and reviewed like every later change (alembic revision --autogenerate -m "<change>", as flat-persistence makes each); Alembic gives it no parent, and an empty upgrade head and downgrade base already succeed before it exists. Over a schema that already exists, the baseline is written into an empty versions/ with every table, column and constraint spelled out in op calls, never metadata.create_all, importing nothing from src/ — neither the metadata nor the table modules — and each existing database is marked with alembic stamp at the baseline's revision; a fresh one — the integration suite's — runs it like any revision.

Other bindings

  • Another package manager. poetry or pdm replace uv add; the roles and what each brings, and the floors with their APIs, are unchanged. The rest is python-toolchain's.
  • Another migration tool. Its init command, config file, revision template and autogenerate command change, and so do the lines its generated environment needs changed; the history in migrations/postgres/ at the distribution root, the environment reading the connection string at its own composition root, seeing every table and logging through the service's one configuration, the chain's root and its baseline (persistence rule 20), and a reverse operation in every revision do not.

Rules

  1. Laid once, in python-toolchain's src layout, from the first commit, with migrations — where the service owns the schema of a relational store — at the distribution root beside src/ and tests/, in one directory per store named for it, and their config beside the project file.
  2. Dependencies follow the roles the service has. The settings library and the structured logger always; everything else arrives with the role that imports it, and a package nothing imports is removed.
  3. A floor is written only where this family's code relies on the API it names, with that API beside it; the table in block A is the family's whole set, and each goes with the code that calls it. The floor discipline itself is python-toolchain rule 9.
  4. Everything else in the project file is python-toolchain's — the development group, the linter and type-checker configuration with its written bounds and the suppression it sanctions everywhere, the line length — and the interpreter floor is python-style's. Block B's two suppressions are sanctioned here, and only where block B is laid.
  5. The migration environment reads the connection string through the data-access component's own settings class, and only there among migration files. It is the migration run's process definition; the migration config names no database, the variables the environment reads are the ones the integration suite sets for it, and the engine it builds is disposed however the run ends.
  6. The migration environment sees the whole schema: its target is the data-access package's one metadata, every table module is imported by it, and a new table module adds its import in the same change.
  7. The generated bootstrap is the tool's starting point, not the bootstrap. Lay it with the tool's own init, then change what it wrote to meet rules 5 and 6, configure logging as the service's other processes do, refuse offline mode, and render revisions in python-style's forms and the linter's import order.
  8. The chain is rooted as persistence rule 20 says, spelled under Alembic as in The root of the chain above.

Hard stops

  • The project file's lint, type-check or layout settings are being chosen here → stop, use python-toolchain.
  • A baseline revision is being written into a versions/ that already holds revisions → stop, the chain has started; write a revision (flat-persistence).
  • A baseline, empty or not, is being written for a greenfield schema → stop, the first table's autogenerated revision is the root (flat-persistence).
  • Migrations are being laid on a service that owns no relational schema — none at all, or one it only reads → stop, there is nothing for it to version; the schema's owner versions it.
  • The service is hexagonal → stop, use hex-project-setup, in the pyhouse-hex plugin.