Metadata-Version: 2.4
Name: hexkit
Version: 8.5.0
Summary: A Toolkit for Building Microservices using the Hexagonal Architecture
Author-email: "German Human Genome Phenome Archive (GHGA)" <contact@ghga.de>
License: Apache 2.0
Project-URL: Repository, https://github.com/ghga-de/hexkit
Project-URL: Documentation, https://ghga-de.github.io/hexkit/
Project-URL: Release Notes, https://github.com/ghga-de/hexkit/releases
Project-URL: Issue Tracker, https://github.com/ghga-de/hexkit/issues
Classifier: Development Status :: 5 - Production/Stable
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: Software Development :: Libraries
Classifier: Intended Audience :: Developers
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: opentelemetry-api<2,>=1.39
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.39.1; extra == "opentelemetry-base"
Requires-Dist: opentelemetry-exporter-otlp<2,>=1.39.1; extra == "opentelemetry-base"
Requires-Dist: opentelemetry-instrumentation>=0.60b1; extra == "opentelemetry-base"
Requires-Dist: opentelemetry-instrumentation-httpx>=0.60b1; extra == "opentelemetry-base"
Requires-Dist: opentelemetry-distro>=0.60b1; 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.60b1; 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.60b1; extra == "opentelemetry-mongodb"
Provides-Extra: opentelemetry-fastapi
Requires-Dist: hexkit[opentelemetry-base]; extra == "opentelemetry-fastapi"
Requires-Dist: opentelemetry-instrumentation-fastapi>=0.60b1; 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.60b1; 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.60b1; 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.14; extra == "test-akafka"
Provides-Extra: test-s3
Requires-Dist: hexkit[s3]; extra == "test-s3"
Requires-Dist: testcontainers<5,>=4.14; extra == "test-s3"
Provides-Extra: test-mongodb
Requires-Dist: hexkit[mongodb]; extra == "test-mongodb"
Requires-Dist: testcontainers[mongo]<5,>=4.14; extra == "test-mongodb"
Provides-Extra: test-redis
Requires-Dist: hexkit[redis]; extra == "test-redis"
Requires-Dist: testcontainers[redis]<5,>=4.14; extra == "test-redis"
Provides-Extra: test-vault
Requires-Dist: hexkit[vault]; extra == "test-vault"
Requires-Dist: testcontainers<5,>=4.14; 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

[![PyPI version shields.io](https://img.shields.io/pypi/v/hexkit.svg)](https://pypi.python.org/pypi/hexkit/)
[![PyPI pyversions](https://img.shields.io/pypi/pyversions/hexkit.svg)](https://pypi.python.org/pypi/hexkit/)
![tests](https://github.com/ghga-de/hexkit/actions/workflows/tests.yaml/badge.svg)
[![Coverage Status](https://coveralls.io/repos/github/ghga-de/hexkit/badge.svg?branch=main)](https://coveralls.io/github/ghga-de/hexkit?branch=main)
[![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/)

# 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/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/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/hexkit/user-guide/) covers all
protocols, providers, testing utilities, and observability tools with example code,
and the [API Reference](https://ghga-de.github.io/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/hexkit/tree/main/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/hexkit/tree/main/src/hexkit/protocols)
and the providers being implemented at
[src/hexkit/providers](https://github.com/ghga-de/hexkit/tree/main/src/hexkit/providers).

## 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! Please see the
[contribution guide](https://github.com/ghga-de/hexkit/blob/main/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

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