# API Reference


## Core Types & Base Classes


Shared type aliases and provider base classes


[custom_types.ID](custom_types.ID.md#hexkit.custom_types.ID)  

[custom_types.JsonObject](custom_types.JsonObject.md#hexkit.custom_types.JsonObject)  

[custom_types.Ascii](custom_types.Ascii.md#hexkit.custom_types.Ascii)  

[custom_types.AsyncConstructable](custom_types.AsyncConstructable.md#hexkit.custom_types.AsyncConstructable)  

[custom_types.AsyncContextConstructable](custom_types.AsyncContextConstructable.md#hexkit.custom_types.AsyncContextConstructable)  

[custom_types.KafkaCompressionType](custom_types.KafkaCompressionType.md#hexkit.custom_types.KafkaCompressionType)  

[custom_types.PytestScope](custom_types.PytestScope.md#hexkit.custom_types.PytestScope)  

[base.InboundProviderBase](base.InboundProviderBase.md#hexkit.base.InboundProviderBase)  
Base class that should be used by inbound providers.


## Configuration


Layering of configuration sources for service config classes


[config.config_from_yaml()](config.config_from_yaml.md#hexkit.config.config_from_yaml)  
A factory that returns decorator functions which extends a

[config.get_default_config_yaml()](config.get_default_config_yaml.md#hexkit.config.get_default_config_yaml)  
Get the path to the default config function.

[config.ConfigYamlDoesNotExist](config.ConfigYamlDoesNotExist.md#hexkit.config.ConfigYamlDoesNotExist)  
Thrown when the context manager is used out of context.


## General Utilities


Dependency-light helper functions and related errors


[utils.calc_part_size()](utils.calc_part_size.md#hexkit.utils.calc_part_size)  
Gives recommendations on the part_size to use for up- or download of a file given

[utils.check_ascii()](utils.check_ascii.md#hexkit.utils.check_ascii)  
Checks that the provided `str_values` are ASCII compatible,

[utils.validate_fields_in_model()](utils.validate_fields_in_model.md#hexkit.utils.validate_fields_in_model)  
Checks that all provided fields are present in the dto_model.

[utils.round_datetime_to_ms()](utils.round_datetime_to_ms.md#hexkit.utils.round_datetime_to_ms)  
Round a datetime object to nearest millisecond.

[utils.now_utc_ms_prec()](utils.now_utc_ms_prec.md#hexkit.utils.now_utc_ms_prec)  
Return the current UTC time with microseconds rounded to milliseconds.

[utils.FieldNotInModelError](utils.FieldNotInModelError.md#hexkit.utils.FieldNotInModelError)  
Raised when provided fields where not contained in a pydantic model.

[utils.NonAsciiStrError](utils.NonAsciiStrError.md#hexkit.utils.NonAsciiStrError)  
Thrown when non-ASCII string was unexpectedly provided


## Correlation IDs


Correlation-ID context management and helpers


[correlation.get_correlation_id()](correlation.get_correlation_id.md#hexkit.correlation.get_correlation_id)  
Get the correlation ID.

[correlation.new_correlation_id()](correlation.new_correlation_id.md#hexkit.correlation.new_correlation_id)  
Generates a new correlation ID.

[correlation.validate_correlation_id()](correlation.validate_correlation_id.md#hexkit.correlation.validate_correlation_id)  
Validate the correlation ID.

[correlation.correlation_id_from_str()](correlation.correlation_id_from_str.md#hexkit.correlation.correlation_id_from_str)  
Convert a string to a UUID4.

[correlation.set_context_var()](correlation.set_context_var.md#hexkit.correlation.set_context_var)  
An async context manager to simplify the use of ContextVars.

[correlation.set_correlation_id()](correlation.set_correlation_id.md#hexkit.correlation.set_correlation_id)  
Set the given correlation ID for the life of the context.

[correlation.set_new_correlation_id()](correlation.set_new_correlation_id.md#hexkit.correlation.set_new_correlation_id)  
Set a new correlation ID for the life of the context.

[correlation.CorrelationIdContextError](correlation.CorrelationIdContextError.md#hexkit.correlation.CorrelationIdContextError)  
Raised when the correlation ID ContextVar is unexpectedly not set.

[correlation.InvalidCorrelationIdError](correlation.InvalidCorrelationIdError.md#hexkit.correlation.InvalidCorrelationIdError)  
Raised when a correlation ID fails validation.


## OpenTelemetry


Observability / tracing configuration


[opentelemetry.OpenTelemetryConfig](opentelemetry.OpenTelemetryConfig.md#hexkit.opentelemetry.OpenTelemetryConfig)  
OpenTelemetry specific configuration options

[opentelemetry.configure_opentelemetry()](opentelemetry.configure_opentelemetry.md#hexkit.opentelemetry.configure_opentelemetry)  
Configure all needed parts of OpenTelemetry.


## Logging


Structured logging configuration and formatters


[log.LoggingConfig](log.LoggingConfig.md#hexkit.log.LoggingConfig)  
A class containing logging config.

[log.configure_logging()](log.configure_logging.md#hexkit.log.configure_logging)  
Set up logging.

[log.JsonFormatter](log.JsonFormatter.md#hexkit.log.JsonFormatter)  
A formatter class that outputs logs in JSON format.

[log.RecordCompiler](log.RecordCompiler.md#hexkit.log.RecordCompiler)  
A class to make all non-standard information available to formatters.


## Protocols -- Events


Ports for event publishing and subscription


[protocols.eventpub.EventPublisherProtocol](protocols.eventpub.EventPublisherProtocol.md#hexkit.protocols.eventpub.EventPublisherProtocol)  
A protocol for publishing events to an event broker.

[protocols.eventsub.EventSubscriberProtocol](protocols.eventsub.EventSubscriberProtocol.md#hexkit.protocols.eventsub.EventSubscriberProtocol)  
A protocol for consuming events from an event broker.

[protocols.eventsub.DLQSubscriberProtocol](protocols.eventsub.DLQSubscriberProtocol.md#hexkit.protocols.eventsub.DLQSubscriberProtocol)  
A protocol for consuming events from an event broker with the header data included.


## Protocols -- Data Access Objects


Ports for DAOs and outbox publishing/subscription


[protocols.dao.Dao](protocols.dao.Dao.md#hexkit.protocols.dao.Dao)  
A duck type with methods common to all DAOs.

[protocols.dao.DaoFactoryProtocol](protocols.dao.DaoFactoryProtocol.md#hexkit.protocols.dao.DaoFactoryProtocol)  
A protocol describing a factory to produce Data Access Objects (DAO) objects

[protocols.dao.DaoFactoryBase](protocols.dao.DaoFactoryBase.md#hexkit.protocols.dao.DaoFactoryBase)  
A base for Data Access Objects (DAO) Factory protocols.

[protocols.dao.FindResult](protocols.dao.FindResult.md#hexkit.protocols.dao.FindResult)  
An async-iterable result from find_all() that also exposes pagination metadata.

[protocols.daopub.DaoPublisher](protocols.daopub.DaoPublisher.md#hexkit.protocols.daopub.DaoPublisher)  
A Data Access Object (DAO) that automatically publishes changes according to the

[protocols.daopub.DaoPublisherFactoryProtocol](protocols.daopub.DaoPublisherFactoryProtocol.md#hexkit.protocols.daopub.DaoPublisherFactoryProtocol)  
A protocol describing a factory to produce Data Access Objects (DAO) objects

[protocols.daosub.DaoSubscriberProtocol](protocols.daosub.DaoSubscriberProtocol.md#hexkit.protocols.daosub.DaoSubscriberProtocol)  
A protocol for consuming events published through the DaoPublisherFactoryProtocol.

[protocols.daosub.DtoValidationError](protocols.daosub.DtoValidationError.md#hexkit.protocols.daosub.DtoValidationError)  
Raised when the payload of a received event was not formatted as expected.

[protocols.dao.DaoError](protocols.dao.DaoError.md#hexkit.protocols.dao.DaoError)  
Base for all errors related to DAO operations.

[protocols.dao.ResourceNotFoundError](protocols.dao.ResourceNotFoundError.md#hexkit.protocols.dao.ResourceNotFoundError)  
Raised when a requested resource did not exist.

[protocols.dao.ResourceAlreadyExistsError](protocols.dao.ResourceAlreadyExistsError.md#hexkit.protocols.dao.ResourceAlreadyExistsError)  
Raised when a resource did unexpectedly exist.

[protocols.dao.UniqueConstraintViolationError](protocols.dao.UniqueConstraintViolationError.md#hexkit.protocols.dao.UniqueConstraintViolationError)  
Raised when attempting to insert a resource violated a uniqueness constraint.

[protocols.dao.FindError](protocols.dao.FindError.md#hexkit.protocols.dao.FindError)  
Base for all error related to DAO find operations.

[protocols.dao.InvalidFindMappingError](protocols.dao.InvalidFindMappingError.md#hexkit.protocols.dao.InvalidFindMappingError)  
Raised when an invalid mapping was passed provided to find.

[protocols.dao.MultipleHitsFoundError](protocols.dao.MultipleHitsFoundError.md#hexkit.protocols.dao.MultipleHitsFoundError)  
Raised when a DAO find operation did result in multiple hits while only a

[protocols.dao.NoHitsFoundError](protocols.dao.NoHitsFoundError.md#hexkit.protocols.dao.NoHitsFoundError)  
Raised when a DAO find operation did result in no hits while a

[protocols.dao.DbTimeoutError](protocols.dao.DbTimeoutError.md#hexkit.protocols.dao.DbTimeoutError)  
Raised when a database operation timed out.


## Protocols -- Storage


Ports for key-value and object storage


[protocols.kvstore.KeyValueStoreProtocol](protocols.kvstore.KeyValueStoreProtocol.md#hexkit.protocols.kvstore.KeyValueStoreProtocol)  
A protocol for a key-value store.

[protocols.objstorage.ObjectStorageProtocol](protocols.objstorage.ObjectStorageProtocol.md#hexkit.protocols.objstorage.ObjectStorageProtocol)  
Protocol for interacting with S3-like Object Storages.

[protocols.objstorage.PresignedPostURL](protocols.objstorage.PresignedPostURL.md#hexkit.protocols.objstorage.PresignedPostURL)  
Container for presigned POST URLs along with additional metadata fields that


## Provider -- Apache Kafka


Event pub/sub backed by Apache Kafka


[providers.akafka.KafkaConfig](providers.akafka.KafkaConfig.md#hexkit.providers.akafka.KafkaConfig)  
Config parameters needed for connecting to Apache Kafka.

[providers.akafka.KafkaEventPublisher](providers.akafka.KafkaEventPublisher.md#hexkit.providers.akafka.KafkaEventPublisher)  
Apache Kafka specific event publishing provider.

[providers.akafka.KafkaEventSubscriber](providers.akafka.KafkaEventSubscriber.md#hexkit.providers.akafka.KafkaEventSubscriber)  
Apache Kafka-specific event subscription provider.

[providers.akafka.KafkaOutboxSubscriber](providers.akafka.KafkaOutboxSubscriber.md#hexkit.providers.akafka.KafkaOutboxSubscriber)  
Apache Kafka-specific provider using translators that implement the

[providers.akafka.ComboTranslator](providers.akafka.ComboTranslator.md#hexkit.providers.akafka.ComboTranslator)  
Takes a list of translators implementing either the `DaoSubscriberProtocol`,


## Provider -- MongoDB


DAO and key-value stores backed by MongoDB


[providers.mongodb.MongoDbConfig](providers.mongodb.MongoDbConfig.md#hexkit.providers.mongodb.MongoDbConfig)  
Configuration parameters for connecting to a MongoDB server.

[providers.mongodb.MongoDbDaoFactory](providers.mongodb.MongoDbDaoFactory.md#hexkit.providers.mongodb.MongoDbDaoFactory)  
A MongoDB-based provider implementing the DaoFactoryProtocol.

[providers.mongodb.MongoDbDao](providers.mongodb.MongoDbDao.md#hexkit.providers.mongodb.MongoDbDao)  
A MongoDb-specific DAO.

[providers.mongodb.MongoDbBytesKeyValueStore](providers.mongodb.MongoDbBytesKeyValueStore.md#hexkit.providers.mongodb.MongoDbBytesKeyValueStore)  
MongoDB specific KVStore provider for binary (bytes) data.

[providers.mongodb.MongoDbStrKeyValueStore](providers.mongodb.MongoDbStrKeyValueStore.md#hexkit.providers.mongodb.MongoDbStrKeyValueStore)  
MongoDB specific KVStore provider for string data.

[providers.mongodb.MongoDbJsonKeyValueStore](providers.mongodb.MongoDbJsonKeyValueStore.md#hexkit.providers.mongodb.MongoDbJsonKeyValueStore)  
MongoDB specific KVStore provider for JSON data.

[providers.mongodb.MongoDbDtoKeyValueStore](providers.mongodb.MongoDbDtoKeyValueStore.md#hexkit.providers.mongodb.MongoDbDtoKeyValueStore)  
MongoDB specific KVStore provider for Pydantic model (DTO) data.


## MongoDB Migration Tooling


Versioned database migration framework for MongoDB


[providers.mongodb.migrations.MigrationConfig](providers.mongodb.migrations.MigrationConfig.md#hexkit.providers.mongodb.migrations.MigrationConfig)  
Minimal configuration required to run the migration process.

[providers.mongodb.migrations.MigrationManager](providers.mongodb.migrations.MigrationManager.md#hexkit.providers.mongodb.migrations.MigrationManager)  
Top-level logic for ensuring the database is updated before running the service.

[providers.mongodb.migrations.MigrationDefinition](providers.mongodb.migrations.MigrationDefinition.md#hexkit.providers.mongodb.migrations.MigrationDefinition)  
Contains all logic to migrate the database from one version to the next.

[providers.mongodb.migrations.Reversible](providers.mongodb.migrations.Reversible.md#hexkit.providers.mongodb.migrations.Reversible)  
Mixin class to mark a migration class as reversible.

[providers.mongodb.migrations.check_db_version()](providers.mongodb.migrations.check_db_version.md#hexkit.providers.mongodb.migrations.check_db_version)  
Verify that the database is at `target_version`, raising an error if not.

[providers.mongodb.migrations.validate_doc()](providers.mongodb.migrations.validate_doc.md#hexkit.providers.mongodb.migrations.validate_doc)  
Ensure that new content passes model validation.

[providers.mongodb.migrations.MigrationStepError](providers.mongodb.migrations.MigrationStepError.md#hexkit.providers.mongodb.migrations.MigrationStepError)  
Raised when a specific migration step fails, e.g. migrating from v4 to v5

[providers.mongodb.migrations.DbVersionMismatchError](providers.mongodb.migrations.DbVersionMismatchError.md#hexkit.providers.mongodb.migrations.DbVersionMismatchError)  
Raised when the database is not at the version expected by the service.

[providers.mongodb.migrations.helpers.convert_uuids_and_datetimes_v6()](providers.mongodb.migrations.helpers.convert_uuids_and_datetimes_v6.md#hexkit.providers.mongodb.migrations.helpers.convert_uuids_and_datetimes_v6)  
Produce a function to convert a document to the format expected by hexkit v6.

[providers.mongodb.migrations.helpers.convert_outbox_correlation_id_v6()](providers.mongodb.migrations.helpers.convert_outbox_correlation_id_v6.md#hexkit.providers.mongodb.migrations.helpers.convert_outbox_correlation_id_v6)  
Convert an outbox document's correlation ID to the format expected by hexkit v6.

[providers.mongodb.migrations.helpers.convert_persistent_event_v6()](providers.mongodb.migrations.helpers.convert_persistent_event_v6.md#hexkit.providers.mongodb.migrations.helpers.convert_persistent_event_v6)  
Convert a persistent event document to the format expected by hexkit v6.


## Provider -- MongoDB + Kafka


Persistent / outbox event publishing


[providers.mongokafka.MongoKafkaConfig](providers.mongokafka.MongoKafkaConfig.md#hexkit.providers.mongokafka.MongoKafkaConfig)  
Config parameters and their defaults.

[providers.mongokafka.MongoKafkaDaoPublisherFactory](providers.mongokafka.MongoKafkaDaoPublisherFactory.md#hexkit.providers.mongokafka.MongoKafkaDaoPublisherFactory)  
A provider implementing the DaoPublisherFactoryProtocol based on MongoDB and

[providers.mongokafka.PersistentKafkaPublisher](providers.mongokafka.PersistentKafkaPublisher.md#hexkit.providers.mongokafka.PersistentKafkaPublisher)  
A Kafka event publisher that uses a MongoDB DAO to store stateless events as-is.

[providers.mongokafka.PersistentKafkaEvent](providers.mongokafka.PersistentKafkaEvent.md#hexkit.providers.mongokafka.PersistentKafkaEvent)  
A model representing a kafka event to be published and stored in the database.


## Provider -- S3


Object storage and key-value stores backed by S3


[providers.s3.S3Config](providers.s3.S3Config.md#hexkit.providers.s3.S3Config)  
S3-specific config params.

[providers.s3.S3ObjectStorage](providers.s3.S3ObjectStorage.md#hexkit.providers.s3.S3ObjectStorage)  
S3-based provider implementing the ObjectStorageProtocol.

[providers.s3.S3BytesKeyValueStore](providers.s3.S3BytesKeyValueStore.md#hexkit.providers.s3.S3BytesKeyValueStore)  
S3-specific KVStore provider for binary (bytes) data.

[providers.s3.S3StrKeyValueStore](providers.s3.S3StrKeyValueStore.md#hexkit.providers.s3.S3StrKeyValueStore)  
S3-specific KVStore provider for string data.

[providers.s3.S3JsonKeyValueStore](providers.s3.S3JsonKeyValueStore.md#hexkit.providers.s3.S3JsonKeyValueStore)  
S3-specific KVStore provider for JSON data.

[providers.s3.S3DtoKeyValueStore](providers.s3.S3DtoKeyValueStore.md#hexkit.providers.s3.S3DtoKeyValueStore)  
S3-specific KVStore provider for Pydantic model (DTO) data.


## Provider -- Redis


Key-value stores backed by Redis


[providers.redis.RedisConfig](providers.redis.RedisConfig.md#hexkit.providers.redis.RedisConfig)  
Configuration parameters for connecting to a Redis server.

[providers.redis.RedisBytesKeyValueStore](providers.redis.RedisBytesKeyValueStore.md#hexkit.providers.redis.RedisBytesKeyValueStore)  
Redis-specific KVStore provider for binary (bytes) data.

[providers.redis.RedisStrKeyValueStore](providers.redis.RedisStrKeyValueStore.md#hexkit.providers.redis.RedisStrKeyValueStore)  
Redis-specific KVStore provider for string data.

[providers.redis.RedisJsonKeyValueStore](providers.redis.RedisJsonKeyValueStore.md#hexkit.providers.redis.RedisJsonKeyValueStore)  
Redis-specific KVStore provider for JSON data.

[providers.redis.RedisDtoKeyValueStore](providers.redis.RedisDtoKeyValueStore.md#hexkit.providers.redis.RedisDtoKeyValueStore)  
Redis-specific KVStore provider for Pydantic model (DTO) data.


## Provider -- HashiCorp Vault


Key-value stores backed by Vault


[providers.vault.VaultConfig](providers.vault.VaultConfig.md#hexkit.providers.vault.VaultConfig)  
Configuration parameters for connecting to a HashiCorp Vault server.

[providers.vault.VaultBytesKeyValueStore](providers.vault.VaultBytesKeyValueStore.md#hexkit.providers.vault.VaultBytesKeyValueStore)  
Vault-specific KVStore provider for binary (bytes) data.

[providers.vault.VaultStrKeyValueStore](providers.vault.VaultStrKeyValueStore.md#hexkit.providers.vault.VaultStrKeyValueStore)  
Vault-specific KVStore provider for string data.

[providers.vault.VaultJsonKeyValueStore](providers.vault.VaultJsonKeyValueStore.md#hexkit.providers.vault.VaultJsonKeyValueStore)  
Vault-specific KVStore provider for JSON data.

[providers.vault.VaultDtoKeyValueStore](providers.vault.VaultDtoKeyValueStore.md#hexkit.providers.vault.VaultDtoKeyValueStore)  
Vault-specific KVStore provider for Pydantic model (DTO) data.


## Provider -- In-Memory (Testing)


In-memory providers and mocks for tests


[providers.testing.InMemEventPublisher](providers.testing.InMemEventPublisher.md#hexkit.providers.testing.InMemEventPublisher)  
An in-memory EventPublisher for testing purposes.

[providers.testing.InMemEventStore](providers.testing.InMemEventStore.md#hexkit.providers.testing.InMemEventStore)  
A manager for multiple topics, whereby each topic is model as queue not as log.

[providers.testing.InMemBytesKeyValueStore](providers.testing.InMemBytesKeyValueStore.md#hexkit.providers.testing.InMemBytesKeyValueStore)  
In-memory KVStore provider for binary (bytes) data.

[providers.testing.InMemStrKeyValueStore](providers.testing.InMemStrKeyValueStore.md#hexkit.providers.testing.InMemStrKeyValueStore)  
In-memory KVStore provider for string data.

[providers.testing.InMemJsonKeyValueStore](providers.testing.InMemJsonKeyValueStore.md#hexkit.providers.testing.InMemJsonKeyValueStore)  
In-memory KVStore provider for JSON objects.

[providers.testing.InMemDtoKeyValueStore](providers.testing.InMemDtoKeyValueStore.md#hexkit.providers.testing.InMemDtoKeyValueStore)  
In-memory KVStore provider for Pydantic model (DTO) data.

[providers.testing.new_mock_dao_class()](providers.testing.new_mock_dao_class.md#hexkit.providers.testing.new_mock_dao_class)  
Produce a mock DAO for the given DTO model and ID field.

[providers.testing.MockDAOEmptyError](providers.testing.MockDAOEmptyError.md#hexkit.providers.testing.MockDAOEmptyError)  
Raised when attempting to access the `latest` property of an empty mock DAO

[providers.testing.TopicExhaustedError](providers.testing.TopicExhaustedError.md#hexkit.providers.testing.TopicExhaustedError)  
Thrown when now more event are queued in a topic.