4.9.0

Added

Adapters - Kafka

• Null Commit and Batch Consume Support - Added support for null commits and batch consume operations in Kafka adapters.
  • Implemented batch consume capability for processing multiple messages in a single operation
  • Added null commit support for manual offset management scenarios
  • Comprehensive BDD test coverage for the new functionality

Full Changelog: 4.8.1...4.9.0

4.8.1

Changed

Helpers - Utils

• Prometheus Utilities Refactor - Replaced standalone Prometheus helper functions with a PrometheusUtils class to centralize process lifecycle and server bootstrap operations.
  • Updated Prometheus server management call sites in AppUtils and BDD step implementations
  • Preserved existing behavior while improving maintainability and encapsulation

Adapters - ScyllaDB

• CQL Identifier Validation - Tightened identifier sanitization in the ScyllaDB adapter to improve validation of dynamically built CQL statements.

Tests

Tests - Containers

• Test Container Setup Updates - Refined test container fixtures for Elasticsearch and MinIO to align startup configuration with current dependency expectations.

Dependencies

Dependencies - Runtime and Tooling

• Dependency Refresh - Updated core and transitive dependencies in pyproject.toml and uv.lock.
  • Upgraded boto3 and related AWS packages to 1.43.4
  • Upgraded cryptography to 48.0.0

Chore

Configs - Test Environment

• Elasticsearch Test Image - Updated test environment defaults to Elasticsearch 9.4.0 for container-based integration tests.

4.8.0

Added

Helpers - Tracing

• async_capture_transaction Decorator — New async-only transaction tracing decorator that enforces coroutine functions at decoration time, providing early failure detection for misuse.

  • Validates that decorated function is a coroutine using inspect.iscoroutinefunction
  • Raises TypeError immediately at import time if a sync function is passed
  • Mirrors the synchronous capture_transaction API with name and op parameters

• async_capture_span Decorator — New async-only span tracing decorator for capturing child operations within async transactions.

  • Enforces coroutine functions at decoration time
  • Works with both Sentry and Elastic APM backends
  • Provides detailed performance insights for async operations

• TracingUtils.outcome_for_exception Method — Added static method to determine the appropriate APM outcome string for exceptions.

  • Returns OUTCOME.SUCCESS for BaseError exceptions with HTTP status below 500 (client errors)
  • Returns OUTCOME.FAILURE for 5xx errors or unexpected exceptions
  • Enables accurate transaction outcome reporting in error handling paths

Configs - Sentry

• SentryConfig.ENVIRONMENT Field — Added optional ENVIRONMENT field (str | None, default None) to explicitly set the Sentry environment name.

Changed

Configs - Base Config

• Conditional Environment Assignment — Updated BaseConfig._post_init to only set ELASTIC_APM.ENVIRONMENT and SENTRY.ENVIRONMENT when they are None, preserving explicitly configured values.

Helpers - Tracing Utils

• Initialization Tracking — Added _sentry_initialized and _elastic_apm_initialized class variables to prevent duplicate initialization attempts.
• Lazy Initialization Enhancement — init_tracing_if_needed now checks initialization state before attempting to initialise each backend.

Helpers - gRPC Interceptors

• Async gRPC Client Trace Interceptor — Changed from elasticapm.capture_span to elasticapm.async_capture_span for proper async span handling.
• gRPC Server Trace Interceptor — Refactored to use elasticapm.set_transaction_outcome with OUTCOME constants instead of deprecated transaction.set_success() / transaction.set_failure() methods.
• Async Servicer Context Wrapper — Added _AsyncServicerContextWrapper class to handle async gRPC server context, ensuring abort() is properly awaited in async servicer methods.

Helpers - App Utils

• Interceptor Ordering Fix — Fixed AppUtils.create_async_grpc_app to add customized interceptors before creating the gRPC server, ensuring interceptors are properly registered.

Tests

Tests - Tracing

• Async Decorator Tests — Added comprehensive BDD test scenarios for async_capture_transaction and async_capture_span decorators to verify proper transaction and span capture for async functions.

Full Changelog: 4.7.1...4.8.0

4.7.1

Added

Helpers - Tracing

