hex-project-setup
Use when laying a hexagonal project down once — which libraries its core, its entrypoints, its stores and its features bring, the floors this family's templates rely on, and the Alembic bootstrap the
SKILL.mdplugins/pyhouse-hex/skills/hex-project-setup/SKILL.md
GitHubHexagonal Project Setup — dependency substrate, migration bootstrap
What a hexagonal project needs once, beyond the toolchain every Python project carries: the libraries
its layers bring, and the migration bootstrap. None of it recurs per feature. The project file itself —
src layout, ruff, mypy, dependency declarations — is python-toolchain's; the derivation rules that do
recur are hex-conventions; the layer boundaries are hex-architecture.
When to use vs. neighbours
- Adding a dependency, or justifying one of this family's floors → block A.
- Laying migrations for the first time on a project that has none → block B.
- The
pyproject.tomltables, the src layout, the linter and type checker, the sanctioned suppressions, the line length, and whether any dependency may carry a floor →python-toolchain. - The per-change migration revision that pairs with a schema edit →
hex-persistence, not here; this skill covers only the bootstrap that lets the chain start. - Where a file goes and what it is called →
hex-conventions. - Layer boundaries →
hex-architecture; packaging mechanics →python-packaging. - Module files,
__all__and the re-export contract inside the package →python-packaging. - The runtime DI bindings →
hex-wiring; the environment-backed settings classes →python-settings, each shown beside the adapter that reads it. This skill stops at which libraries exist. - The interpreter floor →
python-style. - Whether the project should be hexagonal or flat-layered at all →
architecture-choice; settle that before laying this down. - A multi-service uv workspace rather than a single package →
python-workspace.
A. Stack substrate by role — uv
pyproject.toml is python-toolchain's template, laid the way that skill lays it; it carries the core
substrate plus whatever each entrypoint package and each infrastructure adapter needs,
each added with uv add or uv add --dev.
- Core substrate (always present, whatever the program is): the settings library, the
dependency-injection library, and the structured logger. Every hexagonal program reads configuration,
composes its adapters at one root, and logs — a worker, a batch job and a single-command CLI included.
myapp.logging.configure_loggingis the service's one logging setup (python-loggingrule 3): where the service has none yet, it is written there once, safe to run again, and every entrypoint calls it before anything logs. - Entrypoint substrate (whatever the entrypoint packages the project actually has require, and nothing else): an HTTP entrypoint brings its web framework, that framework's server, and the validation library its wire schemas are written in; a queue or scheduled entrypoint brings its broker or scheduler client; a CLI entrypoint brings its argument parser, which may be the standard library and therefore nothing at all. A project with no HTTP entrypoint carries no web framework and no server — the same trigger rule as a feature extra, applied to the entrypoint layer.
- Relational substrate (only when a relational store backs a repository): the ORM/Core library with its async extra and the async driver — and the migration tool only when the store's schema is one this service owns. A service that only reads a table another owns carries no migration tool.
- Feature-triggered extras — a package required only because some endpoint or adapter uses a specific feature. Multipart form handling is the canonical example: a web framework typically imports its multipart library at app-construct time for any form route, and without it constructing the app raises — which lint, type-check and the unit tier do not catch. An app with no such endpoint must not carry it.
- Dev (always present): the test runner and its async plugin, the linter and the type checker.
Triggered alongside them: the container library, once an integration tier drives a real backing
service, and a transport test client for each entrypoint the suite drives over its own transport — an
HTTP test client belongs to a project with HTTP routes to call. An adapter that calls an HTTP API
brings no interception library: its test stubs the transport with the HTTP client's own
(
hex-test-capability-adapter). - Test-bootstrap extras follow the same trigger rule as feature extras: a suite that mints asymmetric-signature tokens needs the crypto library that generates the keypair; a project verifying symmetric or opaque tokens generates no keypair and must not carry it. A dev dependency nothing imports is a stray package.
- SDK packages are not listed as substrate — each rides along with the adapter that needs it.
Every entry is a name; a floor is written only at a known breaking boundary with the API beside it
(python-toolchain rule 9), and an adapter's SDK takes one on exactly the same terms. The async test
plugin's floor is python-toolchain's.
An adapter that calls an HTTP API, and the HTTP test client, bring httpx2>=2 — 2.0 is the first
release carrying the client API, and the only earlier one is an empty 0.0.0 placeholder.
The FastAPI floor is written only where the app declares auth: the auth probe (hex-test-restapi-auth) walks the
app's resolved operations through fastapi.routing.iter_route_contexts, which first ships in 0.137.2,
and from 0.137.0 an included router is a single _IncludedRouter entry in app.routes, so a walk over
app.routes alone no longer reaches the operations. Below 1.0 a release's minor is its breaking segment,
so the floor names the release that shipped the API rather than a major:
[project]
dependencies = [
"fastapi>=0.137.2", # iter_route_contexts, the resolved-route walk the auth probe relies on
]
B. Relational migration bootstrap (write-once) — Alembic over SQLAlchemy and Postgres
Laid only for a relational store whose schema this service owns, the same trigger as the migration
tool and the first table. The migration tool owns the revision chain, but the chain cannot start — and
alembic upgrade head cannot run — without the config (pure glue, rewritten freely), and over a
database that already holds objects, a baseline revision (write-once). Without the config the
integration suite dies at setup with No 'script_location' key found. Nothing in lint, type-check or the unit tier catches that; only a real
run against a database does.
The three config files are complete glue. alembic.ini, at the tree root:
[alembic]
script_location = migrations
prepend_sys_path = src
migrations/env.py runs async and in online mode only — the app is always migrated against a live
connection, so offline mode is refused rather than half-supported:
import asyncio
from alembic import context
from sqlalchemy import Connection
import myapp.infrastructure.postgres.tables # noqa: F401
from myapp.infrastructure.postgres import PostgresSettings, create_engine
from myapp.infrastructure.postgres.metadata import metadata
from myapp.logging import configure_logging
target_metadata = metadata
def _run(connection: Connection) -> None:
context.configure(connection=connection, target_metadata=target_metadata)
with context.begin_transaction():
context.run_migrations()
async def _run_online() -> None:
engine = create_engine(PostgresSettings())
try:
async with engine.connect() as connection:
await connection.run_sync(_run)
finally:
await engine.dispose()
if context.is_offline_mode():
raise RuntimeError("offline migrations are not supported")
configure_logging()
asyncio.run(_run_online())
The engine is disposed however the run ends. The migration run is a process like the others, so the environment calls the service's one logging setup (block A); left unconfigured, the tool's records reach no configured handler.
migrations/script.py.mako is the template alembic init -t async migrations writes — run once from
the tree root, with the alembic.ini and env.py it also writes replaced by the two above and its
README deleted — with three edits, so that every revision alembic revision renders passes the linter and python-style: its revision identifiers are annotated
str | Sequence[str] | None with Sequence from collections.abc, never typing.Union or
typing.Sequence; 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.
Where the chain is rooted, and when a baseline exists at all, is persistence rule 20; under Alembic
it is spelled as follows. On a greenfield project migrations/versions/ starts empty, and the first
table the project adds is autogenerated and reviewed like every later one; Alembic gives it no parent,
and alembic upgrade head and downgrade base already succeed on an empty chain. Over a database that
already holds objects, the baseline revision is created only while migrations/versions/ carries no
*.py yet, with no parent, its objects spelled out in op calls and never metadata.create_all,
importing nothing from src/ — neither the metadata nor the table registrar — and each existing database is marked with alembic stamp <baseline revision>; a fresh one — the integration
suite's — runs it like any revision.
Every subsequent migration is a real revision (uv run alembic revision --autogenerate -m "<change>")
— see hex-persistence for the per-change form.
migrations/ lives at the tree root, outside src/ and tests/: linted, not type-checked
(python-toolchain rule 2). env.py is a composition root, so it constructs the settings class itself
(python-settings rule 13).
This block sanctions two lint suppressions, the ones python-toolchain rule 5 leaves to it. The
inline unused-import suppression on env.py's registration import: it exists only for its side effect,
and without it the linter deletes it 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.
Other bindings
- Another package manager. poetry or pdm replace
uv add; the substrate by role, the SDK riding with its adapter and the floor with its API are unchanged. The rest ispython-toolchain's. - Another migration tool. The config file, the revision template and the autogenerate command all
change; the environment logging through the service's one configuration, the chain's root and its
baseline (
persistencerule 20), and the mandatory reverse operation do not.
Rules
- Select dependencies by block A's core substrate plus its entrypoint, store and feature triggers;
include an SDK only with its adapter. A feature's package or an entrypoint's framework is added only
to an app that has that feature or entrypoint: a dependency nothing imports is a stray package. Every
entrypoint calls the service's one logging setup,
myapp.logging.configure_logging, written once where the service has none, before anything logs. - Write a floor — an SDK's or a substrate library's — only at the documented breaking boundary the
project's code relies on, under
python-toolchainrule 9; block A's one is this family's. - Take everything else in the project file from
python-toolchain— the src layout, the development group, the linter and type-checker configuration with its written bounds and sanctioned suppressions, the line length — and the interpreter floor frompython-style. - Add the complete migration configuration only for a relational store whose schema this service owns.
- Root the chain as
persistencerule 20 says, spelled under Alembic in block B. Every table the project adds is its own revision underhex-persistence. - The migration environment disposes its engine however the run ends, refuses offline mode, and calls
the service's one logging setup (rule 1); the revision template renders
python-style's annotation forms in the linter's import order.
Hard stops
- The project file's lint, type-check or layout settings are being chosen here → stop, use
python-toolchain. - A table the project is adding is being written into the baseline → stop, the baseline holds only what
already existed; the new table is its own autogenerated, reviewed revision (
hex-persistence). - A baseline, empty or not, is being written for a greenfield project → stop, the first table's
autogenerated revision is the root (
hex-persistence). - Migrations are being laid for a relational store this service only reads → stop, the schema's owner versions it.
- The project is flat-layered → stop, use
flat-project-setup, in thepyhouse-flatplugin.