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

4.3.6

Added

Helpers - Chore

• Documentation Cursor Rule - Added a dedicated Cursor rule for documentation standards under docs/**/*.md.
  • Enforces Google-style docstrings, snake_case filenames, required page structure, and code example conventions
    across all documentation files

Fixed

Chore - CI

• Docs Deploy Trigger on Source Changes - Extended the deploy-docs.yml workflow to also trigger on changes to
  archipy/** source files, not only docs/**.
  • Ensures the published documentation is rebuilt whenever adapter or helper code changes
• ReadTheDocs Build Configuration - Repaired the .readthedocs.yaml configuration to restore a functional
  ReadTheDocs build.
  • Simplified configuration to match current ReadTheDocs requirements and removed stale options

Changed

Adapters - SQLAlchemy

• Filter Value Type Union Expansion - Broadened the value parameter type union in
  SQLAlchemyFilterMixin._apply_filter and _validate_list_operation.
  • Added int, Decimal, datetime, date, and Enum to the accepted type union alongside the existing
    str | float | bool | list | UUID | None
  • Allows filtering on numeric, temporal, and enum-typed columns without requiring a cast at the call site

Chore

Docs - Documentation Overhaul

• API Reference Restructure - Split the monolithic api_reference.md into per-module subdirectories (adapters/,
  helpers/) with individual pages for each adapter and helper module.
• Adapter Example Pages - Revamped all adapter example pages with complete runnable snippets and standardised
  sections (Installation, Configuration, Basic Usage, See Also).
  • Added Elasticsearch example guide and expanded PostgreSQL and configs examples
  • Consolidated payment gateway documentation into a single page
• New Example Pages - Added dependency_injection.md and error_handling.md example guides.
• Getting Started - Overhauled the quickstart guide and complete user example to reflect manage.py integration;
  updated project structure documentation with enhanced run command options.
• Navigation - Restructured and expanded mkdocs.yml navigation; added 404.md and CODE_OF_CONDUCT.md pages.
• Architecture & Concepts - Updated architecture and concepts documentation; split the large concepts.md into
  focused topic pages.
• Installation Guide - Created a dedicated installation guide and streamlined the prerequisites section.
• Changelog - Added Cursor rules for changelog standards and restructured changelog organisation and navigation.

Full Changelog: 4.3.5...4.3.6

4.3.5

Fixed

Adapters - Kafka

• SSL Config Typing - Improved type safety and optional-field handling for SSL configuration in all three Kafka
  adapters (KafkaAdminAdapter, KafkaConsumerAdapter, KafkaProducerAdapter)
  • Replaced dict merge (|=) with explicit per-key assignment to satisfy the dict[str, str | int | float] type
    annotation
  • Optional SSL fields (SASL_MECHANISM, SSL_CERT_FILE, SSL_KEY_FILE) now fall back to "" when None,
    preventing type errors
  • Config dicts are now explicitly typed as dict[str, str | int | float] across all three adapters

Helpers - Utils

• gRPC Interceptors Type Annotation - Added explicit list[grpc.ServerInterceptor] type annotation to the
  interceptors list in AppUtils.create_async_grpc_app

Changed

Adapters - Testing

• ScyllaDB Test Container - Lowered minimum aio-max-nr requirement from 131072 to 65536
  • Reduces the kernel parameter requirement for running ScyllaDB in CI and local environments
  • Reflects the actual minimum needed by the Seastar framework in containerised setups

Tests - Redis

• Unified Redis BDD Tests - Consolidated Redis mock and container tests into a single feature file
  • Renamed redis_mock.feature → redis_adapter.feature and redis_mock_steps.py → redis_adapter_steps.py
  • Single feature now covers both mock (fakeredis) and real container scenarios

Dependencies

• cachetools bumped from >=7.0.1 to >=7.0.5 (affects cache, keycloak, minio, scylladb extras)
• fakeredis bumped from >=2.34.0 to >=2.34.1
• fastapi bumped from >=0.133.0 to >=0.135.1
• grpcio / grpcio-health-checking floor lowered from >=1.78.1 to >=1.78.0
• confluent-kafka bumped from >=2.13.0 to >=2.13.2
• boto3 (minio extra) bumped from >=1.42.55 to >=1.42.64
• sqlalchemy / sqlalchemy[asyncio] bumped from >=2.0.46 to >=2.0.47
• bandit (dev) bumped from >=1.9.3 to >=1.9.4

Full Changelog: 4.3.4...4.3.5

4.3.4

Fixed

Models - Errors

• BaseError __str__ Enhancement - Improved string representation to expose full error context
  • __str__ now returns a structured, human-readable string including class name, code, message, http_status, grpc_status, and additional_data
  • Previous output was a minimal [code] message format, making debugging difficult
  • New format: ClassName(code='...', message='...', http_status=..., grpc_status=..., additional_data=...)
  • Consistent with __repr__ behaviour — no information is hidden in logs or tracebacks

Changed

Dependencies

• FastAPI bumped from >=0.131.0 to >=0.133.0
• boto3 (minio extra) bumped from >=1.42.54 to >=1.42.55
• mkdocs-material (docs group) bumped from >=9.7.2 to >=9.7.3

Internal

Developer Tooling

• Cursor Rules Restructured - Replaced monolithic checks.mdc and CLAUDE.md with focused, single-responsibility rule files
  • Added python-code-style.mdc — string quoting, docstrings, line length, type hints, imports, error handling, complexity
  • Added architecture-patterns.mdc — Clean Architecture layer map, import direction, lazy import policy
  • Added typing-strict.mdc — strict type annotation conventions
  • Added testing-bdd.mdc — BDD/Behave test conventions
  • Added tooling-workflow.mdc — uv, Make targets, pre-commit hooks, docs, version bumping
  • Added adapter-conventions.mdc — ports & adapters pattern, mock requirements, naming rules

Full Changelog: 4.3.3...4.3.4

4.3.1

Changed

Adapters - MinIO

• Boto3 Migration - Migrated MinIO adapter from minio library to boto3
  • Replaced minio library with boto3 for S3-compatible object storage operations
  • Added new configuration fields to MinioConfig:
    • ADDRESSING_STYLE: S3 addressing style (auto, path, or virtual) - critical for CDN compatibility
    • SIGNATURE_VERSION: AWS signature version (default: s3v4)
    • CONNECT_TIMEOUT: Connection timeout in seconds (default: 60)
    • READ_TIMEOUT: Read timeout in seconds (default: 60)
    • MAX_POOL_CONNECTIONS: Maximum connections in the pool (default: 10)
    • RETRIES_MAX_ATTEMPTS: Maximum retry attempts for failed requests (default: 3)
    • RETRIES_MODE: Retry strategy - legacy, standard, or adaptive (default: standard)
    • USE_SSL: Explicit SSL usage control (overrides SECURE if set)
    • VERIFY_SSL: SSL certificate verification (default: true)
  • Improved presigned URL generation with better control over addressing styles
  • Enhanced exception handling using structured boto3 error codes instead of string parsing
  • All existing functionality preserved with zero breaking changes to the MinioPort interface
  • Resolves CDN and presigned URL compatibility issues
  • Custom MinIO test container implementation eliminates minio library dependency entirely

Full Changelog: 4.3.0...4.3.1

4.3.0

Added

Helpers - Utils

• Prometheus Utilities - Added shared Prometheus server management module
  • Implemented prometheus_utils module with is_prometheus_server_running() helper
  • Added start_prometheus_server_if_needed() helper for automatic Prometheus server lifecycle management
  • Prevents duplicate Prometheus server starts across FastAPI, gRPC, and Temporal adapters
  • Supports port availability checking before starting Prometheus HTTP server

Adapters - Temporal

• Prometheus Metrics Integration - Added Temporal metrics collection with Prometheus
  • Implemented TemporalRuntimeManager singleton for managing Runtime instances with telemetry
  • Integrated Runtime with PrometheusConfig into TemporalAdapter client and Worker
  • Added ENABLE_METRICS and METRICS_PORT configuration options to TemporalConfig
  • Temporal SDK metrics now exported to Prometheus when metrics are enabled
  • Metrics include workflow operations, activity executions, and task queue operations
  • Added BDD tests for Temporal metrics collection scenarios (temporal_metric_interceptor.feature)

Changed

Configs

• Prometheus Configuration - Enhanced BaseConfig with Prometheus support
  • Added PROMETHEUS.IS_ENABLED flag for enabling/disabling Prometheus metrics globally
  • Added PROMETHEUS.SERVER_PORT configuration for Prometheus HTTP server port
  • Updated .env.test with Prometheus configuration for testing
  • Added Temporal metrics configuration (TEMPORAL.ENABLE_METRICS, TEMPORAL.METRICS_PORT)

Fixed

Adapters - Redis

• Type Safety - Fixed Redis adapter type handling
  • Added type check for unexpected awaitable results from sync Redis client in spop() method
  • Prevents async/sync mismatch errors in Redis operations

Full Changelog: 4.2.0...4.3.0

4.1.0

Added

Adapters - Keycloak

• Organization Management - Implemented comprehensive organization management functionality

  • Added create_organization() method for creating new organizations
  • Added update_organization() method for updating existing organizations
  • Added delete_organization() method for removing organizations
  • Added add_organization_member() method for adding members to organizations
  • Added remove_organization_member() method for removing members from organizations
  • Added get_organization_members() method for retrieving organization member lists
  • Implemented both sync (KeycloakAdapter) and async (AsyncKeycloakAdapter) versions
  • Enhanced feature tests to cover all organization operations

• Realm Configuration - Added realm update functionality

  • Implemented update_realm() method to enable organization support
  • Added configuration options for organization features in realms
  • Updated test containers to support organization feature in Keycloak

Tests

• StarRocks TestContainer - Added TestContainer support for StarRocks database

  • Integrated StarRocks container for integration testing
  • Enhanced test coverage for StarRocks adapter functionality

• Atomic Transaction Tests - Expanded test coverage for atomic decorators

  • Added PostgreSQL support for atomic transaction tests
  • Added SQLite support for atomic transaction tests
  • Improved test reliability across different database backends

Changed

Development Tools

• Formatter Migration - Replaced Black with Ruff formatter
  • Migrated from Black to Ruff formatter for code formatting
  • Applied Ruff formatting fixes across entire codebase
  • Updated CI/CD workflows to use Ruff formatter
  • Maintained 120 character line length standard

CI/CD

• Workflow Improvements - Enhanced GitHub Actions workflows
  • Separated Ruff and Ty linting into dedicated workflows
  • Refactored Ty workflow for better performance
  • Bumped actions/cache from version 4 to 5
  • Improved workflow reliability and execution speed

Fixed

Configuration

• Type Safety - Resolved type checker errors
  • Fixed type errors in base_config.py
  • Fixed type errors in keycloak_utils.py
  • Improved type hint accuracy across configuration modules

Documentation

• Module References - Fixed documentation issues
  • Removed reference to non-existent error_message_types module
  • Updated documentation to reflect current module structure

Chore

Dependencies

• Python Version - Updated to Python 3.14

  • Added .python-version file with Python 3.14
  • Updated all Python version references to 3.14
  • Ensured compatibility with Python 3.14 features

• Core Dependencies - Updated multiple dependencies to latest versions

  • Updated cachetools from >=6.2.6 to >=7.0.0 (cache, keycloak, minio, scylladb extras)
  • Updated elasticsearch from >=9.2.1 to >=9.3.0 (elasticsearch and elasticsearch-async extras)
  • Updated fastapi from >=0.128.0 to >=0.128.5 (fastapi extra)
  • Updated grpcio from >=1.76.0 to >=1.78.0 (grpc extra)
  • Updated grpcio-health-checking from >=1.76.0 to >=1.78.0 (grpc extra)
  • Updated sentry-sdk from >=2.51.0 to >=2.52.0 (sentry extra)
  • Updated temporalio from >=1.21.1 to >=1.22.0 (temporalio extra)
  • Updated testcontainers from >=4.14.0 to >=4.14.1 (testcontainers extra)

• Development Dependencies - Updated development tools

  • Updated ty from >=0.0.14 to >=0.0.15 (type checker)
  • Updated ruff from >=0.14.14 to >=0.15.0 (linter and formatter)
  • Updated validate-pyproject from >=0.24.1 to >=0.25

• Documentation Dependencies - Updated documentation tools

  • Updated mkdocstrings from >=1.0.2 to >=1.0.3

• Test Environment - Updated test configuration

  • Updated Elasticsearch test image from 9.2.1 to 9.3.0 in .env.test

New Contributors

• @alip990 made their first contribution in #106

Full Changelog: 4.0.4...4.1.0

4.0.4

Changed

Helpers - Decorators

• Enhanced Exception Handling - Improved exception handling in SQLAlchemy atomic decorators
  • Changed exception handling from Exception to BaseException for comprehensive error catching
  • Updated _handle_db_exception() function signature to accept BaseException instead of Exception
  • Enhanced error handling in both sync and async atomic decorator implementations
  • Ensures all exceptions (including system exceptions) are properly caught and handled

Models - Types

• Enum Value Standardization - Standardized all enum values to uppercase format for consistency
  • SortOrderType: Changed ASCENDING and DESCENDING from lowercase to uppercase
  • FilterOperationType: Changed all 15 operation types to uppercase (EQUAL, NOT_EQUAL, LESS_THAN, LESS_THAN_OR_EQUAL, GREATER_THAN, GREATER_THAN_OR_EQUAL, IN_LIST, NOT_IN_LIST, LIKE, ILIKE, STARTS_WITH, ENDS_WITH, CONTAINS, IS_NULL, IS_NOT_NULL)
  • EmailAttachmentDispositionType: Changed ATTACHMENT and INLINE from lowercase to uppercase
  • TimeIntervalUnitType: Changed all 7 unit types to uppercase (SECONDS, MINUTES, HOURS, DAYS, WEEKS, MONTHS, YEAR)
  • Improved consistency with other enum patterns in the codebase
  • Enhanced code readability and standardization across all type definitions

Fixed

Adapters - StarRocks

• Docstring Formatting - Fixed docstring formatting in StarRocks session manager
  • Corrected docstring formatting in get_connection_args() method
  • Improved code documentation consistency

Chore

Dependencies

• Comprehensive Dependency Updates - Updated multiple dependencies to latest versions
  • Updated cachetools from >=6.2.4 to >=6.2.6 (cache, keycloak, minio, scylladb extras)
  • Updated cryptography from 46.0.3 to 46.0.4 for enhanced security
  • Updated protobuf from >=6.33.4 to >=6.33.5 (grpc extra)
  • Updated pyjwt from >=2.10.1 to >=2.11.0 (jwt extra)
  • Updated python-keycloak from >=7.0.2 to >=7.0.3 (keycloak extra)
  • Updated python-multipart from 0.0.21 to 0.0.22
  • Updated rich from 14.3.0 to 14.3.1
  • Updated rich-toolkit from 0.17.1 to 0.17.2
  • Updated sentry-sdk from >=2.50.0 to >=2.51.0 (sentry extra)
  • Updated ty from >=0.0.13 to >=0.0.14 (dev dependency)
  • Updated mkdocstrings from >=1.0.1 to >=1.0.2 (docs dependency)
  • Updated pathspec from 1.0.3 to 1.0.4
  • Updated orjson from 3.11.5 to 3.11.6

Full Changelog: 4.0.3...4.0.4

4.0.3

Added

Tests

• Add PostgreSQL and SQLite support for atomic transaction tests
• Add Starrocks TestContainer support

Changed

• Replace Black with Ruff formatter

Fixed

Configs

• Resolve type errors in base_config and keycloak_utils

• Remove reference to non-existent error_message_types module

Chore

Configs

• Configure Ruff to respect pyproject.toml in CI lint workflow

• Apply Ruff formatting fixes

• Merge branch 'master' of github.com:SyntaxArc/ArchiPy

• Merge pull request #102 from SyntaxArc/dependabot/github_actions/actions/cache-5

• Update dependencies

CI

• Bump actions/cache from 4 to 5
• Refactor ty workflow
• Separate ruff and ty linting into dedicated workflows

Full Changelog: 4.0.2...4.0.3

testing async capture span

What's Changed

• [fix] BaseProtobufDTO error message by @rabbitix in #100

Full Changelog: 3.15.3...3.16.0-beta