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.md

GitHub

Hex — 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's StrEnum form, in domain/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) or hex-store-repository (a client-style store). The protocol itself is store-agnostic; the choice is made by store profile (hex-conventions block 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_ and i_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 (delete beside upload) → a port method like any other, which raises on failure; the handler-side guard that tolerates its failure is hex-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

  1. A port is a structural interface with no behaviour — method signatures and nothing else. Declare it with typing.Protocol (python-style owns 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.
  2. 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.
  3. 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.
  4. Infrastructure satisfies the port structurally — the adapter neither inherits nor imports it (hex-architecture rule 7).
  5. 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

  1. 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.
  2. Keyword-only arguments for list, count and any multi-parameter method; positional only on a single-parameter lookup such as get_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.
  3. The return shape states what "missing" means, and the adapter has no say in it:
    • get_by_id fails when missing — never Foo | None; the error class is exception-catalog's.
    • get_by_<other> may return Foo | None, and does so exactly when "not found" is a normal outcome.
    • list returns a read-only view (Sequence[Foo]) — see python-style for why a read-only return type is not the same as a list.
    • create / update / delete return None. A write that returns data is a query in disguise.
  4. 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.
  5. 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

  1. One method is the default; two is the maximum, and only when the pair is one reversible action — upload plus delete on the same key. Three or more means the port has stopped being one action: split it, or model it as a repository.
  2. 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-service states 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) from typing. Never abc.ABC, never a concrete base class.
  • No @runtime_checkable unless the codebase genuinely does isinstance(x, IFoo). Default off.
  • Stdlib only — typing, collections.abc, uuid, datetime — plus relative domain imports. No third-party. No from __future__ import annotations.
  • X | None. Sequence[T] from collections.abc for 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-persistence or hex-store-repository for a repository, hex-capability-adapter for a capability.
  • Asked for a port over pure-CPU logic the standard library can do → stop, there is no port; use hex-domain-model or hex-domain-service.