Hexagonal Architecture in Python

Most Python services do not fail at the first release. They fail at the tenth change request, when a command-line tool, a second payment provider or a test without a database turns out to mean editing the code that holds the business rules.

Hexagonal Architecture in Python is about the one thing that decides what that edit costs: which way the dependencies point between the business rules and everything outside them. Hexagonal, Onion and Clean architectures turn those arrows toward the rules. Layering leaves them pointing at the database. Vertical slices cut the code along a different axis. Once you can see the arrows, the choice between them is a decision you can write down and check.

Most architecture books teach one architecture. This one builds five, on one codebase. The service books meeting rooms by the hour: holds that expire, paid confirmations, cancellation fees, no overlapping bookings. It grows an HTTP API, a front-desk command-line tool, a Kafka consumer and a scheduled job, all calling the same use cases. Then the same hold-and-cancel feature is built again as a layered, an Onion, a Clean and a vertical-slice service, and all five pass the same fourteen scenarios from one byte-identical test file.

Then they are measured instead of argued about. The hexagonal variant comes to 364 lines and 29 classes. The vertical slices do the same job in 261 lines and 14 classes. Clean Architecture is the heaviest, at 536 lines. A new business rule is added to every variant and the files it touches are counted. Some of what the counts show favors the hexagon and some of it does not, and the book prints both. It ends in a decision matrix that picks an architecture from two facts about your service, and says when each pick stops being right.

Written against the Python stack as it stands now. Async end to end on Python 3.14, FastAPI and Pydantic v2 at the edge, SQLAlchemy 2.1 on PostgreSQL behind the ports, every version pinned and dated. Pythonic rather than ported from Java: ports are Protocols the core writes, the domain is frozen dataclasses that import nothing.

What you will be able to do:

• Tell from a codebase's imports which architecture it really is, and where three of the five are one idea at different levels of ceremony.
• Model a domain in plain Python, with value objects, invariants checked on construction and state transitions that refuse illegal moves.
• Write adapters on both sides that translate and decide nothing, and wire them in one composition root.
• Make the dependency rule a build failure with import contracts and strict type checking in CI.
• Test the core in milliseconds against fakes, and prove the fakes keep their promises with contract tests against a real PostgreSQL.
• Handle the unit of work, the double-booking race, errors that cross boundaries, the transactional outbox, and tracing that never touches the domain.
• Migrate a framework-shaped app to a hexagon in steps that each ship, and split one hexagon into two.

And when not to use any of it. A hexagon is a purchase: you pay up front, in files and indirection, for options you expect to exercise later. A whole chapter is about the code that will never meet those changes, and why treating it as if it would is its own kind of mistake.

Every listing runs. A free public companion repository holds every file the book prints, all five architecture variants and the recorded output of every command. You need Docker with Compose and nothing else.

Who it is for. Backend engineers who have shipped a FastAPI, Flask or Django service and felt it harden: a rule living in three route handlers, a test suite that needs a database before it can say anything about pricing. You know async and await at a working level.