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

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.3

Reverted

Models - DTOs

• Type-Safe Field References - Reverted the experimental type-safe field references feature
  • Removed FieldStr utility class that was introduced for field name representation
  • Removed BaseMeta metaclass from BaseDTO
  • Reverted changes to range_dtos.py model validators
  • Removed associated BDD tests (base_dtos.feature and test steps)
  • This feature is being reconsidered for a future implementation with better design

Changed

Release Management

• Version Management - Reverted v4.3.2 release preparation
  • Reset version numbers back to v4.3.1 state
  • This version (v4.3.3) supersedes the cancelled v4.3.2 release

Full Changelog: 4.3.1...4.3.3