Metadata-Version: 2.4
Name: hexkit
Version: 10.0.0
Summary: A Toolkit for Building Microservices using the Hexagonal Architecture
Author-email: "German Human Genome Phenome Archive (GHGA)" <contact@ghga.de>
License-Expression: Apache-2.0
Project-URL: Repository, https://github.com/ghga-de/ghga
Project-URL: Documentation, https://ghga-de.github.io/ghga/hexkit/
Project-URL: Release Notes, https://github.com/ghga-de/ghga/releases?q=hexkit
Project-URL: Issue Tracker, https://github.com/ghga-de/ghga/issues
Classifier: Development Status :: 5 - Production/Stable
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Topic :: Software Development :: Libraries
Classifier: Intended Audience :: Developers
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: opentelemetry-api<2,>=1.44
Requires-Dist: pydantic<3,>=2.12
Requires-Dist: pydantic_settings<3,>=2.12
Requires-Dist: PyYAML<7,>=6
Provides-Extra: akafka
Requires-Dist: aiokafka[lz4,snappy,zstd]~=0.14.0; extra == "akafka"
Requires-Dist: jsonschema<5,>=4.25; extra == "akafka"
Provides-Extra: s3
Requires-Dist: boto3<2,>=1.42; extra == "s3"
Requires-Dist: botocore<2,>=1.42; extra == "s3"
Provides-Extra: mongodb
Requires-Dist: pymongo<5,>=4.16; extra == "mongodb"
Provides-Extra: redis
Requires-Dist: redis<8,>=7.1; extra == "redis"
Provides-Extra: vault
Requires-Dist: hvac<3,>=2.4; extra == "vault"
Provides-Extra: opentelemetry-base
Requires-Dist: opentelemetry-sdk<2,>=1.44; extra == "opentelemetry-base"
Requires-Dist: opentelemetry-exporter-otlp<2,>=1.44; extra == "opentelemetry-base"
Requires-Dist: opentelemetry-instrumentation>=0.65b0; extra == "opentelemetry-base"
Requires-Dist: opentelemetry-instrumentation-httpx>=0.65b0; extra == "opentelemetry-base"
Requires-Dist: opentelemetry-distro>=0.65b0; extra == "opentelemetry-base"
Provides-Extra: opentelemetry-akafka
Requires-Dist: hexkit[opentelemetry-base]; extra == "opentelemetry-akafka"
Requires-Dist: hexkit[akafka]; extra == "opentelemetry-akafka"
Requires-Dist: opentelemetry-instrumentation-aiokafka>=0.65b0; extra == "opentelemetry-akafka"
Provides-Extra: opentelemetry-mongodb
Requires-Dist: hexkit[opentelemetry-base]; extra == "opentelemetry-mongodb"
Requires-Dist: hexkit[mongodb]; extra == "opentelemetry-mongodb"
Requires-Dist: opentelemetry-instrumentation-pymongo>=0.65b0; extra == "opentelemetry-mongodb"
Provides-Extra: opentelemetry-fastapi
Requires-Dist: hexkit[opentelemetry-base]; extra == "opentelemetry-fastapi"
Requires-Dist: opentelemetry-instrumentation-fastapi>=0.65b0; extra == "opentelemetry-fastapi"
Provides-Extra: opentelemetry-s3
Requires-Dist: hexkit[opentelemetry-base]; extra == "opentelemetry-s3"
Requires-Dist: hexkit[s3]; extra == "opentelemetry-s3"
Requires-Dist: opentelemetry-instrumentation-botocore>=0.65b0; extra == "opentelemetry-s3"
Provides-Extra: opentelemetry-redis
Requires-Dist: hexkit[opentelemetry-base]; extra == "opentelemetry-redis"
Requires-Dist: hexkit[redis]; extra == "opentelemetry-redis"
Requires-Dist: opentelemetry-instrumentation-redis>=0.65b0; extra == "opentelemetry-redis"
Provides-Extra: opentelemetry
Requires-Dist: hexkit[opentelemetry-akafka]; extra == "opentelemetry"
Requires-Dist: hexkit[opentelemetry-mongodb]; extra == "opentelemetry"
Requires-Dist: hexkit[opentelemetry-fastapi]; extra == "opentelemetry"
Requires-Dist: hexkit[opentelemetry-s3]; extra == "opentelemetry"
Provides-Extra: test-akafka
Requires-Dist: hexkit[akafka]; extra == "test-akafka"
Requires-Dist: testcontainers[kafka]<5,>=4.15; extra == "test-akafka"
Provides-Extra: test-s3
Requires-Dist: hexkit[s3]; extra == "test-s3"
Requires-Dist: httpx2<3,>=2.9.1; extra == "test-s3"
Requires-Dist: testcontainers<5,>=4.15; extra == "test-s3"
Provides-Extra: test-mongodb
Requires-Dist: hexkit[mongodb]; extra == "test-mongodb"
Requires-Dist: testcontainers[mongodb]<5,>=4.15; extra == "test-mongodb"
Provides-Extra: test-redis
Requires-Dist: hexkit[redis]; extra == "test-redis"
Requires-Dist: testcontainers[redis]<5,>=4.15; extra == "test-redis"
Provides-Extra: test-vault
Requires-Dist: hexkit[vault]; extra == "test-vault"
Requires-Dist: testcontainers<5,>=4.15; extra == "test-vault"
Provides-Extra: test
Requires-Dist: hexkit[test-akafka,test-mongodb,test-s3,test-vault]; extra == "test"
Provides-Extra: all
Requires-Dist: hexkit[test]; extra == "all"
Requires-Dist: hexkit[opentelemetry]; extra == "all"
Dynamic: license-file

