---
name: hexkit
description: >
  A Toolkit for Building Microservices using the Hexagonal Architecture. Use when writing Python code that uses the hexkit package.
license: Apache-2.0
compatibility: Requires Python >=3.10.
---

# hexkit

A Toolkit for Building Microservices using the Hexagonal Architecture

## Installation

```bash
pip install hexkit
```

## API overview

### Core Types & Base Classes

Shared type aliases and provider base classes

- `custom_types.ID`
- `custom_types.JsonObject`
- `custom_types.Ascii`
- `custom_types.AsyncConstructable`
- `custom_types.AsyncContextConstructable`
- `custom_types.KafkaCompressionType`
- `custom_types.PytestScope`
- `base.InboundProviderBase`

### General Utilities

Dependency-light helper functions and related errors

- `utils.calc_part_size`
- `utils.check_ascii`
- `utils.validate_fields_in_model`
- `utils.round_datetime_to_ms`
- `utils.now_utc_ms_prec`
- `utils.FieldNotInModelError`
- `utils.NonAsciiStrError`

### Correlation IDs

Correlation-ID context management and helpers

- `correlation.get_correlation_id`
- `correlation.new_correlation_id`
- `correlation.validate_correlation_id`
- `correlation.correlation_id_from_str`
- `correlation.set_context_var`
- `correlation.set_correlation_id`
- `correlation.set_new_correlation_id`
- `correlation.CorrelationIdContextError`
- `correlation.InvalidCorrelationIdError`

### OpenTelemetry

Observability / tracing configuration

- `opentelemetry.OpenTelemetryConfig`
- `opentelemetry.configure_opentelemetry`

### Logging

Structured logging configuration and formatters

- `log.LoggingConfig`
- `log.configure_logging`
- `log.JsonFormatter`
- `log.RecordCompiler`

### Protocols — Events

Ports for event publishing and subscription

- `protocols.eventpub.EventPublisherProtocol`
- `protocols.eventsub.EventSubscriberProtocol`
- `protocols.eventsub.DLQSubscriberProtocol`

### Protocols — Data Access Objects

Ports for DAOs and outbox publishing/subscription

- `protocols.dao.Dao`
- `protocols.dao.DaoFactoryProtocol`
- `protocols.dao.DaoFactoryBase`
- `protocols.dao.FindResult`
- `protocols.daopub.DaoPublisher`
- `protocols.daopub.DaoPublisherFactoryProtocol`
- `protocols.daosub.DaoSubscriberProtocol`
- `protocols.daosub.DtoValidationError`
- `protocols.dao.DaoError`
- `protocols.dao.ResourceNotFoundError`
- `protocols.dao.ResourceAlreadyExistsError`
- `protocols.dao.UniqueConstraintViolationError`
- `protocols.dao.FindError`
- `protocols.dao.InvalidFindMappingError`
- `protocols.dao.MultipleHitsFoundError`
- `protocols.dao.NoHitsFoundError`
- `protocols.dao.DbTimeoutError`

### Protocols — Storage

Ports for key-value and object storage

- `protocols.kvstore.KeyValueStoreProtocol`
- `protocols.objstorage.ObjectStorageProtocol`
- `protocols.objstorage.PresignedPostURL`

### Provider — Apache Kafka

Event pub/sub backed by Apache Kafka

- `providers.akafka.KafkaConfig`
- `providers.akafka.KafkaEventPublisher`
- `providers.akafka.KafkaEventSubscriber`
- `providers.akafka.KafkaOutboxSubscriber`
- `providers.akafka.ComboTranslator`

### Provider — MongoDB

DAO and key-value stores backed by MongoDB

- `providers.mongodb.MongoDbConfig`
- `providers.mongodb.MongoDbDaoFactory`
- `providers.mongodb.MongoDbDao`
- `providers.mongodb.MongoDbBytesKeyValueStore`
- `providers.mongodb.MongoDbStrKeyValueStore`
- `providers.mongodb.MongoDbJsonKeyValueStore`
- `providers.mongodb.MongoDbDtoKeyValueStore`

### MongoDB Migration Tooling

Versioned database migration framework for MongoDB

- `providers.mongodb.migrations.MigrationConfig`
- `providers.mongodb.migrations.MigrationManager`
- `providers.mongodb.migrations.MigrationDefinition`
- `providers.mongodb.migrations.Reversible`
- `providers.mongodb.migrations.check_db_version`
- `providers.mongodb.migrations.validate_doc`
- `providers.mongodb.migrations.MigrationStepError`
- `providers.mongodb.migrations.DbVersionMismatchError`
- `providers.mongodb.migrations.helpers.convert_uuids_and_datetimes_v6`
- `providers.mongodb.migrations.helpers.convert_outbox_correlation_id_v6`
- `providers.mongodb.migrations.helpers.convert_persistent_event_v6`

### Provider — MongoDB + Kafka

Persistent / outbox event publishing

- `providers.mongokafka.MongoKafkaConfig`
- `providers.mongokafka.MongoKafkaDaoPublisherFactory`
- `providers.mongokafka.PersistentKafkaPublisher`
- `providers.mongokafka.PersistentKafkaEvent`

### Provider — S3

Object storage and key-value stores backed by S3

- `providers.s3.S3Config`
- `providers.s3.S3ObjectStorage`
- `providers.s3.S3BytesKeyValueStore`
- `providers.s3.S3StrKeyValueStore`
- `providers.s3.S3JsonKeyValueStore`
- `providers.s3.S3DtoKeyValueStore`

### Provider — Redis

Key-value stores backed by Redis

- `providers.redis.RedisConfig`
- `providers.redis.RedisBytesKeyValueStore`
- `providers.redis.RedisStrKeyValueStore`
- `providers.redis.RedisJsonKeyValueStore`
- `providers.redis.RedisDtoKeyValueStore`

### Provider — HashiCorp Vault

Key-value stores backed by Vault

- `providers.vault.VaultConfig`
- `providers.vault.VaultBytesKeyValueStore`
- `providers.vault.VaultStrKeyValueStore`
- `providers.vault.VaultJsonKeyValueStore`
- `providers.vault.VaultDtoKeyValueStore`

### Provider — In-Memory (Testing)

In-memory providers and mocks for tests

- `providers.testing.InMemEventPublisher`
- `providers.testing.InMemEventStore`
- `providers.testing.InMemBytesKeyValueStore`
- `providers.testing.InMemStrKeyValueStore`
- `providers.testing.InMemJsonKeyValueStore`
- `providers.testing.InMemDtoKeyValueStore`
- `providers.testing.new_mock_dao_class`
- `providers.testing.MockDAOEmptyError`
- `providers.testing.TopicExhaustedError`

## Resources

- [Full documentation](https://ghga-de.github.io/hexkit/)
- [llms.txt](llms.txt) — Indexed API reference for LLMs
- [llms-full.txt](llms-full.txt) — Comprehensive documentation for LLMs
- [Source code](https://github.com/ghga-de/hexkit)