idemkit 0.1.0__tar.gz → 0.1.1__tar.gz

{idemkit-0.1.0 → idemkit-0.1.1}/CHANGELOG.md

@@ -9,6 +9,18 @@ minor version may carry a breaking change, and any such change is called out her
 
 Nothing yet.
 
+## [0.1.1] - 2026-07-26
+
+### Added
+- `DynamoBackend.from_url(endpoint_url)`, for parity with the `from_url`
+  constructors on the other backends.
+
+### Fixed
+- The "volatile-looking field" warning no longer fires on ordinary business keys
+  such as `order_id` or `customer_id`. It now matches only known per-call /
+  per-request id names (`request_id`, `trace_id`, `tool_call_id`, and similar), so
+  the getting-started example no longer warns about its own key.
+
 ## [0.1.0] - 2026-07-26
 
 First public release. Pre-1.0: the API may still shift, and a minor version may

{idemkit-0.1.0 → idemkit-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: idemkit
-Version: 0.1.0
+Version: 0.1.1
 Summary: Make any operation safe to retry: crash-safe idempotency for HTTP requests, queue messages, and function calls, on Redis, Postgres, MongoDB, or DynamoDB.
 Project-URL: Homepage, https://github.com/idemkit/idemkit
 Project-URL: Documentation, https://github.com/idemkit/idemkit/blob/main/python/README.md
@@ -62,9 +62,11 @@ Description-Content-Type: text/markdown
 
 # idemkit for Python
 
+[![PyPI](https://img.shields.io/pypi/v/idemkit.svg)](https://pypi.org/project/idemkit/)
 [![CI](https://github.com/idemkit/idemkit/actions/workflows/ci.yml/badge.svg)](https://github.com/idemkit/idemkit/actions/workflows/ci.yml)
 [![License: Apache 2.0](https://img.shields.io/badge/license-Apache_2.0-blue.svg)](../LICENSE)
 [![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org)
+[![Downloads](https://img.shields.io/pypi/dm/idemkit.svg)](https://pypi.org/project/idemkit/)
 
 Make any operation safe to retry. When a client retries, a broker redelivers, or an agent re-plans, idemkit runs your code **once per key** and replays the first result to the duplicates, even when they arrive at the same instant.
 
@@ -87,14 +89,11 @@ New to the vocabulary (*lease*, *fencing token*, *scope*, *fingerprint*)? Each l
 
 ## Install
 
-Not on PyPI yet — install from source:
-
 ```bash
-git clone https://github.com/idemkit/idemkit && cd idemkit/python
-pip install -e ".[asgi,redis]"        # pick the extras you need
+pip install "idemkit[redis]"     # or [postgres], [mongo], [dynamodb], [asgi]
 ```
 
-Once published, this becomes `pip install "idemkit[redis]"` (or `[postgres]`, `[mongo]`, `[dynamodb]`, `[asgi]`).
+Working on idemkit itself? Install from source instead: see [Contributing](#contributing).
 
 The core has no third-party dependencies. Runs on Python 3.10 to 3.13, Redis 6+/Cluster, PostgreSQL 12+, MongoDB 4.2+, DynamoDB, any ASGI 3 or WSGI app.
 
@@ -117,7 +116,7 @@ The middleware wraps the whole app, but by default it only acts on `POST` and `P
 Works in 30 seconds, no infrastructure (the `[asgi]` extra ships Starlette; this snippet also uses FastAPI):
 
 ```bash
-pip install -e ".[asgi]" fastapi uvicorn
+pip install "idemkit[asgi]" fastapi uvicorn
 ```
 
 ```python

{idemkit-0.1.0 → idemkit-0.1.1}/README.md

@@ -1,8 +1,10 @@
 # idemkit for Python
 
+[![PyPI](https://img.shields.io/pypi/v/idemkit.svg)](https://pypi.org/project/idemkit/)
 [![CI](https://github.com/idemkit/idemkit/actions/workflows/ci.yml/badge.svg)](https://github.com/idemkit/idemkit/actions/workflows/ci.yml)
 [![License: Apache 2.0](https://img.shields.io/badge/license-Apache_2.0-blue.svg)](../LICENSE)
 [![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org)
+[![Downloads](https://img.shields.io/pypi/dm/idemkit.svg)](https://pypi.org/project/idemkit/)
 
 Make any operation safe to retry. When a client retries, a broker redelivers, or an agent re-plans, idemkit runs your code **once per key** and replays the first result to the duplicates, even when they arrive at the same instant.
 
@@ -25,14 +27,11 @@ New to the vocabulary (*lease*, *fencing token*, *scope*, *fingerprint*)? Each l
 
 ## Install
 
-Not on PyPI yet — install from source:
-
 ```bash
-git clone https://github.com/idemkit/idemkit && cd idemkit/python
-pip install -e ".[asgi,redis]"        # pick the extras you need
+pip install "idemkit[redis]"     # or [postgres], [mongo], [dynamodb], [asgi]
 ```
 
-Once published, this becomes `pip install "idemkit[redis]"` (or `[postgres]`, `[mongo]`, `[dynamodb]`, `[asgi]`).
+Working on idemkit itself? Install from source instead: see [Contributing](#contributing).
 
 The core has no third-party dependencies. Runs on Python 3.10 to 3.13, Redis 6+/Cluster, PostgreSQL 12+, MongoDB 4.2+, DynamoDB, any ASGI 3 or WSGI app.
 
@@ -55,7 +54,7 @@ The middleware wraps the whole app, but by default it only acts on `POST` and `P
 Works in 30 seconds, no infrastructure (the `[asgi]` extra ships Starlette; this snippet also uses FastAPI):
 
 ```bash
-pip install -e ".[asgi]" fastapi uvicorn
+pip install "idemkit[asgi]" fastapi uvicorn
 ```
 
 ```python

idemkit-0.1.1/idemkit/_version.py

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

{idemkit-0.1.0 → idemkit-0.1.1}/idemkit/adapters/ai.py

@@ -661,8 +661,29 @@ def _canonical_hash(selected: Mapping[str, Any]) -> str:
     return hashlib.sha256(canonical.encode("utf-8")).hexdigest()
 
 
+# Field NAMES that read as per-call / per-request identifiers: they change on every
+# retry, so they must never be the idempotency key. A business key that merely ends
+# in "_id" (order_id, customer_id, payment_id) is the RIGHT thing to key on and is
+# deliberately NOT in this set.
 _VOLATILE_NAMES = frozenset(
-    {"request_id", "requestid", "nonce", "timestamp", "ts", "idempotency_key"}
+    {
+        "request_id",
+        "requestid",
+        "trace_id",
+        "traceid",
+        "span_id",
+        "spanid",
+        "correlation_id",
+        "correlationid",
+        "tool_call_id",
+        "toolcallid",
+        "call_id",
+        "callid",
+        "nonce",
+        "timestamp",
+        "ts",
+        "idempotency_key",
+    }
 )
 _UUID_RE = re.compile(
     r"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-"
@@ -709,10 +730,14 @@ def _value_looks_like_call_id(value: str) -> bool:
 def _name_looks_volatile(name: str) -> bool:
     """Whether a field name alone (no value) reads as volatile.
 
-    Used at decoration time, where only the names in ``key_fields`` are known.
+    Used at decoration time, where only the names in ``key_fields`` are known. It
+    matches KNOWN per-call / per-request id names (request_id, trace_id,
+    tool_call_id, ...), not every field ending in ``_id``: a business key like
+    ``order_id`` or ``customer_id`` is exactly what you should key on, so it must
+    not warn.
     """
     lowered = name.lower()
-    if lowered in _VOLATILE_NAMES or lowered.endswith("_id"):
+    if lowered in _VOLATILE_NAMES:
         return True
     return "timestamp" in lowered or "nonce" in lowered
 

{idemkit-0.1.0 → idemkit-0.1.1}/idemkit/backends/dynamodb.py

@@ -87,6 +87,33 @@ class DynamoBackend:
 
         self._init_lock = asyncio.Lock()
 
+    @classmethod
+    def from_url(
+        cls,
+        url: str,
+        *,
+        table: str = DEFAULT_TABLE,
+        region_name: str = "us-east-1",
+        create_table: bool = True,
+        lease_grace_seconds: float = 60.0,
+        **client_kwargs: Any,
+    ) -> DynamoBackend:
+        """Construct from a DynamoDB endpoint URL, for parity with the other backends.
+
+        ``url`` is the DynamoDB endpoint, e.g. ``http://localhost:8000`` for DynamoDB
+        Local or LocalStack. On real AWS you usually need no endpoint: build
+        ``DynamoBackend(region_name=...)`` directly and let botocore resolve it. Extra
+        keyword arguments go to the aioboto3 resource (e.g. credentials).
+        """
+        return cls(
+            table=table,
+            endpoint_url=url,
+            region_name=region_name,
+            create_table=create_table,
+            lease_grace_seconds=lease_grace_seconds,
+            **client_kwargs,
+        )
+
     async def _ensure_table(self) -> Any:
         if self._table is not None:
             return self._table

{idemkit-0.1.0 → idemkit-0.1.1}/tests/backends/test_dynamodb_backend.py

@@ -29,6 +29,17 @@ def _dynamo(table: str, **kwargs):
     )
 
 
+def test_from_url_matches_direct_construction() -> None:
+    """`from_url` exists for parity with the other backends and maps the URL to the
+    endpoint, without connecting (lazy)."""
+    from idemkit.backends.dynamodb import DynamoBackend
+
+    backend = DynamoBackend.from_url(DYNAMODB_ENDPOINT, table="idempotency_keys")
+    assert backend._endpoint_url == DYNAMODB_ENDPOINT
+    assert backend._table_name == "idempotency_keys"
+    assert backend._create_table is True
+
+
 def _k(suffix: str) -> str:
     return f"dynamo-{suffix}-{uuid.uuid4().hex}"
 

{idemkit-0.1.0 → idemkit-0.1.1}/tests/method/test_ai_tool.py

@@ -527,6 +527,24 @@ def test_volatile_field_named_in_key_fields_warns(backend) -> None:
             return {"r": request_id}
 
 
+def test_business_id_key_does_not_warn(backend) -> None:
+    """A business key ending in _id (order_id, customer_id) is the RIGHT key to
+    dedupe on and must NOT trip the volatile-field warning (fixed false positive)."""
+    import warnings
+
+    with warnings.catch_warnings():
+        warnings.simplefilter("error")  # any UserWarning here becomes a test failure
+
+        @idempotent(
+            backend=backend,
+            config=MethodConfig(scope=lambda a: "s", key_fields=["order_id", "customer_id"]),
+        )
+        async def charge(*, order_id, customer_id):
+            return {"order_id": order_id}
+
+    assert charge is not None
+
+
 def test_key_fields_allowed_with_var_keyword(backend) -> None:
     """A tool taking **kwargs can name key fields not in its explicit signature —
     we can't validate those, so don't reject them."""

idemkit-0.1.0/idemkit/_version.py

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