idempotency-kit 0.1.0__tar.gz → 0.2.0__tar.gz

{idempotency_kit-0.1.0 → idempotency_kit-0.2.0}/.gitignore

@@ -125,3 +125,6 @@ dmypy.json
 
 # ruff
 .ruff_cache/
+
+# Claude Code worktrees
+.claude/worktrees/

idempotency_kit-0.2.0/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+## [0.2.0](https://github.com/bedrock-python/idempotency-kit/compare/idempotency-kit-v0.1.1...idempotency-kit-v0.2.0) (2026-09-06)
+
+
+### ⚠ BREAKING CHANGES
+
+* DEFAULT_TTL_MINUTES is 60 (was 30) and MAX_TTL_SECONDS is 2592000 (was 86400), so IdempotencyDomainService() built without arguments now keeps records for an hour and accepts a TTL of up to 30 days. Pass default_ttl_minutes=30 and max_ttl_seconds=86400 to keep the old values.
+
+### Bug Fixes
+
+* the defects the agents page turned up ([#22](https://github.com/bedrock-python/idempotency-kit/issues/22)) ([1573db4](https://github.com/bedrock-python/idempotency-kit/commit/1573db4774191598cad38b02e653b2656d3bb763))
+
+
+### Documentation
+
+* an upgrade note for the unified TTL defaults ([#25](https://github.com/bedrock-python/idempotency-kit/issues/25)) ([bb90e84](https://github.com/bedrock-python/idempotency-kit/commit/bb90e8453e0ac74856b354b34f01dfe495e9393c))
+
+## [0.1.1](https://github.com/bedrock-python/idempotency-kit/compare/idempotency-kit-v0.1.0...idempotency-kit-v0.1.1) (2026-08-28)
+
+
+### Bug Fixes
+
+* **core:** store any JSON result and decide hit/miss on the record, not on None ([#8](https://github.com/bedrock-python/idempotency-kit/issues/8)) ([ddb537e](https://github.com/bedrock-python/idempotency-kit/commit/ddb537e8c39e5becb1a9b1ff7549bc11f40735d7)), closes [#6](https://github.com/bedrock-python/idempotency-kit/issues/6)
+* **dishka:** provide the metrics collector from settings so the shipped providers build a container ([#9](https://github.com/bedrock-python/idempotency-kit/issues/9)) ([2a06416](https://github.com/bedrock-python/idempotency-kit/commit/2a064169a16332762d3ab62926c03d2f203482bd)), closes [#7](https://github.com/bedrock-python/idempotency-kit/issues/7)
+* **release:** update version to 0.1.0 and fix release-please config ([016c6c4](https://github.com/bedrock-python/idempotency-kit/commit/016c6c42ba189291be56250192f9e6db7020f853))
+* update publish workflow, release-please version search, gitignore ([#3](https://github.com/bedrock-python/idempotency-kit/issues/3)) ([9915f0e](https://github.com/bedrock-python/idempotency-kit/commit/9915f0e6e784b6d59375541e6244efaca694a0bb))
+
+## 0.1.0 (2026-05-13)
+
+
+### Bug Fixes
+
+* **ci:** remove coverage threshold from integration tests ([b00f037](https://github.com/bedrock-python/idempotency-kit/commit/b00f03742925922e261790b0ee649055c31fdaae))
+* **ci:** set integration test coverage threshold to 50% ([ed4e790](https://github.com/bedrock-python/idempotency-kit/commit/ed4e7907ff977916b0be11a6597a090b9ae11cab))
+
+
+### Documentation
+
+* rewrite README to match library style with badges ([cebded3](https://github.com/bedrock-python/idempotency-kit/commit/cebded360b4c0c37d7604efd230574b4464f47c8))
+
+## Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

{idempotency_kit-0.1.0 → idempotency_kit-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: idempotency-kit
-Version: 0.1.0
+Version: 0.2.0
 Summary: Production-ready idempotency library for async Python applications
 Project-URL: Repository, https://github.com/bedrock-python/idempotency-kit
 Project-URL: Documentation, https://bedrock-python.github.io/idempotency-kit/
@@ -244,6 +244,15 @@ Production-ready idempotency library for async Python applications.
 
 Ensure operations execute exactly once, even when called multiple times with the same idempotency key. Built for production microservices with graceful degradation, collision handling, and observability.
 
+> [!TIP]
+> **Building this with an AI assistant?** Hand it
+> **[one page](https://bedrock-python.github.io/idempotency-kit/agents/)** instead of the
+> whole site: the complete API surface, the rules that break code when they are broken —
+> what the key actually identifies, what two concurrent callers really do, how a TTL in
+> seconds is rounded — the mistakes models make with this API, and a map of which page to
+> fetch for the rest. Every docs page is also served as raw Markdown at its own URL, and a
+> **Copy page** button at the top of each one hands it straight to a chat window.
+
 ## Features
 
 - **Clean Architecture** — core domain separated from infrastructure
@@ -352,6 +361,7 @@ Both requests get the **same result** - idempotency guaranteed!
 
 📚 **[Full Documentation](https://bedrock-python.github.io/idempotency-kit/)**
 
+- [For AI agents](https://bedrock-python.github.io/idempotency-kit/agents/) — the whole library on one page
 - [Quick Start](https://bedrock-python.github.io/idempotency-kit/quickstart/) — get started in 5 minutes
 - [User Guide](https://bedrock-python.github.io/idempotency-kit/user_guide/) — detailed usage and patterns
 - [Architecture](https://bedrock-python.github.io/idempotency-kit/architecture/) — design principles

{idempotency_kit-0.1.0 → idempotency_kit-0.2.0}/README.md

@@ -11,6 +11,15 @@ Production-ready idempotency library for async Python applications.
 
 Ensure operations execute exactly once, even when called multiple times with the same idempotency key. Built for production microservices with graceful degradation, collision handling, and observability.
 
+> [!TIP]
+> **Building this with an AI assistant?** Hand it
+> **[one page](https://bedrock-python.github.io/idempotency-kit/agents/)** instead of the
+> whole site: the complete API surface, the rules that break code when they are broken —
+> what the key actually identifies, what two concurrent callers really do, how a TTL in
+> seconds is rounded — the mistakes models make with this API, and a map of which page to
+> fetch for the rest. Every docs page is also served as raw Markdown at its own URL, and a
+> **Copy page** button at the top of each one hands it straight to a chat window.
+
 ## Features
 
 - **Clean Architecture** — core domain separated from infrastructure
@@ -119,6 +128,7 @@ Both requests get the **same result** - idempotency guaranteed!
 
 📚 **[Full Documentation](https://bedrock-python.github.io/idempotency-kit/)**
 
+- [For AI agents](https://bedrock-python.github.io/idempotency-kit/agents/) — the whole library on one page
 - [Quick Start](https://bedrock-python.github.io/idempotency-kit/quickstart/) — get started in 5 minutes
 - [User Guide](https://bedrock-python.github.io/idempotency-kit/user_guide/) — detailed usage and patterns
 - [Architecture](https://bedrock-python.github.io/idempotency-kit/architecture/) — design principles

idempotency_kit-0.2.0/idempotency_kit/__version__.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"  # x-release-please-version

idempotency_kit-0.2.0/idempotency_kit/core/adapters/basic.py

@@ -0,0 +1,61 @@
+from typing import Any, TypeVar
+
+from pydantic import BaseModel
+
+from idempotency_kit.core.exceptions import IdempotencyValidationError
+from idempotency_kit.core.protocols.adapter import ResultAdapter
+
+T = TypeVar("T", bound=BaseModel)
+
+
+class PydanticResultAdapter(ResultAdapter[T]):
+    """Adapter for Pydantic models.
+
+    It has no representation for an absent result: an action that may return ``None``
+    wants ``VoidResultAdapter`` or ``JsonResultAdapter`` instead.
+    """
+
+    def __init__(self, model_class: type[T]) -> None:
+        self.model_class = model_class
+
+    def encode(self, value: T) -> Any:
+        # Encoding None to null would store a record this adapter can never decode again,
+        # turning every later replay into a miss. Refusing it leaves the operation
+        # uncached and says why, which the coordinator reports and swallows.
+        model: BaseModel | None = value
+        if model is None:
+            msg = (
+                f"{type(self).__name__}({self.model_class.__name__}) cannot encode None. "
+                "Use VoidResultAdapter for an action that returns None, or JsonResultAdapter "
+                "for one that may."
+            )
+            raise IdempotencyValidationError(msg)
+        return model.model_dump(mode="json")
+
+    def decode(self, data: Any) -> T:
+        # Only a null payload is undecodable: an empty mapping or list is a model that
+        # happens to dump to nothing.
+        if data is None:
+            msg = "cannot decode a null idempotency payload"
+            raise ValueError(msg)
+        return self.model_class.model_validate(data)
+
+
+class JsonResultAdapter(ResultAdapter[Any]):
+    """Adapter for results that already are JSON values (dict, list, str, number, bool or ``None``)."""
+
+    def encode(self, value: Any) -> Any:
+        return value
+
+    def decode(self, data: Any) -> Any:
+        return data
+
+
+class VoidResultAdapter(ResultAdapter[None]):
+    """Adapter for functions that return ``None``: the record stores JSON ``null`` and decodes back to ``None``."""
+
+    def encode(self, value: None) -> Any:
+        return None
+
+    def decode(self, data: Any) -> None:
+        return None

idempotency_kit-0.2.0/idempotency_kit/core/constants.py

@@ -0,0 +1,22 @@
+"""Core constants for idempotency."""
+
+# Key constraints
+# Maximum allowed length for idempotency key.
+MAX_KEY_LENGTH: int = 255
+
+# Maximum allowed length for operation name.
+MAX_OPERATION_LENGTH: int = 100
+
+# TTL defaults
+# The single source for both IdempotencyDomainService's own defaults and the field
+# defaults of BaseIdempotencySettings, so the bounds do not depend on how the service
+# was built.
+
+# Default TTL in minutes when not explicitly specified (1 hour).
+DEFAULT_TTL_MINUTES: int = 60
+
+# Minimum allowed TTL in seconds (1 minute); the coordinator floors every TTL at a minute.
+MIN_TTL_SECONDS: int = 60
+
+# Maximum allowed TTL in seconds (30 days).
+MAX_TTL_SECONDS: int = 30 * 24 * 3600

idempotency_kit-0.2.0/idempotency_kit/core/decorators/aio/idempotent.py

@@ -0,0 +1,125 @@
+import functools
+import inspect
+import logging
+from collections.abc import Awaitable, Callable
+from typing import Any, TypeVar
+
+from idempotency_kit.core.protocols.adapter import ResultAdapter
+from idempotency_kit.core.services.aio.coordinator import AsyncIdempotencyCoordinator
+
+T = TypeVar("T")
+
+logger = logging.getLogger(__name__)
+
+_POSITIONAL_KINDS = (inspect.Parameter.POSITIONAL_ONLY, inspect.Parameter.POSITIONAL_OR_KEYWORD)
+
+
+def _positional_index(func: Callable[..., Any], key_param: str) -> int | None:
+    """Index at which ``key_param`` can arrive positionally, or ``None`` if it cannot."""
+    try:
+        parameters = list(inspect.signature(func).parameters.values())
+    except (TypeError, ValueError):
+        return None
+    for index, parameter in enumerate(parameters):
+        if parameter.name == key_param and parameter.kind in _POSITIONAL_KINDS:
+            return index
+    return None
+
+
+def async_idempotent(
+    operation: str,
+    adapter: ResultAdapter[T],
+    ttl_seconds: int | None = None,
+    key_param: str = "idempotency_key",
+    infra_param: str | None = None,
+) -> Callable[[Callable[..., Awaitable[T]]], Callable[..., Awaitable[T]]]:
+    """Decorator for asynchronous idempotent operations.
+
+    Can be used on methods (finding coordinator in 'self') or standalone functions
+    (finding coordinator in arguments).
+
+    Args:
+        operation: Unique operation name.
+        adapter: Result adapter for encoding/decoding.
+        ttl_seconds: Optional TTL for idempotency record in seconds.
+            If not provided, uses value from coordinator settings or global default.
+        key_param: Name of the argument containing the idempotency key. Read from the
+            keyword arguments, or from the positional arguments when the parameter can
+            be passed positionally.
+        infra_param: Optional name of the argument or attribute containing AsyncIdempotencyCoordinator.
+            If not provided, searches for AsyncIdempotencyCoordinator by type.
+    """
+
+    def decorator(func: Callable[..., Awaitable[T]]) -> Callable[..., Awaitable[T]]:
+        key_index = _positional_index(func, key_param)
+
+        @functools.wraps(func)
+        async def wrapper(*args: Any, **kwargs: Any) -> T:
+            # 1. Resolve idempotency key
+            idempotency_key = _resolve_key(args, kwargs)
+            if not idempotency_key:
+                return await func(*args, **kwargs)
+
+            # 2. Resolve coordinator
+            coordinator = _resolve_coordinator(args, kwargs)
+
+            if coordinator is None:
+                # Proceeding without idempotency keeps the operation available, but it is
+                # never what the decorator was put there for: say so loudly enough to be
+                # caught by whoever renamed the attribute or forgot the argument.
+                logger.warning(
+                    "No idempotency coordinator found; running the operation without idempotency",
+                    extra={
+                        "operation": operation,
+                        "idempotency_key": idempotency_key,
+                        "infra_param": infra_param,
+                    },
+                )
+                return await func(*args, **kwargs)
+
+            # 3. Delegate to coordinator
+            return await coordinator.coordinate(
+                operation,
+                idempotency_key,
+                ttl_seconds,
+                adapter,
+                func,
+                *args,
+                **kwargs,
+            )
+
+        def _resolve_key(args: tuple[Any, ...], kwargs: dict[str, Any]) -> Any:
+            if key_param in kwargs:
+                return kwargs[key_param]
+            if key_index is not None and key_index < len(args):
+                return args[key_index]
+            return None
+
+        def _resolve_coordinator(args: tuple[Any, ...], kwargs: dict[str, Any]) -> AsyncIdempotencyCoordinator | None:
+            # By name, if infra_param is provided
+            if infra_param:
+                named: AsyncIdempotencyCoordinator | None = kwargs.get(infra_param)
+                if named is None and args:
+                    named = getattr(args[0], infra_param, None)
+                if named is not None:
+                    return named
+
+            # By type, in the keyword arguments
+            for val in kwargs.values():
+                if isinstance(val, AsyncIdempotencyCoordinator):
+                    return val
+
+            # By type, in the positional arguments, then in their attributes:
+            # DI often injects the coordinator into an attribute of 'self'.
+            for arg in args:
+                if isinstance(arg, AsyncIdempotencyCoordinator):
+                    return arg
+                if hasattr(arg, "__dict__"):
+                    for attr_val in vars(arg).values():
+                        if isinstance(attr_val, AsyncIdempotencyCoordinator):
+                            return attr_val
+            return None
+
+        return wrapper
+
+    return decorator

{idempotency_kit-0.1.0 → idempotency_kit-0.2.0}/idempotency_kit/core/models/entities.py

@@ -1,6 +1,5 @@
 """Idempotency record entity."""
 
-from collections.abc import Mapping
 from datetime import UTC, datetime, timedelta
 from typing import Annotated, Self
 
@@ -39,8 +38,8 @@ class IdempotencyRecord(IdempotencyIdentifiers):
 
     model_config = ConfigDict(frozen=True)
 
-    # Result
-    result: Mapping[str, JsonValue] = Field(description="Cached operation result (JSON-serializable)")
+    # Result: whatever the adapter encoded — any JSON value, ``null`` for a void result.
+    result: JsonValue = Field(description="Cached operation result (any JSON value; null for void results)")
 
     # Timing
     created_at: datetime = Field(description="When this record was created")
@@ -51,7 +50,7 @@ class IdempotencyRecord(IdempotencyIdentifiers):
         cls,
         operation: str,
         idempotency_key: str,
-        result: Mapping[str, JsonValue],
+        result: JsonValue,
         ttl_seconds: float,
     ) -> Self:
         """Create a new record with calculated expiration."""

{idempotency_kit-0.1.0 → idempotency_kit-0.2.0}/idempotency_kit/core/services/aio/coordinator.py

@@ -1,9 +1,15 @@
 import logging
 import time
 from collections.abc import Awaitable, Callable
-from typing import Any, TypeVar
-
-from idempotency_kit.core.exceptions import IdempotencyKeyCollisionError
+from dataclasses import dataclass
+from typing import Any, Generic, TypeVar
+
+from idempotency_kit.core.exceptions import (
+    IdempotencyInvalidTTLError,
+    IdempotencyKeyCollisionError,
+    IdempotencyRecordExpiredError,
+    IdempotencyValidationError,
+)
 from idempotency_kit.core.protocols.adapter import ResultAdapter
 from idempotency_kit.core.protocols.aio.repository import AsyncIdempotencyRepository
 from idempotency_kit.core.protocols.metrics import IdempotencyMetricsProtocol, NoOpIdempotencyMetrics
@@ -14,8 +20,28 @@ T = TypeVar("T")
 logger = logging.getLogger(__name__)
 
 
+@dataclass(frozen=True)
+class _Hit(Generic[T]):
+    """A decoded cached result.
+
+    Wrapping it keeps hit/miss a property of the *record*: an adapter may
+    legitimately decode to ``None`` (``VoidResultAdapter``, a stored JSON
+    ``null``), which a bare ``None`` sentinel would misread as a miss.
+    """
+
+    value: T
+
+
 class AsyncIdempotencyCoordinator:
-    """Coordinator for asynchronous idempotent operations."""
+    """Coordinator for asynchronous idempotent operations.
+
+    Args:
+        repository: Storage for idempotency records.
+        domain_service: Record factory and TTL bounds.
+        operation_ttls: Per-operation TTL overrides in seconds; wins over the decorator.
+        metrics: Metrics collector for hits, misses, collisions, errors and latency.
+        enabled: Set to False to make every call a pass-through to the action.
+    """
 
     def __init__(
         self,
@@ -23,11 +49,13 @@ class AsyncIdempotencyCoordinator:
         domain_service: IdempotencyDomainService,
         operation_ttls: dict[str, int] | None = None,
         metrics: IdempotencyMetricsProtocol | None = None,
+        enabled: bool = True,
     ) -> None:
         self._repo = repository
         self._svc = domain_service
         self._operation_ttls = operation_ttls or {}
         self._metrics = metrics or NoOpIdempotencyMetrics()
+        self._enabled = enabled
 
     async def coordinate(
         self,
@@ -40,14 +68,18 @@ class AsyncIdempotencyCoordinator:
         *args: Any,
         **kwargs: Any,
     ) -> T:
-        """Coordinate an idempotent operation."""
-        if not idempotency_key:
+        """Coordinate an idempotent operation.
+
+        With ``enabled=False`` the action is simply run: nothing is read, nothing is
+        written, and no metric is recorded.
+        """
+        if not self._enabled or not idempotency_key:
             return await action(*args, **kwargs)
 
         # 1. Try to get from storage
-        cached_result = await self._try_get_cached(operation, idempotency_key, adapter)
-        if cached_result is not None:
-            return cached_result
+        hit = await self._try_get_cached(operation, idempotency_key, adapter)
+        if hit is not None:
+            return hit.value
 
         # 2. Execute business logic
         result = await action(*args, **kwargs)
@@ -68,18 +100,18 @@ class AsyncIdempotencyCoordinator:
         operation: str,
         idempotency_key: str,
         adapter: ResultAdapter[T],
-    ) -> T | None:
+    ) -> _Hit[T] | None:
         """Try to fetch and decode result from storage. Returns None on miss or error."""
         start_time = time.perf_counter()
         try:
-            result = await self._get_and_decode(operation, idempotency_key, adapter)
-            if result is not None:
+            hit = await self._get_and_decode(operation, idempotency_key, adapter)
+            if hit is not None:
                 self._metrics.record_hit(operation)
                 logger.info(
                     "Idempotency cache hit",
                     extra={"operation": operation, "idempotency_key": idempotency_key},
                 )
-                return result
+                return hit
             self._metrics.record_miss(operation)
         except Exception:
             self._metrics.record_error(operation, "storage_get_error")
@@ -109,6 +141,22 @@ class AsyncIdempotencyCoordinator:
             )
         except IdempotencyKeyCollisionError:
             return await self._handle_collision(operation, idempotency_key, result, adapter)
+        except (IdempotencyValidationError, IdempotencyInvalidTTLError):
+            # The record itself is invalid — the adapter encoded something the
+            # storage format cannot hold, or the TTL is out of range. No retry can
+            # fix that, so it is reported as a contract violation rather than a
+            # storage blip. The result is still returned: the action has already
+            # run, and raising here would make the caller retry a completed
+            # operation — the one thing an idempotency layer must never cause.
+            self._metrics.record_error(operation, "record_validation_error")
+            logger.exception(
+                "Idempotency record rejected; this operation will not be cached",
+                extra={
+                    "operation": operation,
+                    "idempotency_key": idempotency_key,
+                    "adapter": type(adapter).__name__,
+                },
+            )
         except Exception:
             self._metrics.record_error(operation, "storage_save_error")
             logger.exception(
@@ -125,10 +173,20 @@ class AsyncIdempotencyCoordinator:
         operation: str,
         idempotency_key: str,
         adapter: ResultAdapter[T],
-    ) -> T | None:
-        """Fetch record from repository and decode it safely."""
+    ) -> _Hit[T] | None:
+        """Fetch record from repository and decode it safely; ``None`` means no usable record."""
         cached = await self._repo.get(operation, idempotency_key)
-        if not cached:
+        if cached is None:
+            return None
+        try:
+            # The protocol asks a repository not to return an expired record, but expiry is
+            # the domain's rule to enforce, and a backend without native expiry cannot.
+            self._svc.validate_record(cached)
+        except IdempotencyRecordExpiredError:
+            logger.warning(
+                "Idempotency record expired; treating it as a miss",
+                extra={"operation": operation, "idempotency_key": idempotency_key},
+            )
             return None
         return self._decode_safely(adapter, cached.result, operation, idempotency_key)
 
@@ -163,9 +221,9 @@ class AsyncIdempotencyCoordinator:
             extra={"operation": operation, "idempotency_key": idempotency_key},
         )
         try:
-            winner_result = await self._get_and_decode(operation, idempotency_key, adapter)
-            if winner_result is not None:
-                return winner_result
+            winner = await self._get_and_decode(operation, idempotency_key, adapter)
+            if winner is not None:
+                return winner.value
         except Exception:
             logger.exception(
                 "Failed to fetch concurrent result after collision",
@@ -179,10 +237,10 @@ class AsyncIdempotencyCoordinator:
         data: Any,
         operation: str,
         idempotency_key: str,
-    ) -> T | None:
+    ) -> _Hit[T] | None:
         """Try to decode data using adapter. Returns None and logs error on failure."""
         try:
-            return adapter.decode(data)
+            return _Hit(adapter.decode(data))
         except Exception:
             logger.exception(
                 "Idempotency decode error",

{idempotency_kit-0.1.0 → idempotency_kit-0.2.0}/idempotency_kit/core/services/domain.py

@@ -52,7 +52,7 @@ class IdempotencyDomainService:
         self,
         operation: str,
         idempotency_key: str,
-        result: dict[str, JsonValue],
+        result: JsonValue,
         *,
         ttl_minutes: int | None = None,
     ) -> IdempotencyRecord:

{idempotency_kit-0.1.0 → idempotency_kit-0.2.0}/idempotency_kit/dishka/aio/coordinator.py

@@ -23,7 +23,7 @@ class AsyncIdempotencyCoordinatorProvider(Provider):
         repository: AsyncIdempotencyRepository,
         domain_service: IdempotencyDomainService,
         settings: IdempotencySettingsProtocol,
-        metrics: IdempotencyMetricsProtocol | None = None,
+        metrics: IdempotencyMetricsProtocol,
     ) -> AsyncIdempotencyCoordinator:
         """Provide idempotency coordinator."""
         return AsyncIdempotencyCoordinator(
@@ -31,4 +31,7 @@ class AsyncIdempotencyCoordinatorProvider(Provider):
             domain_service=domain_service,
             operation_ttls=settings.operation_ttls,
             metrics=metrics,
+            # Read defensively: settings objects written against the protocol before
+            # ``enabled`` was part of it stay valid, and they mean enabled.
+            enabled=getattr(settings, "enabled", True),
         )

{idempotency_kit-0.1.0 → idempotency_kit-0.2.0}/idempotency_kit/dishka/aio/redis.py

@@ -19,7 +19,7 @@ class AsyncRedisIdempotencyProvider(Provider):
         self,
         redis: AsyncRedisClient,
         settings: IdempotencySettingsProtocol,
-        metrics: IdempotencyMetricsProtocol | None = None,
+        metrics: IdempotencyMetricsProtocol,
     ) -> AsyncIdempotencyRepository:
         """Provide idempotency repository."""
         return RedisAsyncIdempotencyRepository(

idempotency_kit-0.2.0/idempotency_kit/dishka/common.py

@@ -0,0 +1,35 @@
+"""Common Dishka providers for idempotency."""
+
+from dishka import Provider, Scope, provide
+
+from idempotency_kit import IdempotencyDomainService, IdempotencyMetricsProtocol, NoOpIdempotencyMetrics
+from idempotency_kit.infra.metrics.prometheus import PrometheusIdempotencyMetrics
+
+from .protocols import IdempotencySettingsProtocol
+
+
+class IdempotencyProvider(Provider):
+    """Provider for the idempotency domain service and the metrics collector (sync / framework-agnostic).
+
+    The metrics collector is a single APP-scoped instance shared by the repository and the coordinator,
+    which is also what ``PrometheusIdempotencyMetrics`` needs — it registers its collectors once per process.
+    An application with another metrics backend overrides it with ``@provide(override=True)`` in a later provider.
+    """
+
+    scope = Scope.APP
+
+    @provide
+    def get_service(self, settings: IdempotencySettingsProtocol) -> IdempotencyDomainService:
+        """Provide idempotency domain service."""
+        return IdempotencyDomainService(
+            default_ttl_minutes=settings.default_ttl_minutes,
+            min_ttl_seconds=settings.min_ttl_seconds,
+            max_ttl_seconds=settings.max_ttl_seconds,
+        )
+
+    @provide
+    def get_metrics(self, settings: IdempotencySettingsProtocol) -> IdempotencyMetricsProtocol:
+        """Provide the metrics collector: Prometheus when ``settings.metrics_enabled``, a no-op otherwise."""
+        if settings.metrics_enabled:
+            return PrometheusIdempotencyMetrics()
+        return NoOpIdempotencyMetrics()

{idempotency_kit-0.1.0 → idempotency_kit-0.2.0}/idempotency_kit/dishka/protocols.py

@@ -7,6 +7,14 @@ from typing import Protocol, runtime_checkable
 class IdempotencySettingsProtocol(Protocol):
     """Protocol for idempotency settings."""
 
+    @property
+    def enabled(self) -> bool:
+        """Whether the shipped coordinator applies idempotency at all.
+
+        A settings object without the attribute is read as enabled.
+        """
+        ...
+
     @property
     def key_prefix(self) -> str:
         """Key prefix for Redis."""
@@ -14,7 +22,9 @@ class IdempotencySettingsProtocol(Protocol):
 
     @property
     def metrics_enabled(self) -> bool:
-        """Whether idempotency metrics are enabled."""
+        """Whether the shipped providers wire ``PrometheusIdempotencyMetrics``
+        (needs the ``prometheus`` extra); a no-op collector otherwise.
+        """
         ...
 
     @property

{idempotency_kit-0.1.0 → idempotency_kit-0.2.0}/idempotency_kit/infra/storage/redis/aio/repository.py

@@ -43,6 +43,12 @@ class RedisAsyncIdempotencyRepository(AsyncIdempotencyRepository):
     """Redis implementation of idempotency repository.
 
     Stores records as JSON with automatic TTL expiration.
+
+    It records only the metrics the coordinator cannot produce for it -- errors, the bulk
+    hit and miss counts of ``get_many``, and the latency of ``delete`` and ``get_many``.
+    Hit, miss, collision and the latency of ``get`` and ``save`` belong to
+    ``AsyncIdempotencyCoordinator``, so that a collector shared by both counts each
+    operation once.
     """
 
     def __init__(
@@ -61,8 +67,8 @@ class RedisAsyncIdempotencyRepository(AsyncIdempotencyRepository):
         """
         if not _HAS_REDIS or not _HAS_ORJSON:
             raise ImportError(
-                "RedisAsyncIdempotencyRepository requires redis-client-kit and orjson. "
-                "Install them with: pip install idempotency-kit[redis-aio]"
+                "RedisAsyncIdempotencyRepository requires redis and orjson. "
+                "Install them with: pip install idempotency-kit[redis]"
             )
         self._redis = redis
         self._key_prefix = key_prefix
@@ -74,11 +80,11 @@ class RedisAsyncIdempotencyRepository(AsyncIdempotencyRepository):
 
     def _deserialize_record(
         self,
-        data: bytes,
+        data: bytes | str,
         operation: str,
         idempotency_key: str,
     ) -> IdempotencyRecord | None:
-        """Deserialize record from JSON bytes.
+        """Deserialize record from its JSON payload (bytes, or str with ``decode_responses``).
 
         Returns None if record is expired.
         Raises IdempotencyValidationError or IdempotencyError on corruption.
@@ -134,49 +140,42 @@ class RedisAsyncIdempotencyRepository(AsyncIdempotencyRepository):
             IdempotencyStorageError: If Redis operation fails
             IdempotencyError: If data is corrupted
         """
-        start = time.perf_counter()
+        self._validate_inputs(operation, idempotency_key)
+        key = self._make_key(operation, idempotency_key)
         try:
-            self._validate_inputs(operation, idempotency_key)
-            key = self._make_key(operation, idempotency_key)
-            try:
-                data = await self._redis.get(key)
-            except Exception as e:
-                self._metrics.record_error(operation, type(e).__name__)
-                logger.exception(
-                    "Redis error during get",
-                    extra={"operation": operation, "key": idempotency_key},
-                )
-                raise IdempotencyStorageError(
-                    f"Redis storage failure during get for {operation}",
-                    operation=operation,
-                    original_error=e,
-                ) from e
+            data = await self._redis.get(key)
+        except Exception as e:
+            self._metrics.record_error(operation, type(e).__name__)
+            logger.exception(
+                "Redis error during get",
+                extra={"operation": operation, "key": idempotency_key},
+            )
+            raise IdempotencyStorageError(
+                f"Redis storage failure during get for {operation}",
+                operation=operation,
+                original_error=e,
+            ) from e
 
-            if not data:
-                self._metrics.record_miss(operation)
-                return None
+        if not data:
+            return None
 
-            record = self._deserialize_record(data, operation, idempotency_key)
-            if record is None:
-                self._metrics.record_miss(operation)
+        record = self._deserialize_record(data, operation, idempotency_key)
+        if record is None:
+            logger.warning(
+                "Found expired record in Redis (TTL mismatch). Deleting it.",
+                extra={"operation": operation, "key": idempotency_key},
+            )
+            try:
+                await self._redis.delete(key)
+            except Exception:
                 logger.warning(
-                    "Found expired record in Redis (TTL mismatch). Deleting it.",
+                    "Failed to delete expired record from Redis",
                     extra={"operation": operation, "key": idempotency_key},
+                    exc_info=True,
                 )
-                try:
-                    await self._redis.delete(key)
-                except Exception:
-                    logger.warning(
-                        "Failed to delete expired record from Redis",
-                        extra={"operation": operation, "key": idempotency_key},
-                        exc_info=True,
-                    )
-                return None
+            return None
 
-            self._metrics.record_hit(operation)
-            return record
-        finally:
-            self._metrics.record_latency(operation, "get", time.perf_counter() - start)
+        return record
 
     async def save(
         self,
@@ -193,60 +192,55 @@ class RedisAsyncIdempotencyRepository(AsyncIdempotencyRepository):
             IdempotencyStorageError: If Redis operation fails
             IdempotencyError: If serialization fails
         """
-        start = time.perf_counter()
         operation = record.operation
-        try:
-            self._validate_inputs(operation, record.idempotency_key)
-            key = self._make_key(operation, record.idempotency_key)
+        self._validate_inputs(operation, record.idempotency_key)
+        key = self._make_key(operation, record.idempotency_key)
 
-            # Calculate TTL
-            ttl_seconds = math.ceil(record.ttl_seconds)
+        # Calculate TTL
+        ttl_seconds = math.ceil(record.ttl_seconds)
 
-            if ttl_seconds <= 0:
-                self._metrics.record_error(operation, "validation_error")
-                logger.warning(
-                    "Attempted to save already expired record",
-                    extra={"operation": operation, "key": record.idempotency_key},
-                )
-                raise IdempotencyValidationError("Cannot save already expired record")
+        if ttl_seconds <= 0:
+            self._metrics.record_error(operation, "validation_error")
+            logger.warning(
+                "Attempted to save already expired record",
+                extra={"operation": operation, "key": record.idempotency_key},
+            )
+            raise IdempotencyValidationError("Cannot save already expired record")
 
-            # Serialize record
-            try:
-                data = orjson.dumps(record.model_dump(mode="json")) if _HAS_ORJSON else record.model_dump_json()
-            except Exception as e:
-                self._metrics.record_error(operation, "serialization_error")
-                logger.exception(
-                    "Failed to serialize record",
-                    extra={"operation": operation, "key": record.idempotency_key},
-                )
-                raise IdempotencyError("Serialization failed") from e
+        # Serialize record
+        try:
+            data = orjson.dumps(record.model_dump(mode="json")) if _HAS_ORJSON else record.model_dump_json()
+        except Exception as e:
+            self._metrics.record_error(operation, "serialization_error")
+            logger.exception(
+                "Failed to serialize record",
+                extra={"operation": operation, "key": record.idempotency_key},
+            )
+            raise IdempotencyError("Serialization failed") from e
 
-            # Use SET with NX (only if key doesn't exist) and EX (expiration)
-            try:
-                was_set = await self._redis.set(key, data, ex=ttl_seconds, nx=True)
-            except Exception as e:
-                self._metrics.record_error(operation, type(e).__name__)
-                logger.exception(
-                    "Redis error during save",
-                    extra={"operation": operation, "key": record.idempotency_key},
-                )
-                # In case of Redis error, we cannot guarantee idempotency.
-                raise IdempotencyStorageError(
-                    "Redis storage failure during save",
-                    operation=operation,
-                    original_error=e,
-                ) from e
+        # Use SET with NX (only if key doesn't exist) and EX (expiration)
+        try:
+            was_set = await self._redis.set(key, data, ex=ttl_seconds, nx=True)
+        except Exception as e:
+            self._metrics.record_error(operation, type(e).__name__)
+            logger.exception(
+                "Redis error during save",
+                extra={"operation": operation, "key": record.idempotency_key},
+            )
+            # In case of Redis error, we cannot guarantee idempotency.
+            raise IdempotencyStorageError(
+                "Redis storage failure during save",
+                operation=operation,
+                original_error=e,
+            ) from e
 
-            if not was_set:
-                self._metrics.record_collision(operation)
-                raise IdempotencyKeyCollisionError(operation, record.idempotency_key)
+        if not was_set:
+            raise IdempotencyKeyCollisionError(operation, record.idempotency_key)
 
-            logger.debug(
-                "Saved idempotency record",
-                extra={"operation": operation, "key": record.idempotency_key, "ttl_seconds": ttl_seconds},
-            )
-        finally:
-            self._metrics.record_latency(operation, "save", time.perf_counter() - start)
+        logger.debug(
+            "Saved idempotency record",
+            extra={"operation": operation, "key": record.idempotency_key, "ttl_seconds": ttl_seconds},
+        )
 
     async def delete(self, operation: str, idempotency_key: str) -> bool:
         """Delete record from Redis.

idempotency_kit-0.2.0/idempotency_kit/settings.py

@@ -0,0 +1,25 @@
+"""Settings for idempotency kit."""
+
+from pydantic import BaseModel, Field
+
+from .core.constants import DEFAULT_TTL_MINUTES, MAX_TTL_SECONDS, MIN_TTL_SECONDS
+
+
+class BaseIdempotencySettings(BaseModel):
+    """Common configuration for idempotency kit."""
+
+    enabled: bool = Field(
+        default=True,
+        description="Whether the coordinator applies idempotency; False makes every call a pass-through",
+    )
+    key_prefix: str = Field(description="Redis key prefix for idempotency records")
+    metrics_enabled: bool = Field(default=False, description="Whether idempotency metrics are enabled")
+    default_ttl_minutes: int = Field(
+        default=DEFAULT_TTL_MINUTES, description="Default TTL for records in minutes (1 hour)"
+    )
+    min_ttl_seconds: int = Field(default=MIN_TTL_SECONDS, description="Minimum allowed TTL in seconds (1 minute)")
+    max_ttl_seconds: int = Field(default=MAX_TTL_SECONDS, description="Maximum allowed TTL in seconds (30 days)")
+    operation_ttls: dict[str, int] = Field(
+        default_factory=dict,
+        description="Operation-specific TTLs in seconds (overrides decorator and default)",
+    )

{idempotency_kit-0.1.0 → idempotency_kit-0.2.0}/pyproject.toml

@@ -50,6 +50,8 @@ test = [
     "fakeredis>=2.28.2",
     "redis>=5.0.0",
     "orjson>=3.11.7,<4.0.0",
+    "dishka>=1.0.0",
+    "prometheus-client>=0.15.0",
 ]
 docs = [
     "zensical>=0.0.37",
@@ -98,6 +100,10 @@ warn_unreachable = true
 [tool.ruff]
 line-length = 120
 target-version = "py311"
+# The Markdown guides hold fragments -- a keyword argument on its own, a body
+# without its def -- that read as code to a formatter and come out as
+# something else. ruff 0.16 formats fenced Python in Markdown by default.
+extend-exclude = ["*.md"]
 
 [tool.ruff.lint]
 select = ["F", "E", "W", "I", "B", "N", "S", "C4", "DTZ", "SIM", "TRY", "PERF", "RUF", "UP", "ANN", "T20", "PTH", "PLC", "PLE", "PLW"]

idempotency_kit-0.1.0/CHANGELOG.md

@@ -1,21 +0,0 @@
-# Changelog
-
-## 0.1.0 (2026-05-13)
-
-
-### Bug Fixes
-
-* **ci:** remove coverage threshold from integration tests ([b00f037](https://github.com/bedrock-python/idempotency-kit/commit/b00f03742925922e261790b0ee649055c31fdaae))
-* **ci:** set integration test coverage threshold to 50% ([ed4e790](https://github.com/bedrock-python/idempotency-kit/commit/ed4e7907ff977916b0be11a6597a090b9ae11cab))
-
-
-### Documentation
-
-* rewrite README to match library style with badges ([cebded3](https://github.com/bedrock-python/idempotency-kit/commit/cebded360b4c0c37d7604efd230574b4464f47c8))
-
-## Changelog
-
-All notable changes to this project will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

idempotency_kit-0.1.0/idempotency_kit/__version__.py

@@ -1 +0,0 @@
-__version__ = "0.1.0"

idempotency_kit-0.1.0/idempotency_kit/core/adapters/basic.py

@@ -1,43 +0,0 @@
-from typing import Any, TypeVar
-
-from pydantic import BaseModel
-
-from idempotency_kit.core.protocols.adapter import ResultAdapter
-
-T = TypeVar("T", bound=BaseModel)
-
-
-class PydanticResultAdapter(ResultAdapter[T]):
-    """Adapter for Pydantic models."""
-
-    def __init__(self, model_class: type[T]) -> None:
-        self.model_class = model_class
-
-    def encode(self, value: T) -> Any:
-        return value.model_dump(mode="json") if value else None
-
-    def decode(self, data: Any) -> T:
-        if not data:
-            msg = "cannot decode empty idempotency payload"
-            raise ValueError(msg)
-        return self.model_class.model_validate(data)
-
-
-class JsonResultAdapter(ResultAdapter[Any]):
-    """Adapter for JSON-serializable types (dict, list, etc.)."""
-
-    def encode(self, value: Any) -> Any:
-        return value
-
-    def decode(self, data: Any) -> Any:
-        return data
-
-
-class VoidResultAdapter(ResultAdapter[None]):
-    """Adapter for functions that return None."""
-
-    def encode(self, value: None) -> Any:
-        return None
-
-    def decode(self, data: Any) -> None:
-        return None

idempotency_kit-0.1.0/idempotency_kit/core/constants.py

@@ -1,18 +0,0 @@
-"""Core constants for idempotency."""
-
-# Key constraints
-# Maximum allowed length for idempotency key.
-MAX_KEY_LENGTH: int = 255
-
-# Maximum allowed length for operation name.
-MAX_OPERATION_LENGTH: int = 100
-
-# TTL defaults
-# Default TTL in minutes when not explicitly specified.
-DEFAULT_TTL_MINUTES: int = 30
-
-# Minimum allowed TTL in seconds (1 minute).
-MIN_TTL_SECONDS: int = 60
-
-# Maximum allowed TTL in seconds (24 hours).
-MAX_TTL_SECONDS: int = 86400  # 24 hours

idempotency_kit-0.1.0/idempotency_kit/core/decorators/aio/idempotent.py

@@ -1,93 +0,0 @@
-import functools
-from collections.abc import Awaitable, Callable
-from typing import Any, TypeVar
-
-from idempotency_kit.core.protocols.adapter import ResultAdapter
-from idempotency_kit.core.services.aio.coordinator import AsyncIdempotencyCoordinator
-
-T = TypeVar("T")
-
-
-def async_idempotent(
-    operation: str,
-    adapter: ResultAdapter[T],
-    ttl_seconds: int | None = None,
-    key_param: str = "idempotency_key",
-    infra_param: str | None = None,
-) -> Callable[[Callable[..., Awaitable[T]]], Callable[..., Awaitable[T]]]:
-    """Decorator for asynchronous idempotent operations.
-
-    Can be used on methods (finding coordinator in 'self') or standalone functions
-    (finding coordinator in arguments).
-
-    Args:
-        operation: Unique operation name.
-        adapter: Result adapter for encoding/decoding.
-        ttl_seconds: Optional TTL for idempotency record in seconds.
-            If not provided, uses value from coordinator settings or global default.
-        key_param: Name of the argument containing the idempotency key.
-        infra_param: Optional name of the argument or attribute containing AsyncIdempotencyCoordinator.
-            If not provided, searches for AsyncIdempotencyCoordinator by type.
-    """
-
-    def decorator(func: Callable[..., Awaitable[T]]) -> Callable[..., Awaitable[T]]:
-        @functools.wraps(func)
-        async def wrapper(*args: Any, **kwargs: Any) -> T:
-            # 1. Resolve idempotency key
-            idempotency_key = kwargs.get(key_param)
-            if not idempotency_key:
-                return await func(*args, **kwargs)
-
-            # 2. Resolve coordinator
-            coordinator: AsyncIdempotencyCoordinator | None = None
-
-            # 2.1. Try to find by name if infra_param is provided
-            if infra_param:
-                if infra_param in kwargs:
-                    coordinator = kwargs[infra_param]
-                elif args and hasattr(args[0], infra_param):
-                    coordinator = getattr(args[0], infra_param)
-
-            # 2.2. Try to find by type if not found or infra_param is None
-            if not coordinator:
-                # Search in kwargs
-                for val in kwargs.values():
-                    if isinstance(val, AsyncIdempotencyCoordinator):
-                        coordinator = val
-                        break
-
-                # Search in args (skipping self if it was already checked)
-                if not coordinator:
-                    for arg in args:
-                        if isinstance(arg, AsyncIdempotencyCoordinator):
-                            coordinator = arg
-                            break
-                        # Also check self attributes if arg is 'self'
-                        # We do this because DI often injects into attributes
-                        if hasattr(arg, "__dict__"):
-                            for attr_val in vars(arg).values():
-                                if isinstance(attr_val, AsyncIdempotencyCoordinator):
-                                    coordinator = attr_val
-                                    break
-                        if coordinator:
-                            break
-
-            if not coordinator:
-                # If no coordinator found but key is present, we might want to fail or proceed
-                # Proceeding without idempotency is safer but should probably be logged
-                return await func(*args, **kwargs)
-
-            # 3. Delegate to coordinator
-            return await coordinator.coordinate(
-                operation,
-                idempotency_key,
-                ttl_seconds,
-                adapter,
-                func,
-                *args,
-                **kwargs,
-            )
-
-        return wrapper
-
-    return decorator

idempotency_kit-0.1.0/idempotency_kit/dishka/common.py

@@ -1,22 +0,0 @@
-"""Common Dishka providers for idempotency."""
-
-from dishka import Provider, Scope, provide
-
-from idempotency_kit import IdempotencyDomainService
-
-from .protocols import IdempotencySettingsProtocol
-
-
-class IdempotencyProvider(Provider):
-    """Provider for idempotency domain service (sync / framework-agnostic)."""
-
-    scope = Scope.APP
-
-    @provide
-    def get_service(self, settings: IdempotencySettingsProtocol) -> IdempotencyDomainService:
-        """Provide idempotency domain service."""
-        return IdempotencyDomainService(
-            default_ttl_minutes=settings.default_ttl_minutes,
-            min_ttl_seconds=settings.min_ttl_seconds,
-            max_ttl_seconds=settings.max_ttl_seconds,
-        )

idempotency_kit-0.1.0/idempotency_kit/settings.py

@@ -1,18 +0,0 @@
-"""Settings for idempotency kit."""
-
-from pydantic import BaseModel, Field
-
-
-class BaseIdempotencySettings(BaseModel):
-    """Common configuration for idempotency kit."""
-
-    enabled: bool = Field(default=True, description="Whether idempotency is enabled")
-    key_prefix: str = Field(description="Redis key prefix for idempotency records")
-    metrics_enabled: bool = Field(default=False, description="Whether idempotency metrics are enabled")
-    default_ttl_minutes: int = Field(default=60, description="Default TTL for records in minutes")
-    min_ttl_seconds: int = Field(default=1, description="Minimum allowed TTL in seconds")
-    max_ttl_seconds: int = Field(default=30 * 24 * 3600, description="Maximum allowed TTL in seconds (30 days)")
-    operation_ttls: dict[str, int] = Field(
-        default_factory=dict,
-        description="Operation-specific TTLs in seconds (overrides decorator and default)",
-    )