• TracingUtils Class - Introduced a new TracingUtils utility class in archipy/helpers/utils/tracing_utils.py to centralise all tracing initialisation and gRPC metadata helpers.
  • is_tracing_enabled(config) — checks whether any tracing backend (Sentry, Elastic APM, or OpenTelemetry) is active
  • init_tracing_if_needed(config) — lazily initialises the appropriate tracing backend once per process
  • grpc_status_indicates_success(status_code) — maps gRPC status codes to a boolean success/failure outcome
  • inject_outbound_metadata(metadata, carrier) — propagates W3C trace context into outbound gRPC metadata
  • extract_inbound_trace(metadata_dict) — extracts and activates an inbound trace context from gRPC metadata

Configs - Sentry

• Extended SentryConfig - Added nine new optional fields to SentryConfig in ConfigTemplate for fine-grained Sentry SDK control.
  • SEND_DEFAULT_PII (bool, default False) — controls whether personally identifiable information (IP address, user) is sent
  • MAX_BREADCRUMBS (int, default 100) — limits the number of breadcrumbs stored per event
  • ATTACH_STACKTRACE (bool, default False) — attaches a stack trace to every captured message, not only exceptions
  • SERVER_NAME (str | None, default None) — overrides the hostname reported to Sentry
  • IN_APP_INCLUDE (list[str]) — module path prefixes that Sentry marks as in-app in stack traces
  • IN_APP_EXCLUDE (list[str]) — module path prefixes excluded from in-app marking
  • PROFILES_SAMPLE_RATE (float, default 0.0) — continuous profiling sample rate between 0.0 and 1.0
  • IGNORE_ERRORS (list[str]) — fully qualified or short exception type names that Sentry should silence
  • SHUTDOWN_TIMEOUT (int, default 2) — seconds the SDK waits to flush pending events on process exit
  • DEFAULT_INTEGRATIONS (bool, default True) — toggles Sentry's automatic default integrations

Changed

Helpers - Tracing

• gRPC Client Interceptor Refactor - Rewrote archipy/helpers/interceptors/grpc/trace/client_interceptor.py to delegate tracing setup and metadata injection to TracingUtils, removing ~200 lines of inline logic.
• gRPC Server Interceptor Refactor - Rewrote archipy/helpers/interceptors/grpc/trace/server_interceptor.py to use TracingUtils.extract_inbound_trace and TracingUtils.grpc_status_indicates_success for consistent span outcome reporting.
• Tracing Decorator Refactor - Updated archipy/helpers/decorators/tracing.py to call TracingUtils.init_tracing_if_needed instead of duplicating Sentry and Elastic APM bootstrap logic inline.

Helpers - App Utils

• Sentry Initialisation Delegated - AppUtils.init_sentry is now a no-op placeholder; Sentry initialisation is performed exclusively via TracingUtils inside create_fastapi_app, preventing double-initialisation.
• Elastic APM Client Reuse - AppUtils.init_elastic_apm now calls elasticapm.get_client() first and only creates a new client when none exists, avoiding duplicate APM client instances.

Environment

• .env.example Extended - Documented the ten new SENTRY_* environment variables introduced by the expanded SentryConfig.

Tests

Tests - Error Handling

• Consolidated Error Handling Feature - Merged four separate BDD feature files (custom_errors.feature, error_utils.feature, fastapi_error_handling.feature, grpc_error_handling.feature) into a single error_handling.feature for easier maintenance and execution.
  • Removed features/custom_errors.feature, features/error_utils.feature, features/fastapi_error_handling.feature, and features/grpc_error_handling.feature
  • Removed matching step modules steps/custom_errors_steps.py, steps/error_utils_steps.py, steps/fastapi_error_handling_steps.py, and steps/grpc_error_handling_steps.py
  • Created unified features/error_handling.feature with all 238 scenario lines
  • Created unified features/steps/error_handling_steps.py consolidating all step definitions
• Tagged Scenarios - Added descriptive tags to error handling scenarios for selective test execution.

Chore

• Elasticsearch Test Image - Updated the Elasticsearch container image version in .env.test to align with CI test dependencies.

Full Changelog: 4.7.0...4.7.1

4.7.0

Added

Adapters - MinIO

• MinIO Copy Object - Implemented copy_object method in MinioAdapter.
  • Supports copying objects within and between buckets
  • Added comprehensive BDD tests

Configuration

• Advanced CORS Configuration - Added advanced CORS configuration options.
  • Extended ConfigTemplate with CORS-related settings
  • Added comprehensive BDD tests for CORS functionality

Changed

Environment

• Example Environment - Updated .env.example with new CORS configuration variables.
  • Added CORS-related environment variable documentation

Tests - App Utils

• Enhanced App Utils Tests - Added extensive BDD tests for advanced CORS configuration.
  • 89 new scenario steps added

