---
title: "Changelog 4.4.0"
description: "Release notes for ArchiPy 4.4.0"
---

# 4.4.0 — 2026-03-13

[← 4.3.6](4.3.6.md) | [↑ 4.x series](index.md)

## Added

### Adapters - Kafka

- **Async Kafka Producer Adapter** - Introduced `AsyncKafkaProducerAdapter` for non-blocking message production using
  `confluent-kafka`'s thread-based async delivery model.
    - Implements the new `AsyncKafkaProducerPort` interface with `async produce`, `async flush`, and `async close`
      methods
    - Lazy-initialises the underlying `confluent-kafka` `Producer` on first use to avoid blocking the event loop at
      construction time
    - Supports configurable worker threads (`kafka_async_worker_threads`) and buffer flush timeout
      (`kafka_async_buffer_timeout_seconds`) via `KafkaConfig`
- **Async Kafka Consumer Adapter** - Introduced `AsyncKafkaConsumerAdapter` for non-blocking message consumption.
    - Implements the new `AsyncKafkaConsumerPort` interface with `async consume`, `async subscribe`, `async commit`,
      and `async close` methods
    - Offloads blocking `confluent-kafka` `Consumer` calls to a thread pool executor to keep the event loop free
- **Async Kafka Ports** - Added `AsyncKafkaProducerPort` and `AsyncKafkaConsumerPort` abstract base classes to
  `archipy/adapters/kafka/ports.py`.
    - Defines the async contract that all async Kafka adapter implementations must satisfy
- **Close Methods on Sync Adapters** - Added explicit `close()` methods to `KafkaConsumerAdapter` and
  `KafkaProducerAdapter` for deterministic resource cleanup.

### Configs - Kafka

- **Async Kafka Config Fields** - Extended `KafkaConfig` with two new settings for the async adapters.
    - `kafka_async_worker_threads: int` — number of threads in the async executor pool (default `4`)
    - `kafka_async_buffer_timeout_seconds: float` — maximum seconds to wait when flushing the producer buffer on close
      (default `5.0`)

### Tests - Kafka

- **Async BDD Scenarios** - Expanded `features/kafka_adapters.feature` with end-to-end scenarios for
  `AsyncKafkaProducerAdapter` and `AsyncKafkaConsumerAdapter`.
    - Covers produce, consume, subscribe, commit, flush, and close lifecycle
    - Step implementations in `features/steps/kafka_adapter_steps.py` use `await` throughout instead of
      `asyncio.run()`

## Changed

### Tests - BDD

- **Async Step Implementations** - Refactored all async Behave step functions across multiple feature files to use
  `await` instead of `asyncio.run()`.
    - Affected files: `atomic_transaction_steps.py`, `error_utils_steps.py`, `grpc_error_handling_steps.py`,
      `metric_interceptor_steps.py`
    - Eliminates nested event-loop errors when steps run inside an already-running loop
- **`test_helpers.py` Cleanup** - Removed deprecated utility functions from `features/test_helpers.py` that were
  superseded by the async step refactor.

## Chore

### Docs - Kafka

- **Kafka Tutorial Expansion** - Substantially expanded `docs/tutorials/adapters/kafka.md` to document all five
  adapter classes (`KafkaAdminAdapter`, `KafkaConsumerAdapter`, `KafkaProducerAdapter`,
  `AsyncKafkaConsumerAdapter`, `AsyncKafkaProducerAdapter`).
    - Added dedicated sections for async adapters, lazy initialisation behaviour, and usage in non-async contexts
    - Improved logging examples for consistency with documentation standards
- **Kafka API Reference Update** - Updated `docs/api_reference/adapters/kafka.md` to list all five adapter classes
  and their async configuration options.
- **Documentation Admonition Style** - Migrated all admonitions across 19 documentation files from MkDocs `!!!`
  directives to block-quote callouts (`> **Type:** ...`) to prevent formatting issues in PyCharm.
- **Quickstart Redis Update** - Updated `docs/getting-started/quickstart.md` to reflect the current Redis caching
  implementation.
- **BDD Testing Rule Update** - Clarified Behave version (1.3.3) and async step conventions in
  `.cursor/rules/testing-bdd.mdc`.
