controlvar 0.0.0__tar.gz → 0.2.0__tar.gz

controlvar-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 The Controlvar authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

controlvar-0.2.0/PKG-INFO

@@ -0,0 +1,231 @@
+Metadata-Version: 2.4
+Name: controlvar
+Version: 0.2.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
+Project-URL: Repository, https://github.com/Controlvar/controlvar
+Project-URL: Issues, https://github.com/Controlvar/controlvar/issues
+Keywords: experimentation,a/b-testing,feature-flags,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+# controlvar (Python)
+
+**Beta.** This is a 0.x release: pin the exact version you test against.
+
+Synchronous, dependency-free Python client for the Controlvar public API.
+Experiment assignment and feature-flag evaluation are decided **by the server** by default (sticky
+per user + experiment); the SDK caches the answers per user + key. Server-side code can opt in to
+**local evaluation** (`evaluation="local"`, beta): flags are answered in-process from the server's
+ruleset, with the server's answers, and anything that cannot be answered exactly goes to the
+server. See [`docs/sdk/local-evaluation.md`](https://github.com/Controlvar/controlvar/blob/main/docs/sdk/local-evaluation.md).
+
+Requires Python 3.9+. HTTP goes through the standard library (`urllib`), so there is nothing
+else to install.
+
+## 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
+beta release. It installs and imports as `controlvar`.
+
+```bash
+pip install controlvar==0.2.0
+```
+
+To work on the SDK itself, install it from the root of a clone of this repository instead:
+
+```bash
+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`.
+
+## Quick start
+
+Set `CONTROLVAR_API_KEY` to an API key, then run the block as it is; the two `print` calls
+stand for your own code.
+
+```python
+import os
+from controlvar import ExperimentationClient, ExperimentationError
+
+client = ExperimentationClient(
+    api_url=os.environ.get("CONTROLVAR_API_URL", "http://localhost:8000"),  # origin only
+    api_key=os.environ["CONTROLVAR_API_KEY"],
+)
+
+# Experiments — sticky assignment made by the server (POST /api/v1/tracking/assign)
+variant = client.get_variant("checkout_flow", user_id="user-123", user_attributes={"plan": "pro"})
+if variant == "treatment":
+    print("show the new checkout")   # your own code
+
+assignment = client.get_assignment("checkout_flow", "user-123")   # raises on failure
+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)
+flags = client.get_all_flags("user-123", {"plan": "pro"})          # {"new_search": True, ...}
+
+# Tracking (never raises)
+client.track("user-123", "purchase", event_value=49.99, experiment_key="checkout_flow")
+client.track("user-123", "page_view", properties={"page": "/"})   # no key: fanned out, see below
+```
+
+Constructor: `ExperimentationClient(api_url, api_key, timeout_seconds=5.0, cache_ttl_seconds=300,
+default_variant="control", transport=None)`. Instances are thread-safe.
+
+## API
+
+| Method | Returns | Failure behaviour |
+|---|---|---|
+| `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"`) |
+| `is_feature_enabled(flag_key, user_id, user_attributes=None)` | `bool` | returns `False` |
+| `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_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` |
+| `cached_assignments(user_id)` / `cached_flags(user_id)` | cached, unexpired entries | — |
+| `clear_cache()` | — (keeps the keys a key-less `track` is sent to) | — |
+| `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).
+
+`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
+(`country` also matches `user.country`; nested dicts flatten to dotted keys such as `app.version`).
+`FlagEvaluation.reason` (`targeting_rule` / `rollout` / `inactive` / `error`, or `None`) says why
+the server decided. Caches are keyed by user + key only — call `clear_cache()` after changing a
+user's attributes.
+
+`report_error` returns `True` when the server stored the report. A stored report counts toward the
+flag's error rate and automatic rollback only when the client's key has the `sdk:ruleset` scope and
+was created by a user who can change feature flags; the flag's safety check shows the others as
+`uncounted_error_count`.
+
+### Enrolment: `assigned` and `reason`
+
+An `Assignment` also carries `assigned` and `reason`. `assigned is False` means the server did not
+enrol the user (`reason` is `"holdout"`, `"mutual_exclusion"` or `"targeting"`) and returned the
+control variant so you render the default experience; no exposure was recorded. **When you export
+exposures to a warehouse, exclude assignments with `assigned is False`**: the user was not enrolled,
+and `reason` says why. A server that predates the fields sends neither, so `assigned` is `None`
+(never `False`). Decide deliberately how to treat those rows rather than dropping them with an
+`assigned is True` filter.
+
+An experiment that is not ACTIVE answers every user with its control variant, `assigned` False and
+`reason` set to its status (`"draft"`, `"paused"`, `"completed"` or `"archived"`).
+
+## Tracking fan-out rule
+
+- **with** `experiment_key` and/or `feature_flag_key` → one `POST /api/v1/tracking/track`;
+- **without** a key → one `POST /api/v1/tracking/batch` (chunks of 100) containing one entry per
+  experiment (`experiment_key`) and one per flag (`feature_flag_key`) this client answered for the
+  user in the last 24 hours, cached or not, except an experiment whose latest answer has `reason`
+  `"draft"`, `"paused"`, `"completed"` or `"archived"`;
+- nothing to attribute it to → one `POST /api/v1/tracking/track` with no key, stored as history (it
+  counts in holdout results and as CUPED history, never in an experiment's results);
+- `track` returns `True` when the event was sent and the server answered 2xx, `False` otherwise.
+
+The keys live in this client's memory, for up to 10,000 users; `clear_cache()` keeps them, and
+another process does not have them. In a server, pass `experiment_key` on conversions.
+
+`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.
+
+## 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_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` 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 |
+
+## Contract smoke
+
+```bash
+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}}
+```
+
+Env: `CONTROLVAR_API_URL` (default `http://localhost:8000`), `CONTROLVAR_API_KEY` (required),
+`CONTRACT_EXPERIMENT_KEY` (default `sdk_contract_ab`), `CONTRACT_FLAG_KEY` (default `sdk_contract_flag`),
+`CONTRACT_USER_ID` (default random `smoke-<uuid>`).
+
+CI runs this SDK's contract smoke against a real API: `python` is in the `sdks:` list of the
+SDK Live Contract job in [pr-qa-gate.yml](https://github.com/Controlvar/controlvar/blob/main/.github/workflows/pr-qa-gate.yml). Its fixtures,
+`sdk_contract_ab` and `sdk_contract_flag`, are seeded with `backend/scripts/seed_sdk_contract.py`;
+run it with `python tests/sdk-contract/live/run_live_contract.py --sdk python --strict`.
+
+## Testing your own code
+
+`controlvar.testing.FakeTransport` records requests and serves canned responses:
+
+```python
+from controlvar import ExperimentationClient
+from controlvar.testing import FakeTransport
+
+transport = FakeTransport().route("GET", "/api/v1/feature-flags/evaluate/new_search",
+                                  json={"key": "new_search", "enabled": True, "config": None})
+client = ExperimentationClient("http://test", "key", transport=transport)
+assert client.is_feature_enabled("new_search", "user-1")
+assert transport.last.query == {"user_id": "user-1"}
+```
+
+## Development
+
+```bash
+source venv/bin/activate
+python -m pytest sdk/python/tests -q -o addopts="" -p no:cacheprovider
+```
+
+- `python -m pytest sdk/python/tests -q -o addopts="" -p no:cacheprovider`: HTTP is faked; CI runs them on Python 3.11

controlvar-0.2.0/README.md

@@ -0,0 +1,205 @@
+# controlvar (Python)
+
+**Beta.** This is a 0.x release: pin the exact version you test against.
+
+Synchronous, dependency-free Python client for the Controlvar public API.
+Experiment assignment and feature-flag evaluation are decided **by the server** by default (sticky
+per user + experiment); the SDK caches the answers per user + key. Server-side code can opt in to
+**local evaluation** (`evaluation="local"`, beta): flags are answered in-process from the server's
+ruleset, with the server's answers, and anything that cannot be answered exactly goes to the
+server. See [`docs/sdk/local-evaluation.md`](https://github.com/Controlvar/controlvar/blob/main/docs/sdk/local-evaluation.md).
+
+Requires Python 3.9+. HTTP goes through the standard library (`urllib`), so there is nothing
+else to install.
+
+## 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
+beta release. It installs and imports as `controlvar`.
+
+```bash
+pip install controlvar==0.2.0
+```
+
+To work on the SDK itself, install it from the root of a clone of this repository instead:
+
+```bash
+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`.
+
+## Quick start
+
+Set `CONTROLVAR_API_KEY` to an API key, then run the block as it is; the two `print` calls
+stand for your own code.
+
+```python
+import os
+from controlvar import ExperimentationClient, ExperimentationError
+
+client = ExperimentationClient(
+    api_url=os.environ.get("CONTROLVAR_API_URL", "http://localhost:8000"),  # origin only
+    api_key=os.environ["CONTROLVAR_API_KEY"],
+)
+
+# Experiments — sticky assignment made by the server (POST /api/v1/tracking/assign)
+variant = client.get_variant("checkout_flow", user_id="user-123", user_attributes={"plan": "pro"})
+if variant == "treatment":
+    print("show the new checkout")   # your own code
+
+assignment = client.get_assignment("checkout_flow", "user-123")   # raises on failure
+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)
+flags = client.get_all_flags("user-123", {"plan": "pro"})          # {"new_search": True, ...}
+
+# Tracking (never raises)
+client.track("user-123", "purchase", event_value=49.99, experiment_key="checkout_flow")
+client.track("user-123", "page_view", properties={"page": "/"})   # no key: fanned out, see below
+```
+
+Constructor: `ExperimentationClient(api_url, api_key, timeout_seconds=5.0, cache_ttl_seconds=300,
+default_variant="control", transport=None)`. Instances are thread-safe.
+
+## API
+
+| Method | Returns | Failure behaviour |
+|---|---|---|
+| `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"`) |
+| `is_feature_enabled(flag_key, user_id, user_attributes=None)` | `bool` | returns `False` |
+| `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_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` |
+| `cached_assignments(user_id)` / `cached_flags(user_id)` | cached, unexpired entries | — |
+| `clear_cache()` | — (keeps the keys a key-less `track` is sent to) | — |
+| `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).
+
+`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
+(`country` also matches `user.country`; nested dicts flatten to dotted keys such as `app.version`).
+`FlagEvaluation.reason` (`targeting_rule` / `rollout` / `inactive` / `error`, or `None`) says why
+the server decided. Caches are keyed by user + key only — call `clear_cache()` after changing a
+user's attributes.
+
+`report_error` returns `True` when the server stored the report. A stored report counts toward the
+flag's error rate and automatic rollback only when the client's key has the `sdk:ruleset` scope and
+was created by a user who can change feature flags; the flag's safety check shows the others as
+`uncounted_error_count`.
+
+### Enrolment: `assigned` and `reason`
+
+An `Assignment` also carries `assigned` and `reason`. `assigned is False` means the server did not
+enrol the user (`reason` is `"holdout"`, `"mutual_exclusion"` or `"targeting"`) and returned the
+control variant so you render the default experience; no exposure was recorded. **When you export
+exposures to a warehouse, exclude assignments with `assigned is False`**: the user was not enrolled,
+and `reason` says why. A server that predates the fields sends neither, so `assigned` is `None`
+(never `False`). Decide deliberately how to treat those rows rather than dropping them with an
+`assigned is True` filter.
+
+An experiment that is not ACTIVE answers every user with its control variant, `assigned` False and
+`reason` set to its status (`"draft"`, `"paused"`, `"completed"` or `"archived"`).
+
+## Tracking fan-out rule
+
+- **with** `experiment_key` and/or `feature_flag_key` → one `POST /api/v1/tracking/track`;
+- **without** a key → one `POST /api/v1/tracking/batch` (chunks of 100) containing one entry per
+  experiment (`experiment_key`) and one per flag (`feature_flag_key`) this client answered for the
+  user in the last 24 hours, cached or not, except an experiment whose latest answer has `reason`
+  `"draft"`, `"paused"`, `"completed"` or `"archived"`;
+- nothing to attribute it to → one `POST /api/v1/tracking/track` with no key, stored as history (it
+  counts in holdout results and as CUPED history, never in an experiment's results);
+- `track` returns `True` when the event was sent and the server answered 2xx, `False` otherwise.
+
+The keys live in this client's memory, for up to 10,000 users; `clear_cache()` keeps them, and
+another process does not have them. In a server, pass `experiment_key` on conversions.
+
+`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.
+
+## 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_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` 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 |
+
+## Contract smoke
+
+```bash
+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}}
+```
+
+Env: `CONTROLVAR_API_URL` (default `http://localhost:8000`), `CONTROLVAR_API_KEY` (required),
+`CONTRACT_EXPERIMENT_KEY` (default `sdk_contract_ab`), `CONTRACT_FLAG_KEY` (default `sdk_contract_flag`),
+`CONTRACT_USER_ID` (default random `smoke-<uuid>`).
+
+CI runs this SDK's contract smoke against a real API: `python` is in the `sdks:` list of the
+SDK Live Contract job in [pr-qa-gate.yml](https://github.com/Controlvar/controlvar/blob/main/.github/workflows/pr-qa-gate.yml). Its fixtures,
+`sdk_contract_ab` and `sdk_contract_flag`, are seeded with `backend/scripts/seed_sdk_contract.py`;
+run it with `python tests/sdk-contract/live/run_live_contract.py --sdk python --strict`.
+
+## Testing your own code
+
+`controlvar.testing.FakeTransport` records requests and serves canned responses:
+
+```python
+from controlvar import ExperimentationClient
+from controlvar.testing import FakeTransport
+
+transport = FakeTransport().route("GET", "/api/v1/feature-flags/evaluate/new_search",
+                                  json={"key": "new_search", "enabled": True, "config": None})
+client = ExperimentationClient("http://test", "key", transport=transport)
+assert client.is_feature_enabled("new_search", "user-1")
+assert transport.last.query == {"user_id": "user-1"}
+```
+
+## Development
+
+```bash
+source venv/bin/activate
+python -m pytest sdk/python/tests -q -o addopts="" -p no:cacheprovider
+```
+
+- `python -m pytest sdk/python/tests -q -o addopts="" -p no:cacheprovider`: HTTP is faked; CI runs them on Python 3.11

controlvar-0.2.0/controlvar/__init__.py

@@ -0,0 +1,37 @@
+"""Controlvar Python SDK.
+
+Usage::
+
+    from controlvar import ExperimentationClient
+
+    client = ExperimentationClient("http://localhost:8000", api_key="...")
+    variant = client.get_variant("checkout_flow", user_id="user-123")
+    if client.is_feature_enabled("new_search", "user-123"):
+        ...
+    client.track("user-123", "purchase", event_value=49.99, experiment_key="checkout_flow")
+"""
+
+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 .version import __version__
+
+__all__ = [
+    "BATCH_LIMIT",
+    "Assignment",
+    "BatchResult",
+    "ExperimentationClient",
+    "ExperimentationError",
+    "FlagEvaluation",
+    "LocalEvaluationStatus",
+    "ReadyResult",
+    "Response",
+    "Transport",
+    "TransportError",
+    "UrllibTransport",
+    "__version__",
+    "consistent_hash",
+    "md5_hex",
+]

controlvar-0.2.0/controlvar/attribution.py

@@ -0,0 +1,105 @@
+"""The keys a key-less ``track()`` is sent to, kept apart from the TTL value cache.
+
+Every successful answer (an assignment, ``assigned=False`` included, or a flag
+evaluation, local or from the server) records its key for the user. A key-less
+event goes to each key recorded for its user, so a purchase made after the cache
+entry expired still reaches the experiment the user was answered for.
+``clear_cache()`` does not touch this record: a user's sticky assignments do not
+change when their attributes do.
+"""
+
+from __future__ import annotations
+
+import threading
+from collections import OrderedDict
+from typing import Dict, FrozenSet, List, Optional, Tuple
+
+from . import cache
+
+__all__ = ["ATTRIBUTION_HORIZON_SECONDS", "LIFECYCLE_REASONS", "MAX_ATTRIBUTED_USERS", "AttributedKeys"]
+
+#: Users kept per client instance; the user answered least recently is dropped first.
+MAX_ATTRIBUTED_USERS = 10_000
+
+#: A key is used for this long after its latest successful answer, then dropped.
+ATTRIBUTION_HORIZON_SECONDS = 24 * 60 * 60
+
+#: An experiment whose latest answer gave one of these reasons is not running, so a
+#: key-less event is not sent to it. Other reasons (``holdout``,
+#: ``mutual_exclusion``, ``targeting``) are kept: holdout results count those
+#: users' events.
+LIFECYCLE_REASONS: FrozenSet[str] = frozenset({"draft", "paused", "completed", "archived"})
+
+# key -> (answered_at, reason); dict order is first-answer order.
+_Answers = Dict[str, Tuple[float, Optional[str]]]
+
+
+class AttributedKeys:
+    """``user_id -> (experiment answers, flag answers)``, least recently answered user first.
+
+    Time is ``controlvar.cache._now`` (monotonic), read at call time, so a test that
+    patches it moves this record and the cache together.
+    """
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._users: "OrderedDict[str, Tuple[_Answers, _Answers]]" = OrderedDict()
+
+    def record_experiment(self, user_id: str, experiment_key: str, reason: Optional[str] = None) -> None:
+        self._record(user_id, experiment_key, reason, 0)
+
+    def record_flag(self, user_id: str, flag_key: str) -> None:
+        self._record(user_id, flag_key, None, 1)
+
+    def forget_experiment(self, user_id: str, experiment_key: str) -> None:
+        """Drop one experiment's key for the user: the server answered its assignment 404, so
+        a key-less event must not reach it (a server that answers 404 for an experiment that is
+        not running would otherwise credit the user's stored arm while the user is shown
+        control)."""
+        with self._lock:
+            answers = self._users.get(user_id)
+            if answers is None:
+                return
+            answers[0].pop(experiment_key, None)
+            if not answers[0] and not answers[1]:
+                del self._users[user_id]
+
+    def keys(self, user_id: str) -> Tuple[List[str], List[str]]:
+        """The user's experiment keys and flag keys within the horizon, each in the
+        order they were first answered. Keys past the horizon are dropped here."""
+        with self._lock:
+            answers = self._users.get(user_id)
+            if answers is None:
+                return [], []
+            now = cache._now()
+            experiments, flags = _live(answers[0], now), _live(answers[1], now)
+            if not answers[0] and not answers[1]:
+                del self._users[user_id]
+            return experiments, flags
+
+    def __len__(self) -> int:
+        with self._lock:
+            return len(self._users)
+
+    def _record(self, user_id: str, key: str, reason: Optional[str], kind: int) -> None:
+        with self._lock:
+            answers = self._users.get(user_id)
+            if answers is None:
+                answers = ({}, {})
+                self._users[user_id] = answers
+            else:
+                self._users.move_to_end(user_id)  # now the most recently answered user
+            # Assigning an existing key keeps its place: the order stays first-answer order.
+            answers[kind][key] = (cache._now(), reason)
+            while len(self._users) > MAX_ATTRIBUTED_USERS:
+                self._users.popitem(last=False)
+
+
+def _live(answers: _Answers, now: float) -> List[str]:
+    out: List[str] = []
+    for key, (answered_at, reason) in list(answers.items()):
+        if now - answered_at > ATTRIBUTION_HORIZON_SECONDS:
+            del answers[key]
+        elif reason not in LIFECYCLE_REASONS:
+            out.append(key)
+    return out

controlvar-0.2.0/controlvar/cache.py

@@ -0,0 +1,58 @@
+"""Thread-safe per-user, per-key TTL cache. Only successful results are ever stored."""
+
+from __future__ import annotations
+
+import threading
+import time
+from typing import Dict, Generic, List, Optional, Tuple, TypeVar
+
+T = TypeVar("T")
+
+# Indirection so tests can patch ``controlvar.cache._now``.
+_now = time.monotonic
+
+
+class UserKeyCache(Generic[T]):
+    """``user_id -> key -> (expires_at, value)`` guarded by a single lock."""
+
+    def __init__(self, ttl_seconds: float) -> None:
+        self._ttl = float(ttl_seconds)
+        self._lock = threading.Lock()
+        self._users: Dict[str, Dict[str, Tuple[float, T]]] = {}
+
+    def get(self, user_id: str, key: str) -> Optional[T]:
+        with self._lock:
+            by_key = self._users.get(user_id)
+            if not by_key:
+                return None
+            entry = by_key.get(key)
+            if entry is None:
+                return None
+            expires_at, value = entry
+            if _now() >= expires_at:
+                del by_key[key]
+                return None
+            return value
+
+    def set(self, user_id: str, key: str, value: T) -> None:
+        with self._lock:
+            self._users.setdefault(user_id, {})[key] = (_now() + self._ttl, value)
+
+    def entries(self, user_id: str) -> List[Tuple[str, T]]:
+        """All live (unexpired) entries for a user, in insertion order."""
+        with self._lock:
+            by_key = self._users.get(user_id)
+            if not by_key:
+                return []
+            now = _now()
+            live: List[Tuple[str, T]] = []
+            for key, (expires_at, value) in list(by_key.items()):
+                if now >= expires_at:
+                    del by_key[key]
+                else:
+                    live.append((key, value))
+            return live
+
+    def clear(self) -> None:
+        with self._lock:
+            self._users.clear()