hex-domain-ports
Use when defining a `typing.Protocol` port in the domain — the `I`-prefixed interface adapters satisfy structurally, `IFooRepository` for one aggregate root's data access or `ICan<Verb>` for a single
SKILL.mdplugins/pyhouse-hex/skills/hex-domain-ports/SKILL.md
GitHubHex — Domain Ports
The domain's outbound interfaces. Both are typing.Protocol modules holding method signatures and
nothing else; infrastructure satisfies them structurally (hex-architecture rule 7).
When to use vs. neighbours
- Aggregate-root data access — CRUD plus aggregate-specific reads → repository protocol (
IFooRepository), in this skill. - A single action that does IO or talks to an external system — file rendering, token verification, blob storage, a third-party gateway call → capability protocol (
ICan<Verb>), in this skill. - A pure-CPU operation a third-party library performs — JWT signature verification, rendering bytes through a document library → capability protocol, with a sync method instead of async; the domain cannot import the library, and the port is how it uses one.
- Pure-CPU logic the standard library can do — trimming, case-folding, a stdlib URL normalization → no port; a value object's construction (
hex-domain-model) or a module-level domain function (hex-domain-service). - The entity, value object, enum or filter record the signatures mention →
hex-domain-model.FooKind, which the capability port below returns, is an enum of that skill'sStrEnumform, indomain/foos/foo_kind.py. - A rule needing cross-aggregate state, which consumes these protocols →
hex-domain-service. - A concrete repository implementation →
hex-persistence(a relational store) orhex-store-repository(a client-style store). The protocol itself is store-agnostic; the choice is made by store profile (hex-conventionsblock B). - A concrete capability implementation →
hex-capability-adapter. - An in-memory fake satisfying one of these protocols in a unit test →
hex-test-application-handler. - Binding a concrete implementation to the protocol by type →
hex-wiring. - The token-verifier port, its adapter and the route dependency that resolves it →
hex-restapi-auth; it is the sync shape, bound to auth, and exists only in an app whose entrypoint authenticates. - The
i_andi_can_filename prefixes and the rest of the identifier derivation →naming. - The command or query handler that consumes one of these protocols →
hex-application. - The reversing method a compensating handler calls on one of these ports (
deletebesideupload) → a port method like any other, which raises on failure; the handler-side guard that tolerates its failure ishex-application's (Compensation).
Template(s) — stdlib typing.Protocol
Repository protocol
from collections.abc import Sequence
from typing import Protocol
from uuid import UUID
from .foo import Foo
from .foo_list_filter import FooListFilter
__all__ = ["IFooRepository"]
class IFooRepository(Protocol):
async def list(self, *, filter: FooListFilter) -> Sequence[Foo]: ...
async def count(self, *, filter: FooListFilter) -> int: ...
async def get_by_id(self, id: UUID) -> Foo: ...
async def get_by_name(self, name: str) -> Foo | None: ...
async def create(self, foo: Foo) -> None: ...
async def update(self, foo: Foo) -> None: ...
async def delete(self, id: UUID) -> None: ...
Repository protocol — a store that answers only some reads
A port declares what its store can answer, never more. A key-value store reaches a record by its key and
nothing else, so a Baz kept there is created, fetched by id and deleted — a list, a count or a
get_by_name would need a secondary index the store does not keep. Its repository port is still
IBazRepository, and simply declares those three: a repository port may be narrower than full CRUD, and
a handler that needs a read the port lacks needs the aggregate on a store that can answer it:
from typing import Protocol
from uuid import UUID
from .baz import Baz
__all__ = ["IBazRepository"]
class IBazRepository(Protocol):
async def create(self, baz: Baz) -> None: ...
async def get_by_id(self, id: UUID) -> Baz: ...
async def delete(self, id: UUID) -> None: ...
An index kept beside the authoritative store is the same rule again: its own narrower port, whose verbs are what that index answers.
Capability protocol — a third-party gateway call (async, the default in an event-loop program)
from typing import Protocol
from .foo import Foo
from .foo_kind import FooKind
__all__ = ["ICanClassifyFoos"]
class ICanClassifyFoos(Protocol):
async def classify(self, foo: Foo) -> FooKind: ...
Capability protocol — a reversible action (the forward operation and its undo)
from typing import Protocol
__all__ = ["ICanStoreFoos"]
class ICanStoreFoos(Protocol):
async def upload(self, key: str, body: bytes) -> None: ...
async def delete(self, key: str) -> None: ...
Reading the stored bytes back is a second action, so it is a second port, which one adapter may also
satisfy (hex-capability-adapter).
A pure-CPU port backed by a third-party library declares its method sync (def, not async def);
otherwise it has the same form.
Rules
Two shapes, and the split is about mental model rather than size: a repository is the collection of one aggregate root, a capability is a single action the domain needs but cannot perform itself.
- Aggregate-root data access — CRUD plus aggregate-specific reads → repository protocol.
- A single action that does IO or talks to an external system — file rendering, blob storage, a third-party gateway call → capability protocol.
- A pure-CPU operation that needs a third-party library — verifying a signature, rendering in-memory bytes through a document library → capability protocol, with a sync method instead of async. Pure-CPU logic the standard library can do is not a port at all: it lives in the domain, as a value object's construction or a module-level domain function.
The protocol itself is store-agnostic; the choice is made by store profile (hex-conventions block B).
File location and naming
| Path | Class | |
|---|---|---|
| Repository | src/myapp/domain/foos/i_foo_repository.py |
IFooRepository |
| Capability | src/myapp/domain/foos/i_can_<verb>.py |
ICan<Verb> |
Follow naming for protocol names and prefixes, and python-packaging for module boundaries.
Place a capability where its primary input lives. Cross-cutting ones — auth, observability — go in their
own subdomain package (domain/auth/, domain/observability/).
Both shapes
- A port is a structural interface with no behaviour — method signatures and nothing else. Declare
it with
typing.Protocol(python-styleowns the declaration form and runtime checking), never an abstract base class: a base class makes satisfaction a matter of inheritance, and the point of a port is that an adapter the domain has never heard of satisfies it. - No default implementations and no docstring standing in for one. A body the adapter inherits is
behaviour that escaped the layer that owns it. Comments and docstrings follow
python-style. - Parameters and return types are domain types or primitives. Never a database row, an SDK object or a validation model: a port typed in an adapter's vocabulary drags that library into every caller, and the domain then cannot be imported without it.
- Infrastructure satisfies the port structurally — the adapter neither inherits nor imports it
(
hex-architecturerule 7). - No class-level state and no helper methods. Both belong to the adapter — a helper on the port is a decision the domain has taken on the adapter's behalf, and every adapter then inherits it.
Repository protocol
- Every method carries the same mode, and the mode is the program's. A repository method reaches a
store, so in a program that runs an event loop it is
async— there a sync signature forces every future adapter to either block the loop or break the contract. A program that runs no event loop — a synchronous batch job, a single-command entrypoint that returns — declares the port sync throughout, and the templates above are the async mode. What is not negotiable is uniformity within one port: never a mix, because the mode is part of every signature an adapter and a caller must match, and changing it later changes both sides at once. - Keyword-only arguments for
list,countand any multi-parameter method; positional only on a single-parameter lookup such asget_by_id(id). Two positional parameters of the same type are silently swappable at the call site and no checker catches it — a one-parameter lookup cannot be. - The return shape states what "missing" means, and the adapter has no say in it:
get_by_idfails when missing — neverFoo | None; the error class isexception-catalog's.get_by_<other>may returnFoo | None, and does so exactly when "not found" is a normal outcome.listreturns a read-only view (Sequence[Foo]) — seepython-stylefor why a read-only return type is not the same as alist.create/update/deletereturnNone. A write that returns data is a query in disguise.
- A port declares the methods some handler calls. A method no use case reaches is not declared, however standard — the template is a CRUD service's full set.
- Every method belongs to the one aggregate's collection. Single actions sharing no collection mental model — more than about three of them is the sign — are one or more capability protocols, not repository methods.
Capability protocol
- One method is the default; two is the maximum, and only when the pair is one reversible action —
uploadplusdeleteon the same key. Three or more means the port has stopped being one action: split it, or model it as a repository. - In a program that awaits its IO, async unless the operation is pure CPU. Anything that may do IO
is
async; sync is reserved for work that provably cannot block — cryptographic, parsing and encoding helpers. Getting this wrong is only discovered under load, because the sync port cannot be widened without changing every caller. A program that runs no event loop has no such split — every method is sync — and the split returns the moment one is introduced, which is why the distinction is worth recording even there (hex-domain-servicestates the same condition for a service method).
Inlined typing / import rules
Follow python-style and python-packaging; the load-bearing slice is:
class IName(Protocol)fromtyping. Neverabc.ABC, never a concrete base class.- No
@runtime_checkableunless the codebase genuinely doesisinstance(x, IFoo). Default off. - Stdlib only —
typing,collections.abc,uuid,datetime— plus relative domain imports. No third-party. Nofrom __future__ import annotations. X | None.Sequence[T]fromcollections.abcfor read-only views.- Full annotations on every parameter and every return type.
- No comments unless a non-obvious why; one short line at most.
Package wiring
Follow python-packaging for package exports and hex-architecture for layer placement.
Hard stops
- Asked for the class that implements a port → stop, use
hex-persistenceorhex-store-repositoryfor a repository,hex-capability-adapterfor a capability. - Asked for a port over pure-CPU logic the standard library can do → stop, there is no port; use
hex-domain-modelorhex-domain-service.