Full Changelog: 4.6.0...4.7.0

4.6.0

Added

Adapters - Payment Gateways

• Parsian IPG Async Adapter - Added new async payment gateway adapter for Parsian integration.

  • New parsian-ipg-async optional extra
  • SOCKS5 proxy support

• Saman IPG Async Adapter - Refactored Saman IPG adapter to use async httpx.

  • Switched from synchronous requests to async httpx

Adapters - Ports

• Port Interface Extraction - Extracted payment gateway port interfaces and moved DTOs to ports.
  • Moved DTOs to ports.py for cleaner abstraction

Documentation - Payment Gateways

• IPG Adapters Documentation - Added async documentation for Saman and Parsian adapters.

Changed

Dependencies - Project

• Saman IPG Extra - Switched Saman IPG extra from requests to httpx.

  • saman-ipg = ["httpx[socks]>=0.28.1"]

• Parsian IPG Extra - Added new async extra for Parsian IPG.

  • parsian-ipg-async = ["zeep[async]>=4.3.2", "httpx[socks]>=0.28.1"]

Tests - Containers

• Dynamic Kafka Test Container - Upgraded Kafka test container with dynamic port allocation.
  • Upgraded to apache/kafka:4.2.0

Fixed

Tests - Datetime Utils

• Datetime Utils Test Alignment - Fixed tests to match rolled-back implementation.

Full Changelog: 4.5.0...4.6.0

4.5.0

Added

Adapters - Payment Gateways

• Saman Shaparak Adapter - Added new payment gateway adapter for Saman integration.
  • New saman-ipg optional extra
  • Added SAMAN_SHAPARAK__* environment variables

Helpers - Utils

• DatetimeUtils Caching Refactor - Refactored Iran holiday caching to use ClassVar.
  • Removed @ttl_cache_decorator dependency for holiday lookups
  • Added class-level cache with manual TTL handling

Changed

Adapters - Kafka

• Async Method Cleanup - Removed noqa comments from async Kafka adapter methods.
  • Removed ASYNC109 noqa from flush(), list_topics(), batch_consume(), poll()

Documentation - Payment Gateways

• Tutorial Unification - Unified payment gateway tutorials across all adapters.

Chore

Dependencies - Project

• Dependency Updates - Updated multiple package constraints.
  • cache: cachetools>=7.0.5 → >=7.0.6
  • fastapi: >=0.135.3 → >=0.136.1
  • minio: boto3>=1.42.89 → >=1.42.96
  • ty: >=0.0.30 → >=0.0.32
  • pre-commit: >=4.5.1 → >=4.6.0
  • ruff: >=0.15.10 → >=0.15.12

Tests - Containers

• Container Update - Bumped test container version.

Full Changelog: 4.4.2...4.5.0

4.4.2

Changed

Dependencies - Project

• asyncmy to asyncmy2 Migration - Replaced the asyncmy package with the maintained asyncmy2 fork in the
  starrocks-async optional extra.
  • Updated starrocks-async dependency from asyncmy>=0.2.11 to asyncmy2>=0.2.20
• Dev Dependency Refresh - Bumped multiple dev and type-stub packages and regenerated uv.lock.
  • ruff upgraded to >=0.15.10
  • types-cachetools, types-grpcio, types-protobuf, types-pymysql, types-regex, types-requests all updated
    to 20260408 stub releases

Chore

Tests - Containers

• Test Container Images - Updated test container image versions in .env.test.
  • Keycloak: keycloak/keycloak:26.5.7 → keycloak/keycloak:26.6.0
  • ScyllaDB: scylladb/scylla:2025.4.3 → scylladb/scylla:2026.1.1

4.4.1

Changed

Adapters - Keycloak

• Userinfo Cache Typing - Tightened typing for Keycloak userinfo caching by replacing type: ignore return
  annotations with explicit cast() to KeycloakUserType.

Helpers - Decorators

• Atomic Decorator Overloads - Refined sqlalchemy_atomic_decorator overloads to better distinguish sync vs async
  call sites.
  • Uses Literal[True] / Literal[False] overloads for is_async
  • Adds explicit cast() when selecting the async/sync decorator branch

Dependencies

Dependencies - Project

• Dependency Refresh - Updated runtime and dev dependencies and regenerated uv.lock.

Chore

Tests - Containers

• Test Container Images - Refreshed container image settings used by .env.test.

Full Changelog: 4.4.0...4.4.1

4.4.0

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.

Full Changelog: 4.3.6...4.4.0