AI / Agents

Skills
llms.txt
llms-full.txt

Developers

German Human Genome Phenome Archive (GHGA)

Community

Contributing guide
Full license Apache-2.0

Meta

Requires: Python >=3.10
Provides-Extra: akafka, s3, mongodb, redis, vault, opentelemetry-base, opentelemetry-akafka, opentelemetry-mongodb, opentelemetry-fastapi, opentelemetry-s3, opentelemetry-redis, opentelemetry, test-akafka, test-s3, test-mongodb, test-redis, test-vault, test, all

PyPI version shields.io PyPI pyversions tests Coverage Status Ruff Checked with mypy

hexkit

A chassis library for building domain-focused, infrastructure-agnostic, and event-driven microservices in Python

Read the short summary below, or jump straight to our full 📖 User Guide to learn the abstract concepts and patterns as well as the concrete infrastructure integrations and testing tools that hexkit provides for building better microservices.

In a Nutshell

hexkit implements the Triple Hexagonal Architecture pattern, an optimization of the ordinary Hexagonal Architecture for use with microservices: adapters (as per the hexagonal architecture) are divided into two parts. One part called translator is specific to one individual microservice and its domain-oriented ports. The other part called provider is service-agnostic but specific to one technology of the surrounding infrastructure. Both parts interact through a high-level interface called protocol (not to be confused with Python’s typing.Protocol) which is neither specific to the technology nor to the microservice.

As a chassis lib, hexkit reduces redundancy and boilerplate across microservices by providing the service-independent building blocks — protocols and providers — ready to use. The only task that remains for an individual service is to implement service-specific translators between the service’s ports and the general-purpose protocols (in addition to implementing the domain functionality of the service, of course). For an in-depth introduction to the pattern, please read the Architectural Concepts chapter of the User Guide.

The following protocols and providers are currently available:

Protocol Providers
Event Publishing Apache Kafka, MongoDB + Kafka (outbox)
Event Subscription Apache Kafka
Data Access Object MongoDB
Object Storage S3(-compatible)
Key-Value Store MongoDB, Redis, S3, HashiCorp Vault

In-memory implementations and per-backend test utilities are also included to support testing without real infrastructure.

You are not forced to go all-in on the idea of Triple Hexagonal Architecture. You can use it just for the technologies where you see benefits and use another approach for the rest. For example, you could use hexkit for simplifying the exchange of events between microservices but use a classical web framework such as FastAPI for designing REST APIs and an ORM like SQLAlchemy for interacting with databases.

Getting Started

The 📖 User Guide covers all protocols, providers, testing utilities, and observability tools with example code, and the API Reference documents all public classes and functions.

For a complete example service built with hexkit, have a look at the stream_calc example application. We also put a lot of effort into making the code self-documenting: you can find the protocols being defined at src/hexkit/protocols and the providers being implemented at src/hexkit/providers.

Installation

This package is available at PyPI: https://pypi.org/project/hexkit

You can install it from there using:

pip install hexkit

The following extras are available:

  • akafka: when using the Apache Kafka-based event publishing or subscription
  • mongodb: when using MongoDB as backend for the DAO protocol or key-value stores
  • s3: when interacting with S3-compatible object storages or key-value stores
  • redis: when using Redis-based key-value stores
  • vault: when using HashiCorp Vault-based key-value stores
  • opentelemetry: observability instrumentation (also available per backend, e.g. opentelemetry-akafka, opentelemetry-mongodb, opentelemetry-fastapi)
  • test-akafka, test-mongodb, test-s3, test-redis, test-vault: testing utils for the respective backend (test is a union of all of them)
  • all: a union of all the above

Contributing

Contributions are welcome! Please see the contribution guide for how to set up the development environment and build the documentation locally.

Credits

The hexkit library is developed and maintained by the developer team of GHGA. We would especially like to thank its original author, Kersten Breuer, who came up with the idea for the library and designed and coded its first versions.

License

This repository is free to use and modify according to the Apache 2.0 License.