Reference

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: Base class that should be used by inbound providers.

General Utilities

Dependency-light helper functions and related errors

utils.calc_part_size(): Gives recommendations on the part_size to use for up- or download of a file given
utils.check_ascii(): Checks that the provided str_values are ASCII compatible,
utils.validate_fields_in_model(): Checks that all provided fields are present in the dto_model.
utils.round_datetime_to_ms(): Round a datetime object to nearest millisecond.
utils.now_utc_ms_prec(): Return the current UTC time with microseconds rounded to milliseconds.
utils.FieldNotInModelError: Raised when provided fields where not contained in a pydantic model.
utils.NonAsciiStrError: Thrown when non-ASCII string was unexpectedly provided

Correlation IDs

Correlation-ID context management and helpers

correlation.get_correlation_id(): Get the correlation ID.
correlation.new_correlation_id(): Generates a new correlation ID.
correlation.validate_correlation_id(): Validate the correlation ID.
correlation.correlation_id_from_str(): Convert a string to a UUID4.
correlation.set_context_var(): An async context manager to simplify the use of ContextVars.
correlation.set_correlation_id(): Set the given correlation ID for the life of the context.
correlation.set_new_correlation_id(): Set a new correlation ID for the life of the context.
correlation.CorrelationIdContextError: Raised when the correlation ID ContextVar is unexpectedly not set.
correlation.InvalidCorrelationIdError: Raised when a correlation ID fails validation.

OpenTelemetry

Observability / tracing configuration

opentelemetry.OpenTelemetryConfig: OpenTelemetry specific configuration options
opentelemetry.configure_opentelemetry(): Configure all needed parts of OpenTelemetry.

Logging

Structured logging configuration and formatters

log.LoggingConfig: A class containing logging config.
log.configure_logging(): Set up logging.
log.JsonFormatter: A formatter class that outputs logs in JSON format.
log.RecordCompiler: A class to make all non-standard information available to formatters.

Protocols — Events

Ports for event publishing and subscription

protocols.eventpub.EventPublisherProtocol: A protocol for publishing events to an event broker.
protocols.eventsub.EventSubscriberProtocol: A protocol for consuming events from an event broker.
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: A duck type with methods common to all DAOs.
protocols.dao.DaoFactoryProtocol: A protocol describing a factory to produce Data Access Objects (DAO) objects
protocols.dao.DaoFactoryBase: A base for Data Access Objects (DAO) Factory protocols.
protocols.dao.FindResult: An async-iterable result from find_all() that also exposes pagination metadata.
protocols.daopub.DaoPublisher: A Data Access Object (DAO) that automatically publishes changes according to the
protocols.daopub.DaoPublisherFactoryProtocol: A protocol describing a factory to produce Data Access Objects (DAO) objects
protocols.daosub.DaoSubscriberProtocol: A protocol for consuming events published through the DaoPublisherFactoryProtocol.
protocols.daosub.DtoValidationError: Raised when the payload of a received event was not formatted as expected.
protocols.dao.DaoError: Base for all errors related to DAO operations.
protocols.dao.ResourceNotFoundError: Raised when a requested resource did not exist.
protocols.dao.ResourceAlreadyExistsError: Raised when a resource did unexpectedly exist.
protocols.dao.UniqueConstraintViolationError: Raised when attempting to insert a resource violated a uniqueness constraint.
protocols.dao.FindError: Base for all error related to DAO find operations.
protocols.dao.InvalidFindMappingError: Raised when an invalid mapping was passed provided to find.
protocols.dao.MultipleHitsFoundError: Raised when a DAO find operation did result in multiple hits while only a
protocols.dao.NoHitsFoundError: Raised when a DAO find operation did result in no hits while a
protocols.dao.DbTimeoutError: Raised when a database operation timed out.

Protocols — Storage

Ports for key-value and object storage

