Skip to content

5.16.0 — 2026-10-18

← 5.16.1 | 5.15.0 → | ↑ 5.x series

Added

Adapters - SQLAlchemy

  • Several databases of the same type - Session managers are keyed by configuration, so two adapters built with different configs no longer share the first one's engine.
    • The same config still returns the same manager.
    • sqlalchemy_atomic and the *_sqlalchemy_atomic shortcuts take an optional registry.
    • Every registry subclass has its own manager slots, so a subclass of a concrete registry can hold another database of the same type.

Adapters - Keycloak

  • archipy.adapters.keycloak.auth - fastapi_auth and grpc_auth are plain functions with __all__.
    • fastapi_auth returns an always-async dependency that works for def and async def endpoints; grpc_auth detects async def servicer methods.
    • fastapi_auth also sets AuthContextManager for the request and clears it when the request ends. set_auth_context returns a token and clear_auth_context accepts it, so a nested guard restores the outer caller.
    • AuthenticatedUserDTO gains token_info.

Helpers - gRPC

  • Rate-limit counter store - RateLimitStore and AsyncRateLimitStore protocols and a store argument on the rate-limit interceptors, plus store_errors for failures of a caller's backend. Without them the Redis default is built lazily as before.

Helpers - OpenTelemetry

  • Configurable SDK - OpentelemetryConfig gains TRACES_SAMPLER, PROPAGATORS (including b3 and b3multi), OTLP_COMPRESSION, SPAN_BATCH_*, LOG_BATCH_*, SERVICE_VERSION, SERVICE_INSTANCE_ID, RESOURCE_DETECTORS and METRICS_DURATION_BUCKETS_S.
    • Service instance id, host and os are detected by default; process is opt-in because it records the command line. Explicit resource settings override detected attributes.
    • With USE_STANDARD_ENV, the standard OTEL_* variables fill in the settings the config leaves unset; an explicitly set field wins, and invalid values are logged and ignored. OTEL_SDK_DISABLED=true keeps the SDK off.
    • Defaults are queue 4096, batch 512 and compression none. A batch size left unset follows a lowered queue.
  • B3 propagation - opentelemetry-propagator-b3 ships in archipy[otel].
  • OtelRuntime - The provider state lives on runtime instances; OtelUtils is a typed facade over a default one, with runtime() and set_runtime().
  • Decorator attributes - Spans record code.function.name and, for a failed call, error.type; the measure_duration and count_calls instruments add error.type to a call that ends in error or cancelled.

Models - DTOs

  • RpcInstrumentsDTO - Frozen DTO for the gRPC metric instruments.

Changed

Behavior

  • gRPC server metrics (breaking) - The histogram is now rpc.server.call.duration (was rpc.server.request.duration) with rpc.system.name, the fully qualified rpc.method, rpc.response.status_code and error.type for server-failure codes. A handler that raises without a status is recorded as UNKNOWN. rpc.server.active_requests stays on the same attributes. Update dashboards and alerts.
  • fastapi_auth is always async - It works for both endpoint kinds, so async_fastapi_auth and async_grpc_auth are deprecated aliases.
  • Type strictness - JWTUtils raises InvalidTokenError for a non-string sub or an invalid exp claim. Helpers, interceptors, errors and decorators replace Any with precise types, ParamSpec and Protocols.

Layout

  • Enforced layer order - models ← configs ← helpers ← adapters is checked by an import-linter contract in make lint and pre-commit. Models read settings through archipy.models.runtime_settings, and the Persian digit table is archipy.models.types.PersianDigitType.
  • Atomic decorators moved - They live in archipy.adapters.base.sqlalchemy.atomic.
  • OTel internals split - OtelUtils internals moved into the private archipy.helpers.utils._otel package.

Deprecated

All removed in 6.0.0; each warning names the replacement.

  • archipy.helpers.decorators atomic names (sqlalchemy_atomic and the *_sqlalchemy_atomic shortcuts) - use archipy.adapters.base.sqlalchemy.atomic.
  • archipy.helpers.utils.keycloak_utils and KeycloakUtils - use archipy.adapters.keycloak.auth.
  • KeycloakUtils.async_fastapi_auth and async_grpc_auth - use fastapi_auth and grpc_auth.
  • Reading request.state.user_info, token_info, actor_chain and user_roles - read them from AuthContextManager.

Removed

  • otel-fastapi extra (breaking) - Install archipy[otel,fastapi].

Tests

  • New otel_configuration.feature, trace propagation through FastAPI, gRPC (sync and aio) and httpx in B3 and W3C formats, gRPC compression measured on the wire, SQLite multi-database scenarios, FastAPI auth context scenarios against a real ASGI app, and rate-limit scenarios with caller stores.

Chore

  • Docs - Layer order, observability, decorators, utils and FAQ pages updated, including the 6.0.0 removal notes.

Dependencies

  • Lower bounds of every requirement raised to the locked versions.