<!-- rumdl-disable MD013 -->
[![PyPI version shields.io](https://img.shields.io/pypi/v/hexkit.svg)](https://pypi.org/project/hexkit/)
[![PyPI pyversions](https://img.shields.io/pypi/pyversions/hexkit.svg)](https://pypi.org/project/hexkit/)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![Checked with mypy](https://www.mypy-lang.org/static/mypy_badge.svg)](https://mypy-lang.org/)
<!-- rumdl-enable MD013 -->

# 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](https://ghga-de.github.io/ghga/hexkit/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.

<!--
NOTE: This README doubles as the landing page of the documentation site built with
great-docs. Therefore, all links must be absolute URLs — repo-relative links like
./examples or ./src would resolve correctly on GitHub but break on the site.
-->

## In a Nutshell

hexkit implements the *Triple Hexagonal Architecture* pattern, an optimization of the ordinary [Hexagonal Architecture](https://alistair.cockburn.us/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](https://ghga-de.github.io/ghga/hexkit/user-guide/arch_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](https://ghga-de.github.io/ghga/hexkit/user-guide/) covers all protocols, providers, testing utilities, and observability tools with example code, and the [API Reference](https://ghga-de.github.io/ghga/hexkit/reference/) documents all public classes and functions.

For a complete example service built with hexkit, have a look at the [stream_calc](https://github.com/ghga-de/ghga/tree/main/libs/hexkit/examples/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](https://github.com/ghga-de/ghga/tree/main/libs/hexkit/src/hexkit/protocols) and the providers being implemented at [src/hexkit/providers](https://github.com/ghga-de/ghga/tree/main/libs/hexkit/src/hexkit/providers).

Coding agents get an [agent skill](https://agentskills.io) for hexkit with the package, at `hexkit/.agents/skills/hexkit/SKILL.md` in `site-packages`, where tools such as [library-skills](https://library-skills.io) find it.
The docs site publishes the same file, so `npx skills add https://ghga-de.github.io/ghga/hexkit` installs it as well.

## Installation

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

You can install it from there using:

```sh
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!
hexkit is developed in the [GHGA monorepo](https://github.com/ghga-de/ghga) under `libs/hexkit`, together with the services that build on it.
Please see the [contribution guide](https://github.com/ghga-de/ghga/blob/main/libs/hexkit/CONTRIBUTING.md) 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

hexkit is free to use and modify according to the [Apache 2.0 License](https://github.com/ghga-de/ghga/blob/main/libs/hexkit/LICENSE).