protocols.kvstore.KeyValueStoreProtocol: A protocol for a key-value store.
protocols.objstorage.ObjectStorageProtocol: Protocol for interacting with S3-like Object Storages.
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: Config parameters needed for connecting to Apache Kafka.
providers.akafka.KafkaEventPublisher: Apache Kafka specific event publishing provider.
providers.akafka.KafkaEventSubscriber: Apache Kafka-specific event subscription provider.
providers.akafka.KafkaOutboxSubscriber: Apache Kafka-specific provider using translators that implement the
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: Configuration parameters for connecting to a MongoDB server.
providers.mongodb.MongoDbDaoFactory: A MongoDB-based provider implementing the DaoFactoryProtocol.
providers.mongodb.MongoDbDao: A MongoDb-specific DAO.
providers.mongodb.MongoDbBytesKeyValueStore: MongoDB specific KVStore provider for binary (bytes) data.
providers.mongodb.MongoDbStrKeyValueStore: MongoDB specific KVStore provider for string data.
providers.mongodb.MongoDbJsonKeyValueStore: MongoDB specific KVStore provider for JSON data.
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: Minimal configuration required to run the migration process.
providers.mongodb.migrations.MigrationManager: Top-level logic for ensuring the database is updated before running the service.
providers.mongodb.migrations.MigrationDefinition: Contains all logic to migrate the database from one version to the next.
providers.mongodb.migrations.Reversible: Mixin class to mark a migration class as reversible.
providers.mongodb.migrations.check_db_version(): Verify that the database is at target_version, raising an error if not.
providers.mongodb.migrations.validate_doc(): Ensure that new content passes model validation.
providers.mongodb.migrations.MigrationStepError: Raised when a specific migration step fails, e.g. migrating from v4 to v5
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(): Produce a function to convert a document to the format expected by hexkit v6.
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(): Convert a persistent event document to the format expected by hexkit v6.

Provider — MongoDB + Kafka

Persistent / outbox event publishing

providers.mongokafka.MongoKafkaConfig: Config parameters and their defaults.
providers.mongokafka.MongoKafkaDaoPublisherFactory: A provider implementing the DaoPublisherFactoryProtocol based on MongoDB and
providers.mongokafka.PersistentKafkaPublisher: A Kafka event publisher that uses a MongoDB DAO to store stateless events as-is.
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: S3-specific config params.
providers.s3.S3ObjectStorage: S3-based provider implementing the ObjectStorageProtocol.
providers.s3.S3BytesKeyValueStore: S3-specific KVStore provider for binary (bytes) data.
providers.s3.S3StrKeyValueStore: S3-specific KVStore provider for string data.
providers.s3.S3JsonKeyValueStore: S3-specific KVStore provider for JSON data.
providers.s3.S3DtoKeyValueStore: S3-specific KVStore provider for Pydantic model (DTO) data.

Provider — Redis

Key-value stores backed by Redis

providers.redis.RedisConfig: Configuration parameters for connecting to a Redis server.
providers.redis.RedisBytesKeyValueStore: Redis-specific KVStore provider for binary (bytes) data.
providers.redis.RedisStrKeyValueStore: Redis-specific KVStore provider for string data.
providers.redis.RedisJsonKeyValueStore: Redis-specific KVStore provider for JSON data.
providers.redis.RedisDtoKeyValueStore: Redis-specific KVStore provider for Pydantic model (DTO) data.

Provider — HashiCorp Vault

Key-value stores backed by Vault

providers.vault.VaultConfig: Configuration parameters for connecting to a HashiCorp Vault server.
providers.vault.VaultBytesKeyValueStore: Vault-specific KVStore provider for binary (bytes) data.
providers.vault.VaultStrKeyValueStore: Vault-specific KVStore provider for string data.
providers.vault.VaultJsonKeyValueStore: Vault-specific KVStore provider for JSON data.
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: An in-memory EventPublisher for testing purposes.
providers.testing.InMemEventStore: A manager for multiple topics, whereby each topic is model as queue not as log.
providers.testing.InMemBytesKeyValueStore: In-memory KVStore provider for binary (bytes) data.
providers.testing.InMemStrKeyValueStore: In-memory KVStore provider for string data.
providers.testing.InMemJsonKeyValueStore: In-memory KVStore provider for JSON objects.
providers.testing.InMemDtoKeyValueStore: In-memory KVStore provider for Pydantic model (DTO) data.
providers.testing.new_mock_dao_class(): Produce a mock DAO for the given DTO model and ID field.
providers.testing.MockDAOEmptyError: Raised when attempting to access the latest property of an empty mock DAO
providers.testing.TopicExhaustedError: Thrown when now more event are queued in a topic.