Building Hexagonal Python Services
2023-04-19 , A05-A06

The importance of enterprise architecture patterns is all well-known and applicable to varied types of tasks. Thinking about the architecture from the beginning of the journey is crucial to have a maintainable, therefore testable, and flexible code base. In We are going to explore the Ports and Adapters(Hexagonal) pattern by showing a simple web app using Repository, Unit of Work, and Services(Use Cases) patterns tied together with Dependency Injection. All those patterns are quite famous in other languages but they are relatively new for the Python ecosystem, which is a crucial missing part.
As a web framework, we are going to use FastAPI which can be replaced with any framework in a matter of time because of the abstractions we have added.


In nearly all web applications and Python tutorials we are starting from installing a web framework, and database server, the next step is to build database models and then use ORM, etc.
But wait, there is a problem with this classical approach, we lose the core business domain discussions - so-called core domain models just get lost inside some classes and functions. How about changing and reverting our approach? How about first starting by thinking, modeling our business, and core domain, and then testing it properly? Afterward, how about adding an abstraction layer on the database, then adding another abstraction on actual services, and use cases? But wait, how we are going to manage all transactional usage - okay let's add another layer with the Unit of Work pattern to manage our work as units. Sounds cryptic? Here is a step-by-step guide to starting our project:
* We are going to start with domain modeling and adding tests for our domain models
* The database layer will be abstracted using a Repository pattern
* The database transactions will be managed by the Unit of Work pattern
* The business logic actions were encapsulated in the Use Cases

The question can arise: where are our web framework and database server?
Answer: good architecture lets us defer those choices until the end. Because the web framework and the database server are details for our business/core application itself. Web framework will be considered as an entry point for our application and the database layer will be encapsulated using SQLAlchemy ORM, but still, ORM itself is hidden behind Repository and UoW patterns. This allows us to change the ORM library if there will be any need in the future.

The most important part here is to understand how we are going to build our application using Ports and Adapters(Hexagonal) pattern and all aforementioned patterns will be divided into Ports(using abstract base classes) and Adapters(the actual implementations), we can think about this as a contract between our actual implementations and abstractions.


Expected audience expertise: Domain:

Novice

Expected audience expertise: Python:

Intermediate

Abstract as a tweet:

Building Hexagonal Python Services from scratch using Repository, Unit of Work and Use Cases patterns

Public link to supporting material:

https://github.com/ShahriyarR/hexagonal-fastapi-jobboard

Senior Software Engineer. Moving forward on Clean Code and Clean Architecture. Previous accomplishments include contributing to open source, providing technical direction, and sharing knowledge about Clean Code and Architectural patterns. An empathetic team player and mentor.
Azerbaijan Python Group Leader. Former QA Engineer and Bug Hunter.