controlvar 0.2.0__tar.gz → 0.3.0__tar.gz

{controlvar-0.2.0 → controlvar-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: controlvar
-Version: 0.2.0
+Version: 0.3.0
 Summary: Python client for the Controlvar public API (experiments, feature flags, event tracking)
 License: MIT
 Project-URL: Homepage, https://github.com/Controlvar/controlvar/tree/main/sdk/python#readme
@@ -42,11 +42,11 @@ else to install.
 
 If you installed `experimently`, the name this package had before the project was renamed, uninstall it and install `controlvar`.
 
-The `controlvar` package is on [PyPI](https://pypi.org/project/controlvar/). 0.2.0 is a
+The `controlvar` package is on [PyPI](https://pypi.org/project/controlvar/). 0.3.0 is a
 beta release. It installs and imports as `controlvar`.
 
 ```bash
-pip install controlvar==0.2.0
+pip install controlvar==0.3.0
 ```
 
 To work on the SDK itself, install it from the root of a clone of this repository instead:
@@ -57,19 +57,55 @@ pip install -e sdk/python
 
 ## Changes in this version
 
-- `report_error()` is new: it sends one error report to the server and returns `True` when the
-  server stored it.
-- `track()` returns `True` when the event was sent and the server answered 2xx, and `False`
-  otherwise. Before this version, a `track()` without a key returned `True` only when the server
-  accepted every entry it was fanned out to. Now a batch answered 2xx returns `True` even when the
-  server refused one of its entries; `track_batch()` returns the per-entry results.
-- A `track()` without a key still reaches the experiments and flags this client answered for the
-  user in the last 24 hours (with the exceptions under Tracking fan-out rule) after their cached
-  answers expire; before this version it reached only the answers still in the cache. Those keys
-  are this client instance's only: an event tracked by another instance, in this process or
-  another, reaches none of them.
-- With nothing to reach, a `track()` without a key is now sent once with no key and stored as
-  history, and returns `True` on a 2xx; before this version it sent nothing and returned `False`.
+- `get_string_value`, `get_number_value` and `get_json_value` are new: they read the value a
+  string, number or json flag serves. Each returns your `default` (keyword-only) when it cannot,
+  logs a warning, and passes the reason to `on_error(error, "value")`. See
+  [Flag values](https://github.com/Controlvar/controlvar/blob/main/docs/sdk/python.md#flag-values).
+- `FlagEvaluation` gains `value` and `value_type`, after `source`, so building one by position
+  still works. `FlagEvaluation` equality, `repr` and `astuple`/`asdict` include the two new fields.
+- `ExperimentationError` gains `code`: `"TYPE_MISMATCH"` or `"INVALID_RESPONSE"` on the errors the
+  typed getters make, and `"HOOK_ERROR"` on the error `on_error` receives with `"exposure"`. Other
+  errors carry no code in this version; `status` describes them.
+- `on_exposure` is new: a function you give the client when you create it, which it calls once each
+  time the server enrols a user in an experiment and the answer did not come from its cache. It
+  receives an `Exposure`, which `controlvar` exports. See Exposure hook below.
+- `on_error` is now also called in server mode: with the operation `"value"` when a typed getter
+  returns your default, and with `"exposure"` when `on_exposure` raises. Code that treats an
+  operation or a `code` it does not know as a mistake should handle them.
+- `track()` takes an `event_id`, and `track_batch()` sends the `event_id` key of an event's dict.
+  See Event ids below.
+- `track()` returns `False`, and sends nothing, when `event_value` or `properties` holds NaN or an
+  infinite number; see Tracking fan-out rule for the other methods. Before this version the request
+  was sent.
+- Local evaluation answers a string, number or json flag's value too. A flag entry with an
+  `evaluation` this SDK does not know sends only that flag to the server, and the rest of the
+  ruleset is still answered locally; before this version it refused the whole ruleset, and the
+  client kept answering from its last one. An entry with a `value_type` it does not know, or a
+  value of the wrong type, also sends only that flag to the server.
+- Once local evaluation stops answering a flag (`max_stale_seconds` passed, the ruleset discarded,
+  `close()`), a call for a user it answered locally goes to the server; before this version that
+  user kept the local answer from the cache for up to `cache_ttl_seconds`.
+- With a finite `cache_ttl_seconds` above 24 hours, a `track()` without a key still reaches an
+  experiment or flag whose answer is still cached; before this version it reached only those
+  answered in the last 24 hours.
+- The message of a request that fails on the network, and the warning the client logs for it,
+  name the URL without its query string, which carries the user id and the user's attributes;
+  before this version they named the full URL.
+
+## Event ids
+
+`track(..., event_id=None)` sends an `event_id`, and `track_batch()` sends the `event_id` key of
+an event's dict as it is. The server stores an event sent again with the same `event_id`, user,
+experiment, flag and event name only once. It needs a Controlvar server that includes the `event_id` change (#1640,
+in the first platform release after it merged): an older server ignores the field.
+
+- The SDK makes no id: without an `event_id` none is sent, and an event sent again is counted
+  again. Make the id once, when the event happens, and give the same one each time you send it.
+- `None` and `""` send none. The server refuses an id of more than 255 characters or one holding
+  NUL with `422`; the SDK does not check it.
+- An event fanned out to several experiments and flags carries the same id in every entry. A `429`
+  that is retried sends the same id. A request that fails on the network or times out is not sent
+  again by the SDK.
 
 ## Quick start
 
@@ -96,7 +132,7 @@ assignment.variant_name, assignment.is_control, assignment.configuration
 # Feature flags (GET /api/v1/feature-flags/evaluate/{key}?user_id=…&context=<url-encoded attributes>)
 if client.is_feature_enabled("new_search", "user-123", user_attributes={"plan": "pro"}):
     print("use the new search")      # your own code
-flag = client.get_feature_flag("new_search", "user-123")          # FlagEvaluation(key, enabled, config, reason)
+flag = client.get_feature_flag("new_search", "user-123")          # FlagEvaluation(key, enabled, config, reason, source, value, value_type)
 flags = client.get_all_flags("user-123", {"plan": "pro"})          # {"new_search": True, ...}
 
 # Tracking (never raises)
@@ -113,10 +149,13 @@ default_variant="control", transport=None)`. Instances are thread-safe.
 |---|---|---|
 | `get_assignment(experiment_key, user_id, user_attributes=None)` | `Assignment(experiment_key, user_id, variant_id, variant_name, is_control, configuration, assigned, reason)` | raises `ExperimentationError` (`status == 404` when no experiment has the key, or for a draft with no control variant); an experiment that is not ACTIVE returns its control variant with `assigned` False and `reason` its status |
 | `get_variant(experiment_key, user_id, user_attributes=None)` | `str` variant name | returns `default_variant` |
-| `get_feature_flag(flag_key, user_id, user_attributes=None)` | `FlagEvaluation(key, enabled, config, reason)` | raises `ExperimentationError` (`status == 404` when the flag key is unknown; a flag that is not ACTIVE returns `enabled=False`, `reason="inactive"`) |
+| `get_feature_flag(flag_key, user_id, user_attributes=None)` | `FlagEvaluation(key, enabled, config, reason, source, value, value_type)` | raises `ExperimentationError` (`status == 404` when the flag key is unknown; a flag that is not ACTIVE returns `enabled=False`, `reason="inactive"`) |
 | `is_feature_enabled(flag_key, user_id, user_attributes=None)` | `bool` | returns `False` |
+| `get_string_value(flag_key, user_id, user_attributes=None, *, default)` | `str`, the string a string flag serves this user | returns `default`; never raises; logs a warning and calls `on_error(error, "value")` |
+| `get_number_value(flag_key, user_id, user_attributes=None, *, default)` | `int` or `float` as saved (never a `bool`), the number a number flag serves this user | returns `default`; never raises; logs a warning and calls `on_error(error, "value")` |
+| `get_json_value(flag_key, user_id, user_attributes=None, *, default)` | a new copy of the `dict` or `list` a json flag serves this user | returns `default`; never raises; logs a warning and calls `on_error(error, "value")` |
 | `get_all_flags(user_id, user_attributes=None)` | `dict[str, bool]` (not cached) | raises `ExperimentationError` |
-| `track(user_id, event_name, event_value=None, properties=None, experiment_key=None, feature_flag_key=None, event_type=None, timestamp=None)` | `bool` — `True` when sent and answered 2xx | never raises; `False` on failure |
+| `track(user_id, event_name, event_value=None, properties=None, experiment_key=None, feature_flag_key=None, event_type=None, timestamp=None, event_id=None)` | `bool` — `True` when sent and answered 2xx | never raises; `False` on failure |
 | `track_batch(events)` | `BatchResult(success_count, failure_count, errors)`; `.ok` | never raises; a failed chunk counts all its events as failures |
 | `report_error(error_type, message, *, feature_flag_key=None, experiment_key=None, user_id=None, stack_trace=None, metadata=None, timestamp=None)` | `bool` — `True` when the server stored the report (201) | never raises; `False` and a logged warning otherwise |
 | `get_assignments(user_id, active_only=True)` | `list[dict]` from the server | raises `ExperimentationError` |
@@ -125,9 +164,11 @@ default_variant="control", transport=None)`. Instances are thread-safe.
 | `ready(timeout_seconds=None)`, `status()`, `close()` / `with` | local mode: readiness, ruleset state, shutdown (sends evaluation counts) | never raise |
 | `consistent_hash(user_id, flag_key)` / `md5_hex(user_id, flag_key)` | cross-SDK MD5 bucket in `[0, 1)` / hex digest | pure functions; **not** the flag bucketing function |
 
-`ExperimentationError` carries `.status` (HTTP status, `None` for network errors/timeouts) and
-`.body` (raw response text). Failures are never cached, so the next call retries. A `429` is
-retried once after `Retry-After` seconds (capped at 5 s).
+`ExperimentationError` carries `.status` (HTTP status, `None` for network errors/timeouts),
+`.body` (raw response text) and `.code`: `"TYPE_MISMATCH"` or `"INVALID_RESPONSE"` on an error a
+typed getter makes itself, and `"HOOK_ERROR"` on the error `on_error` receives with `"exposure"`.
+Other errors carry no code in this version; `.status` describes them. Failures are never cached, so
+the next call retries. A `429` is retried once after `Retry-After` seconds (capped at 5 s).
 
 `user_attributes` is sent as `context` on assignment **and** on flag evaluation
 (`&context=<url-encoded JSON>`, omitted when empty), so flag targeting rules evaluate against it
@@ -171,16 +212,78 @@ another process does not have them. In a server, pass `experiment_key` on conver
 `event_type` defaults to `event_name`; `properties` is sent as `metadata`; `timestamp` may be a
 `datetime` (naive values are treated as UTC) or an ISO-8601 string.
 
+`track` returns `False`, and sends nothing, when `event_value` or `properties` holds NaN or an
+infinite number. `get_assignment` raises `ExperimentationError`
+for the same in `user_attributes`, and `get_variant` returns the default for a user with no
+cached assignment (a cached assignment is returned as before).
+
+## Exposure hook
+
+`on_exposure` is a function you give the client when you create it. The client calls it once each
+time the server enrols the user in an experiment and the answer did not come from the client's
+cache: the moment the server records the exposure. Use it to send the exposure to your analytics
+tool or warehouse.
+
+The example needs an ACTIVE experiment with the key `checkout_flow`; put your own key in its place.
+It prints `exposure checkout_flow <variant> user-123` once, or nothing for a user the experiment
+did not enrol.
+
+```python
+import os
+import queue
+import threading
+
+from controlvar import ExperimentationClient
+
+exposures = queue.Queue(maxsize=10_000)
+
+
+def send_exposures():
+    while True:
+        exposure = exposures.get()
+        # Your analytics tool's call goes here: it runs on this thread, not inside get_variant.
+        print("exposure", exposure.experiment_key, exposure.variant_name, exposure.user_id)
+        exposures.task_done()
+
+
+threading.Thread(target=send_exposures, daemon=True).start()
+
+
+def on_exposure(exposure):
+    try:
+        exposures.put_nowait(exposure)
+    except queue.Full:
+        pass  # drop it rather than make get_variant wait
+
+
+client = ExperimentationClient(
+    api_url=os.environ.get("CONTROLVAR_API_URL", "http://localhost:8000"),
+    api_key=os.environ["CONTROLVAR_API_KEY"],
+    on_exposure=on_exposure,
+)
+client.get_variant("checkout_flow", "user-123")
+exposures.join()
+```
+
+It receives an `Exposure`: `experiment_key`, `user_id`, `variant_id` (`None` when the server sends
+none) and `variant_name`. It is not called for a cached answer, a user the experiment did not enrol
+or an experiment that is not running (`assigned` False), a call that fails, or a feature flag. It
+runs in the thread that called `get_assignment` or `get_variant`, before that call returns, so keep
+it quick. If it raises, the answer is unchanged, and the error is logged at ERROR and passed to
+`on_error` with the operation `"exposure"` and `code` `"HOOK_ERROR"`.
+
+Full details: [Exposure hook](https://github.com/Controlvar/controlvar/blob/main/docs/sdk/python.md#exposure-hook).
+
 ## Backend endpoints used
 
 Every request carries `X-API-Key: <key>`, `Content-Type: application/json` and `Accept: application/json`.
 
 | SDK call | Method and path | Body / query | Response used |
 |---|---|---|---|
-| `get_assignment`, `get_variant` | `POST /api/v1/tracking/assign` | `{experiment_key, user_id, context?}` | `{experiment_key, user_id, variant_id, variant_name, is_control, configuration}`; 404 when no experiment has the key, or for a draft with no control variant; an experiment that is not ACTIVE answers its control variant with `assigned: false` |
+| `get_assignment`, `get_variant` | `POST /api/v1/tracking/assign` | `{experiment_key, user_id, context?}` | `{experiment_key, user_id, variant_id, variant_name, is_control, configuration, assigned, reason}`; 404 when no experiment has the key, or for a draft with no control variant; an experiment that is not ACTIVE answers its control variant with `assigned: false` |
 | `get_feature_flag`, `is_feature_enabled` | `GET /api/v1/feature-flags/evaluate/{flag_key}?user_id=…&context=<url-encoded JSON>` | `context` = `user_attributes` (omitted when empty) | `{key, enabled, config, reason}`; off with `reason: "inactive"` when the flag exists but is not ACTIVE; 404 only for an unknown key |
 | `get_all_flags` | `GET /api/v1/feature-flags/user/{user_id}?context=<url-encoded JSON>` | `context` = `user_attributes` (omitted when empty) | `{"<flag_key>": bool, …}` |
-| `track` with a key | `POST /api/v1/tracking/track` | `{event_type, event_name, user_id, experiment_key?, feature_flag_key?, value?, metadata?, timestamp?}` | ignored |
+| `track` with a key | `POST /api/v1/tracking/track` | `{event_type, event_name, user_id, experiment_key?, feature_flag_key?, value?, metadata?, timestamp?, event_id?}` | ignored |
 | `track` without keys | `POST /api/v1/tracking/batch`, one entry per experiment and flag it reaches; with none, `POST /api/v1/tracking/track` | `{events: [<track body>, …]}` (≤ 100 per request); with none, the track body with no key | ignored |
 | `track_batch` | `POST /api/v1/tracking/batch` | `{events: [<track body>, …]}` (≤ 100 per request) | `{success_count, failure_count, errors}` |
 | `get_assignments` | `GET /api/v1/tracking/assignments/{user_id}?active_only=true` | — | list of dicts |
@@ -194,7 +297,7 @@ CONTROLVAR_API_KEY=<key> python sdk/python/examples/contract_smoke.py
 It prints:
 
 ```text
-{"sdk":"python","assign":{"variant_name":"treatment","is_control":false,"sticky":true},"flag":{"enabled":true},"track":{"ok":true},"fanout":{"ok":true}}
+{"sdk":"python","assign":{"variant_name":"treatment","is_control":false,"sticky":true},"flag":{"enabled":true},"track":{"ok":true},"fanout":{"ok":true},"event_id":{"user_id":"smoke-<uuid>","event_name":"contract_dedup_<uuid>","id":"contract-<uuid>","sends":2},"exposure":{"calls":1,"payload":{"experiment_key":"sdk_contract_ab","variant_name":"treatment","variant_id":"<id>","user_id":"smoke-<uuid>"}}}
 ```
 
 Env: `CONTROLVAR_API_URL` (default `http://localhost:8000`), `CONTROLVAR_API_KEY` (required),

{controlvar-0.2.0 → controlvar-0.3.0}/README.md

@@ -16,11 +16,11 @@ else to install.
 
 If you installed `experimently`, the name this package had before the project was renamed, uninstall it and install `controlvar`.
 
-The `controlvar` package is on [PyPI](https://pypi.org/project/controlvar/). 0.2.0 is a
+The `controlvar` package is on [PyPI](https://pypi.org/project/controlvar/). 0.3.0 is a
 beta release. It installs and imports as `controlvar`.
 
 ```bash
-pip install controlvar==0.2.0
+pip install controlvar==0.3.0
 ```
 
 To work on the SDK itself, install it from the root of a clone of this repository instead:
@@ -31,19 +31,55 @@ pip install -e sdk/python
 
 ## Changes in this version
 
-- `report_error()` is new: it sends one error report to the server and returns `True` when the
-  server stored it.
-- `track()` returns `True` when the event was sent and the server answered 2xx, and `False`
-  otherwise. Before this version, a `track()` without a key returned `True` only when the server
-  accepted every entry it was fanned out to. Now a batch answered 2xx returns `True` even when the
-  server refused one of its entries; `track_batch()` returns the per-entry results.
-- A `track()` without a key still reaches the experiments and flags this client answered for the
-  user in the last 24 hours (with the exceptions under Tracking fan-out rule) after their cached
-  answers expire; before this version it reached only the answers still in the cache. Those keys
-  are this client instance's only: an event tracked by another instance, in this process or
-  another, reaches none of them.
-- With nothing to reach, a `track()` without a key is now sent once with no key and stored as
-  history, and returns `True` on a 2xx; before this version it sent nothing and returned `False`.
+- `get_string_value`, `get_number_value` and `get_json_value` are new: they read the value a
+  string, number or json flag serves. Each returns your `default` (keyword-only) when it cannot,
+  logs a warning, and passes the reason to `on_error(error, "value")`. See
+  [Flag values](https://github.com/Controlvar/controlvar/blob/main/docs/sdk/python.md#flag-values).
+- `FlagEvaluation` gains `value` and `value_type`, after `source`, so building one by position
+  still works. `FlagEvaluation` equality, `repr` and `astuple`/`asdict` include the two new fields.
+- `ExperimentationError` gains `code`: `"TYPE_MISMATCH"` or `"INVALID_RESPONSE"` on the errors the
+  typed getters make, and `"HOOK_ERROR"` on the error `on_error` receives with `"exposure"`. Other
+  errors carry no code in this version; `status` describes them.
+- `on_exposure` is new: a function you give the client when you create it, which it calls once each
+  time the server enrols a user in an experiment and the answer did not come from its cache. It
+  receives an `Exposure`, which `controlvar` exports. See Exposure hook below.
+- `on_error` is now also called in server mode: with the operation `"value"` when a typed getter
+  returns your default, and with `"exposure"` when `on_exposure` raises. Code that treats an
+  operation or a `code` it does not know as a mistake should handle them.
+- `track()` takes an `event_id`, and `track_batch()` sends the `event_id` key of an event's dict.
+  See Event ids below.
+- `track()` returns `False`, and sends nothing, when `event_value` or `properties` holds NaN or an
+  infinite number; see Tracking fan-out rule for the other methods. Before this version the request
+  was sent.
+- Local evaluation answers a string, number or json flag's value too. A flag entry with an
+  `evaluation` this SDK does not know sends only that flag to the server, and the rest of the
+  ruleset is still answered locally; before this version it refused the whole ruleset, and the
+  client kept answering from its last one. An entry with a `value_type` it does not know, or a
+  value of the wrong type, also sends only that flag to the server.
+- Once local evaluation stops answering a flag (`max_stale_seconds` passed, the ruleset discarded,
+  `close()`), a call for a user it answered locally goes to the server; before this version that
+  user kept the local answer from the cache for up to `cache_ttl_seconds`.
+- With a finite `cache_ttl_seconds` above 24 hours, a `track()` without a key still reaches an
+  experiment or flag whose answer is still cached; before this version it reached only those
+  answered in the last 24 hours.
+- The message of a request that fails on the network, and the warning the client logs for it,
+  name the URL without its query string, which carries the user id and the user's attributes;
+  before this version they named the full URL.
+
+## Event ids
+
+`track(..., event_id=None)` sends an `event_id`, and `track_batch()` sends the `event_id` key of
+an event's dict as it is. The server stores an event sent again with the same `event_id`, user,
+experiment, flag and event name only once. It needs a Controlvar server that includes the `event_id` change (#1640,
+in the first platform release after it merged): an older server ignores the field.
+
+- The SDK makes no id: without an `event_id` none is sent, and an event sent again is counted
+  again. Make the id once, when the event happens, and give the same one each time you send it.
+- `None` and `""` send none. The server refuses an id of more than 255 characters or one holding
+  NUL with `422`; the SDK does not check it.
+- An event fanned out to several experiments and flags carries the same id in every entry. A `429`
+  that is retried sends the same id. A request that fails on the network or times out is not sent
+  again by the SDK.
 
 ## Quick start
 
@@ -70,7 +106,7 @@ assignment.variant_name, assignment.is_control, assignment.configuration
 # Feature flags (GET /api/v1/feature-flags/evaluate/{key}?user_id=…&context=<url-encoded attributes>)
 if client.is_feature_enabled("new_search", "user-123", user_attributes={"plan": "pro"}):
     print("use the new search")      # your own code
-flag = client.get_feature_flag("new_search", "user-123")          # FlagEvaluation(key, enabled, config, reason)
+flag = client.get_feature_flag("new_search", "user-123")          # FlagEvaluation(key, enabled, config, reason, source, value, value_type)
 flags = client.get_all_flags("user-123", {"plan": "pro"})          # {"new_search": True, ...}
 
 # Tracking (never raises)
@@ -87,10 +123,13 @@ default_variant="control", transport=None)`. Instances are thread-safe.
 |---|---|---|
 | `get_assignment(experiment_key, user_id, user_attributes=None)` | `Assignment(experiment_key, user_id, variant_id, variant_name, is_control, configuration, assigned, reason)` | raises `ExperimentationError` (`status == 404` when no experiment has the key, or for a draft with no control variant); an experiment that is not ACTIVE returns its control variant with `assigned` False and `reason` its status |
 | `get_variant(experiment_key, user_id, user_attributes=None)` | `str` variant name | returns `default_variant` |
-| `get_feature_flag(flag_key, user_id, user_attributes=None)` | `FlagEvaluation(key, enabled, config, reason)` | raises `ExperimentationError` (`status == 404` when the flag key is unknown; a flag that is not ACTIVE returns `enabled=False`, `reason="inactive"`) |
+| `get_feature_flag(flag_key, user_id, user_attributes=None)` | `FlagEvaluation(key, enabled, config, reason, source, value, value_type)` | raises `ExperimentationError` (`status == 404` when the flag key is unknown; a flag that is not ACTIVE returns `enabled=False`, `reason="inactive"`) |
 | `is_feature_enabled(flag_key, user_id, user_attributes=None)` | `bool` | returns `False` |
+| `get_string_value(flag_key, user_id, user_attributes=None, *, default)` | `str`, the string a string flag serves this user | returns `default`; never raises; logs a warning and calls `on_error(error, "value")` |
+| `get_number_value(flag_key, user_id, user_attributes=None, *, default)` | `int` or `float` as saved (never a `bool`), the number a number flag serves this user | returns `default`; never raises; logs a warning and calls `on_error(error, "value")` |
+| `get_json_value(flag_key, user_id, user_attributes=None, *, default)` | a new copy of the `dict` or `list` a json flag serves this user | returns `default`; never raises; logs a warning and calls `on_error(error, "value")` |
 | `get_all_flags(user_id, user_attributes=None)` | `dict[str, bool]` (not cached) | raises `ExperimentationError` |
-| `track(user_id, event_name, event_value=None, properties=None, experiment_key=None, feature_flag_key=None, event_type=None, timestamp=None)` | `bool` — `True` when sent and answered 2xx | never raises; `False` on failure |
+| `track(user_id, event_name, event_value=None, properties=None, experiment_key=None, feature_flag_key=None, event_type=None, timestamp=None, event_id=None)` | `bool` — `True` when sent and answered 2xx | never raises; `False` on failure |
 | `track_batch(events)` | `BatchResult(success_count, failure_count, errors)`; `.ok` | never raises; a failed chunk counts all its events as failures |
 | `report_error(error_type, message, *, feature_flag_key=None, experiment_key=None, user_id=None, stack_trace=None, metadata=None, timestamp=None)` | `bool` — `True` when the server stored the report (201) | never raises; `False` and a logged warning otherwise |
 | `get_assignments(user_id, active_only=True)` | `list[dict]` from the server | raises `ExperimentationError` |
@@ -99,9 +138,11 @@ default_variant="control", transport=None)`. Instances are thread-safe.
 | `ready(timeout_seconds=None)`, `status()`, `close()` / `with` | local mode: readiness, ruleset state, shutdown (sends evaluation counts) | never raise |
 | `consistent_hash(user_id, flag_key)` / `md5_hex(user_id, flag_key)` | cross-SDK MD5 bucket in `[0, 1)` / hex digest | pure functions; **not** the flag bucketing function |
 
-`ExperimentationError` carries `.status` (HTTP status, `None` for network errors/timeouts) and
-`.body` (raw response text). Failures are never cached, so the next call retries. A `429` is
-retried once after `Retry-After` seconds (capped at 5 s).
+`ExperimentationError` carries `.status` (HTTP status, `None` for network errors/timeouts),
+`.body` (raw response text) and `.code`: `"TYPE_MISMATCH"` or `"INVALID_RESPONSE"` on an error a
+typed getter makes itself, and `"HOOK_ERROR"` on the error `on_error` receives with `"exposure"`.
+Other errors carry no code in this version; `.status` describes them. Failures are never cached, so
+the next call retries. A `429` is retried once after `Retry-After` seconds (capped at 5 s).
 
 `user_attributes` is sent as `context` on assignment **and** on flag evaluation
 (`&context=<url-encoded JSON>`, omitted when empty), so flag targeting rules evaluate against it
@@ -145,16 +186,78 @@ another process does not have them. In a server, pass `experiment_key` on conver
 `event_type` defaults to `event_name`; `properties` is sent as `metadata`; `timestamp` may be a
 `datetime` (naive values are treated as UTC) or an ISO-8601 string.
 
+`track` returns `False`, and sends nothing, when `event_value` or `properties` holds NaN or an
+infinite number. `get_assignment` raises `ExperimentationError`
+for the same in `user_attributes`, and `get_variant` returns the default for a user with no
+cached assignment (a cached assignment is returned as before).
+
+## Exposure hook
+
+`on_exposure` is a function you give the client when you create it. The client calls it once each
+time the server enrols the user in an experiment and the answer did not come from the client's
+cache: the moment the server records the exposure. Use it to send the exposure to your analytics
+tool or warehouse.
+
+The example needs an ACTIVE experiment with the key `checkout_flow`; put your own key in its place.
+It prints `exposure checkout_flow <variant> user-123` once, or nothing for a user the experiment
+did not enrol.
+
+```python
+import os
+import queue
+import threading
+
+from controlvar import ExperimentationClient
+
+exposures = queue.Queue(maxsize=10_000)
+
+
+def send_exposures():
+    while True:
+        exposure = exposures.get()
+        # Your analytics tool's call goes here: it runs on this thread, not inside get_variant.
+        print("exposure", exposure.experiment_key, exposure.variant_name, exposure.user_id)
+        exposures.task_done()
+
+
+threading.Thread(target=send_exposures, daemon=True).start()
+
+
+def on_exposure(exposure):
+    try:
+        exposures.put_nowait(exposure)
+    except queue.Full:
+        pass  # drop it rather than make get_variant wait
+
+
+client = ExperimentationClient(
+    api_url=os.environ.get("CONTROLVAR_API_URL", "http://localhost:8000"),
+    api_key=os.environ["CONTROLVAR_API_KEY"],
+    on_exposure=on_exposure,
+)
+client.get_variant("checkout_flow", "user-123")
+exposures.join()
+```
+
+It receives an `Exposure`: `experiment_key`, `user_id`, `variant_id` (`None` when the server sends
+none) and `variant_name`. It is not called for a cached answer, a user the experiment did not enrol
+or an experiment that is not running (`assigned` False), a call that fails, or a feature flag. It
+runs in the thread that called `get_assignment` or `get_variant`, before that call returns, so keep
+it quick. If it raises, the answer is unchanged, and the error is logged at ERROR and passed to
+`on_error` with the operation `"exposure"` and `code` `"HOOK_ERROR"`.
+
+Full details: [Exposure hook](https://github.com/Controlvar/controlvar/blob/main/docs/sdk/python.md#exposure-hook).
+
 ## Backend endpoints used
 
 Every request carries `X-API-Key: <key>`, `Content-Type: application/json` and `Accept: application/json`.
 
 | SDK call | Method and path | Body / query | Response used |
 |---|---|---|---|
-| `get_assignment`, `get_variant` | `POST /api/v1/tracking/assign` | `{experiment_key, user_id, context?}` | `{experiment_key, user_id, variant_id, variant_name, is_control, configuration}`; 404 when no experiment has the key, or for a draft with no control variant; an experiment that is not ACTIVE answers its control variant with `assigned: false` |
+| `get_assignment`, `get_variant` | `POST /api/v1/tracking/assign` | `{experiment_key, user_id, context?}` | `{experiment_key, user_id, variant_id, variant_name, is_control, configuration, assigned, reason}`; 404 when no experiment has the key, or for a draft with no control variant; an experiment that is not ACTIVE answers its control variant with `assigned: false` |
 | `get_feature_flag`, `is_feature_enabled` | `GET /api/v1/feature-flags/evaluate/{flag_key}?user_id=…&context=<url-encoded JSON>` | `context` = `user_attributes` (omitted when empty) | `{key, enabled, config, reason}`; off with `reason: "inactive"` when the flag exists but is not ACTIVE; 404 only for an unknown key |
 | `get_all_flags` | `GET /api/v1/feature-flags/user/{user_id}?context=<url-encoded JSON>` | `context` = `user_attributes` (omitted when empty) | `{"<flag_key>": bool, …}` |
-| `track` with a key | `POST /api/v1/tracking/track` | `{event_type, event_name, user_id, experiment_key?, feature_flag_key?, value?, metadata?, timestamp?}` | ignored |
+| `track` with a key | `POST /api/v1/tracking/track` | `{event_type, event_name, user_id, experiment_key?, feature_flag_key?, value?, metadata?, timestamp?, event_id?}` | ignored |
 | `track` without keys | `POST /api/v1/tracking/batch`, one entry per experiment and flag it reaches; with none, `POST /api/v1/tracking/track` | `{events: [<track body>, …]}` (≤ 100 per request); with none, the track body with no key | ignored |
 | `track_batch` | `POST /api/v1/tracking/batch` | `{events: [<track body>, …]}` (≤ 100 per request) | `{success_count, failure_count, errors}` |
 | `get_assignments` | `GET /api/v1/tracking/assignments/{user_id}?active_only=true` | — | list of dicts |
@@ -168,7 +271,7 @@ CONTROLVAR_API_KEY=<key> python sdk/python/examples/contract_smoke.py
 It prints:
 
 ```text
-{"sdk":"python","assign":{"variant_name":"treatment","is_control":false,"sticky":true},"flag":{"enabled":true},"track":{"ok":true},"fanout":{"ok":true}}
+{"sdk":"python","assign":{"variant_name":"treatment","is_control":false,"sticky":true},"flag":{"enabled":true},"track":{"ok":true},"fanout":{"ok":true},"event_id":{"user_id":"smoke-<uuid>","event_name":"contract_dedup_<uuid>","id":"contract-<uuid>","sends":2},"exposure":{"calls":1,"payload":{"experiment_key":"sdk_contract_ab","variant_name":"treatment","variant_id":"<id>","user_id":"smoke-<uuid>"}}}
 ```
 
 Env: `CONTROLVAR_API_URL` (default `http://localhost:8000`), `CONTROLVAR_API_KEY` (required),

{controlvar-0.2.0 → controlvar-0.3.0}/controlvar/__init__.py

@@ -15,7 +15,13 @@ from .client import BATCH_LIMIT, ExperimentationClient
 from .hashing import consistent_hash, md5_hex
 from .local import LocalEvaluationStatus, ReadyResult
 from .transport import Response, Transport, TransportError, UrllibTransport
-from .types import Assignment, BatchResult, ExperimentationError, FlagEvaluation
+from .types import (
+    Assignment,
+    BatchResult,
+    ExperimentationError,
+    Exposure,
+    FlagEvaluation,
+)
 from .version import __version__
 
 __all__ = [
@@ -24,6 +30,7 @@ __all__ = [
     "BatchResult",
     "ExperimentationClient",
     "ExperimentationError",
+    "Exposure",
     "FlagEvaluation",
     "LocalEvaluationStatus",
     "ReadyResult",

{controlvar-0.2.0 → controlvar-0.3.0}/controlvar/attribution.py

@@ -41,7 +41,10 @@ class AttributedKeys:
     patches it moves this record and the cache together.
     """
 
-    def __init__(self) -> None:
+    def __init__(self, cache_ttl_seconds: float = 0) -> None:
+        # 24 hours, or the cache lifetime when that is longer, so a cached answer never
+        # outlives the record that tags its events (#1423).
+        self._horizon = max(ATTRIBUTION_HORIZON_SECONDS, cache_ttl_seconds)
         self._lock = threading.Lock()
         self._users: "OrderedDict[str, Tuple[_Answers, _Answers]]" = OrderedDict()
 
@@ -72,7 +75,7 @@ class AttributedKeys:
             if answers is None:
                 return [], []
             now = cache._now()
-            experiments, flags = _live(answers[0], now), _live(answers[1], now)
+            experiments, flags = _live(answers[0], now, self._horizon), _live(answers[1], now, self._horizon)
             if not answers[0] and not answers[1]:
                 del self._users[user_id]
             return experiments, flags
@@ -95,10 +98,10 @@ class AttributedKeys:
                 self._users.popitem(last=False)
 
 
-def _live(answers: _Answers, now: float) -> List[str]:
+def _live(answers: _Answers, now: float, horizon: float) -> List[str]:
     out: List[str] = []
     for key, (answered_at, reason) in list(answers.items()):
-        if now - answered_at > ATTRIBUTION_HORIZON_SECONDS:
+        if now - answered_at > horizon:
             del answers[key]
         elif reason not in LIFECYCLE_REASONS:
             out.append(key)

{controlvar-0.2.0 → controlvar-0.3.0}/controlvar/cache.py

@@ -38,6 +38,20 @@ class UserKeyCache(Generic[T]):
         with self._lock:
             self._users.setdefault(user_id, {})[key] = (_now() + self._ttl, value)
 
+    def set_new(self, user_id: str, key: str, value: T) -> bool:
+        """Store ``value`` as :meth:`set` does, and say whether it is new: ``True`` when the slot
+        held no unexpired value (it was empty or expired), ``False`` when it replaced a live one.
+
+        Checked and stored under the one lock: of two threads storing the same user and key, the
+        second finds the first one's value, and sees ``False`` while that value is unexpired."""
+        with self._lock:
+            by_key = self._users.setdefault(user_id, {})
+            now = _now()
+            entry = by_key.get(key)
+            new = entry is None or now >= entry[0]
+            by_key[key] = (now + self._ttl, value)
+            return new
+
     def entries(self, user_id: str) -> List[Tuple[str, T]]:
         """All live (unexpired) entries for a user, in insertion order."""
         with self._lock: