switchbox-flags 0.4.0__tar.gz → 0.6.0__tar.gz

{switchbox_flags-0.4.0 → switchbox_flags-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: switchbox-flags
-Version: 0.4.0
+Version: 0.6.0
 Summary: Feature flag SDK with zero dependencies
 Project-URL: Homepage, https://github.com/ignat14/switchbox-sdk-python
 Project-URL: Repository, https://github.com/ignat14/switchbox-sdk-python
@@ -155,6 +155,7 @@ client = Switchbox(
     sdk_key="your-sdk-key-from-dashboard",  # required — get from Environments tab
     poll_interval=60,                       # seconds between polls (default: 30)
     on_error=lambda e: logger.warning(e),   # called on fetch errors (default: None)
+    block_on_init=True,                     # block on the first fetch (default: True)
 )
 ```
 
@@ -163,9 +164,32 @@ client = Switchbox(
 | `sdk_key`       | `str`                          | —       | SDK key from the environment in the dashboard  |
 | `poll_interval` | `int`                          | `30`    | Seconds between background config refreshes    |
 | `on_error`      | `Callable[[Exception], None]`  | `None`  | Callback invoked when a fetch or parse fails   |
+| `timeout`       | `int`                          | `10`    | Per-fetch HTTP timeout in seconds              |
+| `block_on_init` | `bool`                         | `True`  | Fetch the first config synchronously (see below) |
 
 The SDK builds the CDN URL automatically from the SDK key. You can override with `cdn_base_url` if self-hosting.
 
+### Blocking vs. non-blocking startup
+
+By default (`block_on_init=True`) the constructor performs the **first fetch synchronously**, so
+`client.ready` is `True` the moment `Switchbox(...)` returns — your first flag check already sees live
+config. The trade-off: construction blocks up to `timeout` seconds if the CDN is slow or unreachable,
+which can stall an app's startup path.
+
+Set `block_on_init=False` to return immediately and fetch in the background instead. The client starts
+**not ready** (flag checks fall back to your supplied defaults) and becomes ready as soon as the first
+background fetch lands. Poll `client.ready` if you need to know when live config is available:
+
+```python
+client = Switchbox(sdk_key="...", block_on_init=False)
+# returns instantly, even if the CDN is down — checks use defaults until ready
+if client.enabled("new_checkout", user={"user_id": "42"}):
+    ...
+```
+
+(The JavaScript SDK makes the same choice explicit at the API surface: `await Switchbox.create(...)`
+blocks on the first fetch, while `new Switchbox(...)` without awaiting `init()` does not.)
+
 ## How It Works
 
 ```
@@ -198,9 +222,12 @@ The API server is only in the write path. All read traffic goes to the CDN.
 
 ## API Reference
 
-### `Switchbox(sdk_key, poll_interval=30, on_error=None)`
+### `Switchbox(sdk_key, poll_interval=30, on_error=None, timeout=10, block_on_init=True)`
 
-Creates a new client. Performs an initial synchronous fetch on creation, then starts background polling.
+Creates a new client and starts background polling. With `block_on_init=True` (default) it performs an
+initial **synchronous** fetch on creation (the client is `ready` on return); with `block_on_init=False`
+the first fetch happens in the background and the constructor returns immediately. See
+[Blocking vs. non-blocking startup](#blocking-vs-non-blocking-startup).
 
 ### `client.enabled(flag_key, user=None) -> bool`
 

{switchbox_flags-0.4.0 → switchbox_flags-0.6.0}/README.md

@@ -129,6 +129,7 @@ client = Switchbox(
     sdk_key="your-sdk-key-from-dashboard",  # required — get from Environments tab
     poll_interval=60,                       # seconds between polls (default: 30)
     on_error=lambda e: logger.warning(e),   # called on fetch errors (default: None)
+    block_on_init=True,                     # block on the first fetch (default: True)
 )
 ```
 
@@ -137,9 +138,32 @@ client = Switchbox(
 | `sdk_key`       | `str`                          | —       | SDK key from the environment in the dashboard  |
 | `poll_interval` | `int`                          | `30`    | Seconds between background config refreshes    |
 | `on_error`      | `Callable[[Exception], None]`  | `None`  | Callback invoked when a fetch or parse fails   |
+| `timeout`       | `int`                          | `10`    | Per-fetch HTTP timeout in seconds              |
+| `block_on_init` | `bool`                         | `True`  | Fetch the first config synchronously (see below) |
 
 The SDK builds the CDN URL automatically from the SDK key. You can override with `cdn_base_url` if self-hosting.
 
+### Blocking vs. non-blocking startup
+
+By default (`block_on_init=True`) the constructor performs the **first fetch synchronously**, so
+`client.ready` is `True` the moment `Switchbox(...)` returns — your first flag check already sees live
+config. The trade-off: construction blocks up to `timeout` seconds if the CDN is slow or unreachable,
+which can stall an app's startup path.
+
+Set `block_on_init=False` to return immediately and fetch in the background instead. The client starts
+**not ready** (flag checks fall back to your supplied defaults) and becomes ready as soon as the first
+background fetch lands. Poll `client.ready` if you need to know when live config is available:
+
+```python
+client = Switchbox(sdk_key="...", block_on_init=False)
+# returns instantly, even if the CDN is down — checks use defaults until ready
+if client.enabled("new_checkout", user={"user_id": "42"}):
+    ...
+```
+
+(The JavaScript SDK makes the same choice explicit at the API surface: `await Switchbox.create(...)`
+blocks on the first fetch, while `new Switchbox(...)` without awaiting `init()` does not.)
+
 ## How It Works
 
 ```
@@ -172,9 +196,12 @@ The API server is only in the write path. All read traffic goes to the CDN.
 
 ## API Reference
 
-### `Switchbox(sdk_key, poll_interval=30, on_error=None)`
+### `Switchbox(sdk_key, poll_interval=30, on_error=None, timeout=10, block_on_init=True)`
 
-Creates a new client. Performs an initial synchronous fetch on creation, then starts background polling.
+Creates a new client and starts background polling. With `block_on_init=True` (default) it performs an
+initial **synchronous** fetch on creation (the client is `ready` on return); with `block_on_init=False`
+the first fetch happens in the background and the constructor returns immediately. See
+[Blocking vs. non-blocking startup](#blocking-vs-non-blocking-startup).
 
 ### `client.enabled(flag_key, user=None) -> bool`
 

{switchbox_flags-0.4.0 → switchbox_flags-0.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "switchbox-flags"
-version = "0.4.0"
+version = "0.6.0"
 description = "Feature flag SDK with zero dependencies"
 readme = "README.md"
 license = "MIT"

{switchbox_flags-0.4.0 → switchbox_flags-0.6.0}/switchbox/__init__.py

@@ -1,5 +1,5 @@
 from switchbox.client import Switchbox
 from switchbox.exceptions import SwitchboxError
 
-__version__ = "0.4.0"
+__version__ = "0.5.0"
 __all__ = ["Switchbox", "SwitchboxError"]

{switchbox_flags-0.4.0 → switchbox_flags-0.6.0}/switchbox/client.py

@@ -35,12 +35,17 @@ class Switchbox:
         on_error: Callable[[Exception], None] | None = None,
         timeout: int = 10,
         cdn_base_url: str | None = None,
+        block_on_init: bool = True,
     ) -> None:
         base = cdn_base_url or CDN_BASE_URL
         cdn_url = f"{base}/{sdk_key}/flags.json"
         self._cache = FlagCache()
         self._sync = SyncWorker(cdn_url, self._cache, poll_interval, on_error, timeout=timeout)
-        self._sync.start()
+        # block_on_init=True (default): the constructor performs the first fetch
+        # synchronously, so the client is `ready` on return. Set False to fetch in
+        # the background instead — the constructor returns immediately and never
+        # blocks on a slow/unreachable CDN (SEC-9). See `ready`.
+        self._sync.start(block=block_on_init)
 
     @property
     def ready(self) -> bool:

{switchbox_flags-0.4.0 → switchbox_flags-0.6.0}/switchbox/evaluator.py

@@ -88,10 +88,16 @@ def evaluate(flag: Flag, user_context: dict | None = None) -> bool | str | int |
 
 
 def _enabled_value(flag: Flag) -> bool | str | int | Any:
-    """Return the appropriate 'enabled' value based on flag type."""
+    """The value served to matched / in-rollout users.
+
+    Boolean flags serve ``True``. Non-boolean flags serve ``enabled_value``
+    (variations, ADR-017), falling back to ``default_value`` when it's unset —
+    so a config without ``enabled_value`` behaves exactly as before. Fallback is
+    at evaluation time (not parse time) so directly-constructed Flags work too,
+    matching the JS SDK's ``?? default_value``."""
     if flag.flag_type == "boolean":
         return True
-    return flag.default_value
+    return flag.enabled_value if flag.enabled_value is not None else flag.default_value
 
 
 def _to_groups(rules: list) -> list[RuleGroup]:

{switchbox_flags-0.4.0 → switchbox_flags-0.6.0}/switchbox/models.py

@@ -29,6 +29,10 @@ class Flag:
     rollout_pct: int
     flag_type: str  # boolean | string | number | json
     default_value: Any
+    # The "on"/matched value for non-boolean flags (variations, ADR-017). None
+    # means "unset" — the evaluator falls back to default_value, so configs
+    # without this key behave exactly as before. Boolean flags ignore it.
+    enabled_value: Any = None
     rules: list[RuleGroup] = field(default_factory=list)
 
 
@@ -62,6 +66,7 @@ class FlagConfig:
                 rollout_pct=flag_data.get("rollout_pct", 0),
                 flag_type=flag_data.get("flag_type", "boolean"),
                 default_value=flag_data.get("default_value"),
+                enabled_value=flag_data.get("enabled_value"),
                 rules=rules,
             )
         return cls(version=data.get("version", ""), flags=flags)

{switchbox_flags-0.4.0 → switchbox_flags-0.6.0}/switchbox/sync.py

@@ -31,12 +31,30 @@ class SyncWorker:
         self._stop_event = threading.Event()
         self._thread: threading.Thread | None = None
 
-    def start(self) -> None:
-        """Fetch configs synchronously first, then start background polling."""
-        # Initial synchronous fetch — block until we have configs
-        self._poll()
+    def start(self, block: bool = True) -> None:
+        """Start polling. Fetch the first config, then poll in the background.
 
-        self._thread = threading.Thread(target=self._run, daemon=True)
+        ``block=True`` (default): fetch synchronously before returning, so the
+        client is ``ready`` the moment construction completes (at the cost of
+        blocking up to ``timeout`` if the CDN is slow/unreachable).
+
+        ``block=False`` (SEC-9): return immediately and fetch the first config on
+        the background thread, so a slow CDN never stalls app startup. The client
+        starts not-ready; poll ``client.ready`` (or rely on flag defaults) until
+        the first fetch lands.
+        """
+        if block:
+            # Initial synchronous fetch — block until we have configs.
+            self._poll()
+            poll_immediately = False
+        else:
+            # Defer the first fetch onto the background thread so __init__ returns
+            # right away rather than waiting on the network.
+            poll_immediately = True
+
+        self._thread = threading.Thread(
+            target=self._run, args=(poll_immediately,), daemon=True
+        )
         self._thread.start()
 
     def stop(self) -> None:
@@ -45,8 +63,18 @@ class SyncWorker:
         if self._thread is not None:
             self._thread.join(timeout=5)
 
-    def _run(self) -> None:
-        """Main loop for the background thread."""
+    def _run(self, poll_immediately: bool = False) -> None:
+        """Main loop for the background thread.
+
+        ``poll_immediately`` does one fetch before the first interval wait — used
+        by non-blocking start so the config still arrives ASAP rather than after a
+        full poll interval.
+        """
+        if poll_immediately:
+            try:
+                self._poll()
+            except Exception as exc:
+                logger.warning("Unexpected error in initial sync: %s", exc)
         while not self._stop_event.wait(timeout=self._interval):
             try:
                 self._poll()
@@ -58,7 +86,7 @@ class SyncWorker:
         try:
             req = urllib.request.Request(
                 self._cdn_url,
-                headers={"User-Agent": "switchbox-python/0.3.0"},
+                headers={"User-Agent": "switchbox-python/0.6.0"},
             )
             with urllib.request.urlopen(req, timeout=self._timeout) as resp:
                 data = json.loads(resp.read().decode("utf-8"))

switchbox_flags-0.6.0/tests/fixtures/cdn-json/defaults.json

@@ -0,0 +1,8 @@
+{
+  "version": "2026-01-01T00:00:00+00:00",
+  "flags": {
+    "minimal": {
+      "enabled": true
+    }
+  }
+}

switchbox_flags-0.6.0/tests/fixtures/cdn-json/empty.json

@@ -0,0 +1,4 @@
+{
+  "version": "2026-01-01T00:00:00+00:00",
+  "flags": {}
+}

switchbox_flags-0.6.0/tests/fixtures/cdn-json/full_config.json

@@ -0,0 +1,133 @@
+{
+  "flags": {
+    "all_operators": {
+      "default_value": false,
+      "enabled": true,
+      "flag_type": "boolean",
+      "rollout_pct": 0,
+      "rules": [
+        {
+          "conditions": [
+            {
+              "attribute": "email",
+              "operator": "ends_with",
+              "value": "@acme.com"
+            },
+            {
+              "attribute": "plan",
+              "operator": "equals",
+              "value": "pro"
+            }
+          ]
+        },
+        {
+          "conditions": [
+            {
+              "attribute": "age",
+              "operator": "gt",
+              "value": 18
+            },
+            {
+              "attribute": "age",
+              "operator": "lt",
+              "value": 65
+            }
+          ]
+        },
+        {
+          "conditions": [
+            {
+              "attribute": "country",
+              "operator": "in_list",
+              "value": [
+                "US",
+                "CA",
+                "GB"
+              ]
+            },
+            {
+              "attribute": "name",
+              "operator": "contains",
+              "value": "a"
+            },
+            {
+              "attribute": "role",
+              "operator": "not_equals",
+              "value": "guest"
+            }
+          ]
+        }
+      ]
+    },
+    "bool_off": {
+      "default_value": false,
+      "enabled": false,
+      "flag_type": "boolean",
+      "rollout_pct": 100,
+      "rules": []
+    },
+    "bool_on": {
+      "default_value": false,
+      "enabled": true,
+      "flag_type": "boolean",
+      "rollout_pct": 100,
+      "rules": []
+    },
+    "json_variant": {
+      "default_value": {
+        "theme": "light"
+      },
+      "enabled": true,
+      "enabled_value": {
+        "theme": "dark"
+      },
+      "flag_type": "json",
+      "rollout_pct": 100,
+      "rules": []
+    },
+    "number_rollout": {
+      "default_value": 0,
+      "enabled": true,
+      "enabled_value": 42,
+      "flag_type": "number",
+      "rollout_pct": 25,
+      "rules": []
+    },
+    "segment_flag": {
+      "default_value": false,
+      "enabled": true,
+      "flag_type": "boolean",
+      "rollout_pct": 0,
+      "rules": [
+        {
+          "conditions": [
+            {
+              "attribute": "plan",
+              "operator": "equals",
+              "value": "enterprise"
+            }
+          ]
+        }
+      ]
+    },
+    "string_ab": {
+      "default_value": "control",
+      "enabled": true,
+      "enabled_value": "treatment",
+      "flag_type": "string",
+      "rollout_pct": 0,
+      "rules": [
+        {
+          "conditions": [
+            {
+              "attribute": "country",
+              "operator": "equals",
+              "value": "US"
+            }
+          ]
+        }
+      ]
+    }
+  },
+  "version": "2026-01-01T00:00:00+00:00"
+}

switchbox_flags-0.6.0/tests/fixtures/cdn-json/legacy_flat_rules.json

@@ -0,0 +1,14 @@
+{
+  "version": "2026-01-01T00:00:00+00:00",
+  "flags": {
+    "legacy": {
+      "enabled": true,
+      "rollout_pct": 100,
+      "flag_type": "boolean",
+      "default_value": false,
+      "rules": [
+        { "attribute": "country", "operator": "equals", "value": "US" }
+      ]
+    }
+  }
+}

switchbox_flags-0.6.0/tests/fixtures/cdn-json/unknown_fields.json

@@ -0,0 +1,15 @@
+{
+  "version": "2026-01-01T00:00:00+00:00",
+  "future_top_level_field": "must be ignored by every SDK",
+  "flags": {
+    "fwd_compat": {
+      "enabled": true,
+      "rollout_pct": 100,
+      "flag_type": "boolean",
+      "default_value": false,
+      "rules": [],
+      "some_future_field": { "nested": true },
+      "another_unknown": 123
+    }
+  }
+}

{switchbox_flags-0.4.0/tests → switchbox_flags-0.6.0/tests/fixtures/parity}/parity_vectors.json

@@ -1,5 +1,5 @@
 {
-  "_comment": "SEC-4 cross-SDK parity vectors. This file MUST be byte-identical to switchbox-sdk-js/packages/core/tests/parity_vectors.json — it is duplicated into each repo because each SDK is built/tested by its own CI. Canonical semantics are JS-style: lowercase booleans (String(true)='true'), parseFloat-style prefix numeric parsing, null coerces to 'null', user_id resolved with ??-style null-only fallback, and a user context lacking a usable id serves only 100% rollouts (ADR-008). See DECISIONS.md ADR-013. When you change one copy, change the other and run both suites.",
+  "_comment": "SEC-4 cross-SDK parity vectors (evaluation half of the parity story; the format half is fixtures/cdn-json/). CANONICAL SOURCE: fixtures/parity/parity_vectors.json — distributed into each SDK repo's tests/fixtures/parity/ by `python3 fixtures/sync.py` (do NOT hand-edit a synced copy; edit the canonical and re-sync). Both SDK suites run it (test_parity_vectors.py, parity.test.ts). Sections: rule_match (single-condition coercion/operators), evaluate (full evaluate path incl. rollout-bucket boundaries), rollout_bucket (sha256(user_id:flag_key)%100 — pins the hash itself across languages). Canonical semantics are JS-style: lowercase booleans (String(true)='true'), parseFloat-style prefix numeric parsing, null coerces to 'null', user_id resolved with ??-style null-only fallback, and a user context lacking a usable id serves only 100% rollouts (ADR-008). See DECISIONS.md ADR-013 (coercion) + ADR-024 (shared-fixture mechanism).",
   "rule_match": [
     {"name": "boolean true matches lowercase 'true'", "rule": {"attribute": "is_beta", "operator": "equals", "value": "true"}, "context": {"is_beta": true}, "expected": true},
     {"name": "boolean false matches lowercase 'false'", "rule": {"attribute": "is_beta", "operator": "equals", "value": "false"}, "context": {"is_beta": false}, "expected": true},
@@ -34,6 +34,23 @@
     {"name": "DNF: second group matches (OR across groups) -> enabled", "flag_key": "f", "flag": {"enabled": true, "rollout_pct": 0, "flag_type": "boolean", "default_value": false, "rules": [{"conditions": [{"attribute": "country", "operator": "equals", "value": "US"}]}, {"conditions": [{"attribute": "plan", "operator": "equals", "value": "ent"}]}]}, "user": {"plan": "ent"}, "expected": true},
     {"name": "DNF: no group matches (OR across groups) -> default", "flag_key": "f", "flag": {"enabled": true, "rollout_pct": 0, "flag_type": "boolean", "default_value": false, "rules": [{"conditions": [{"attribute": "country", "operator": "equals", "value": "US"}]}, {"conditions": [{"attribute": "plan", "operator": "equals", "value": "ent"}]}]}, "user": {"plan": "free", "country": "EU"}, "expected": false},
     {"name": "DNF: empty-conditions group never matches -> default", "flag_key": "f", "flag": {"enabled": true, "rollout_pct": 0, "flag_type": "boolean", "default_value": false, "rules": [{"conditions": []}]}, "user": {"any": "thing"}, "expected": false},
-    {"name": "DNF back-compat: legacy flat rule still matches -> enabled", "flag_key": "f", "flag": {"enabled": true, "rollout_pct": 0, "flag_type": "boolean", "default_value": false, "rules": [{"attribute": "plan", "operator": "equals", "value": "pro"}]}, "user": {"plan": "pro"}, "expected": true}
+    {"name": "DNF back-compat: legacy flat rule still matches -> enabled", "flag_key": "f", "flag": {"enabled": true, "rollout_pct": 0, "flag_type": "boolean", "default_value": false, "rules": [{"attribute": "plan", "operator": "equals", "value": "pro"}]}, "user": {"plan": "pro"}, "expected": true},
+    {"name": "variation: string flag rule match serves enabled_value", "flag_key": "f", "flag": {"enabled": true, "rollout_pct": 0, "flag_type": "string", "default_value": "Shop", "enabled_value": "Buy now", "rules": [{"conditions": [{"attribute": "plan", "operator": "equals", "value": "pro"}]}]}, "user": {"plan": "pro", "user_id": "u1"}, "expected": "Buy now"},
+    {"name": "variation: string flag no match serves default_value", "flag_key": "f", "flag": {"enabled": true, "rollout_pct": 0, "flag_type": "string", "default_value": "Shop", "enabled_value": "Buy now", "rules": [{"conditions": [{"attribute": "plan", "operator": "equals", "value": "pro"}]}]}, "user": {"plan": "free", "user_id": "u1"}, "expected": "Shop"},
+    {"name": "variation: absent enabled_value falls back to default on match", "flag_key": "f", "flag": {"enabled": true, "rollout_pct": 0, "flag_type": "string", "default_value": "Shop", "rules": [{"conditions": [{"attribute": "plan", "operator": "equals", "value": "pro"}]}]}, "user": {"plan": "pro", "user_id": "u1"}, "expected": "Shop"},
+    {"name": "variation: number flag rollout 100 no context serves enabled_value", "flag_key": "f", "flag": {"enabled": true, "rollout_pct": 100, "flag_type": "number", "default_value": 0, "enabled_value": 42, "rules": []}, "user": null, "expected": 42},
+    {"name": "variation: disabled non-boolean serves default_value", "flag_key": "f", "flag": {"enabled": false, "rollout_pct": 100, "flag_type": "string", "default_value": "Shop", "enabled_value": "Buy now", "rules": []}, "user": {"user_id": "u1"}, "expected": "Shop"},
+    {"name": "variation: boolean flag ignores enabled_value (serves true)", "flag_key": "f", "flag": {"enabled": true, "rollout_pct": 100, "flag_type": "boolean", "default_value": false, "enabled_value": "ignored", "rules": []}, "user": null, "expected": true},
+    {"name": "rollout: user bucket 58 with rollout 59 -> enabled (bucket < pct)", "flag_key": "f", "flag": {"enabled": true, "rollout_pct": 59, "flag_type": "boolean", "default_value": false, "rules": []}, "user": {"user_id": "u_low"}, "expected": true},
+    {"name": "rollout: user bucket 58 with rollout 58 -> default (boundary is exclusive)", "flag_key": "f", "flag": {"enabled": true, "rollout_pct": 58, "flag_type": "boolean", "default_value": false, "rules": []}, "user": {"user_id": "u_low"}, "expected": false},
+    {"name": "rollout: user bucket 47 with rollout 48 -> enabled", "flag_key": "f", "flag": {"enabled": true, "rollout_pct": 48, "flag_type": "boolean", "default_value": false, "rules": []}, "user": {"user_id": "user-2"}, "expected": true},
+    {"name": "rollout: user bucket 47 with rollout 47 -> default", "flag_key": "f", "flag": {"enabled": true, "rollout_pct": 47, "flag_type": "boolean", "default_value": false, "rules": []}, "user": {"user_id": "user-2"}, "expected": false}
+  ],
+  "rollout_bucket": [
+    {"name": "42:new_checkout", "user_id": "42", "flag_key": "new_checkout", "expected": 98},
+    {"name": "user_100:feature_x", "user_id": "user_100", "flag_key": "feature_x", "expected": 4},
+    {"name": "abc:search_version", "user_id": "abc", "flag_key": "search_version", "expected": 10},
+    {"name": "u_low:f", "user_id": "u_low", "flag_key": "f", "expected": 58},
+    {"name": "user-2:f", "user_id": "user-2", "flag_key": "f", "expected": 47}
   ]
 }

{switchbox_flags-0.4.0 → switchbox_flags-0.6.0}/tests/test_client.py

@@ -1,4 +1,5 @@
 import json
+import time
 from unittest.mock import MagicMock, patch
 
 from switchbox.client import Switchbox
@@ -139,3 +140,44 @@ def test_client_close_stops_sync(mock_urlopen):
     c = Switchbox(sdk_key=TEST_SDK_KEY, cdn_base_url=TEST_CDN)
     c.close()
     assert c._sync._stop_event.is_set()
+
+
+# --- SEC-9: block_on_init ---
+
+
+@patch("switchbox.sync.urllib.request.urlopen")
+def test_client_block_on_init_true_ready_immediately(mock_urlopen):
+    """Default: the first fetch is synchronous, so the client is ready on return."""
+    mock_urlopen.return_value = _mock_urlopen(SAMPLE_CONFIG)
+    client = Switchbox(sdk_key=TEST_SDK_KEY, cdn_base_url=TEST_CDN)
+    assert client.ready is True
+    client.close()
+
+
+@patch("switchbox.sync.urllib.request.urlopen")
+def test_client_block_on_init_false_does_not_raise_on_failure(mock_urlopen):
+    """Non-blocking construction never blocks or raises on a down CDN — flag
+    checks just fall back to defaults until the background fetch succeeds."""
+    mock_urlopen.side_effect = Exception("CDN down")
+    client = Switchbox(
+        sdk_key=TEST_SDK_KEY, cdn_base_url=TEST_CDN, block_on_init=False
+    )
+    assert client.enabled("new_dashboard") is False
+    assert client.get_value("search_version", default="v1") == "v1"
+    client.close()
+
+
+@patch("switchbox.sync.urllib.request.urlopen")
+def test_client_block_on_init_false_becomes_ready(mock_urlopen):
+    """With block_on_init=False the config still arrives — on the background
+    thread — so the client becomes ready shortly after construction."""
+    mock_urlopen.return_value = _mock_urlopen(SAMPLE_CONFIG)
+    client = Switchbox(
+        sdk_key=TEST_SDK_KEY, cdn_base_url=TEST_CDN, block_on_init=False
+    )
+    deadline = time.monotonic() + 5
+    while not client.ready and time.monotonic() < deadline:
+        time.sleep(0.02)
+    assert client.ready is True
+    assert client.enabled("new_dashboard", user={"user_id": "1"}) is True
+    client.close()

switchbox_flags-0.6.0/tests/test_contract_fixtures.py

@@ -0,0 +1,123 @@
+"""CDN JSON contract — Python SDK side of the 3-repo handshake (TESTING Phase 2).
+
+Parses the canonical fixtures (`tests/fixtures/cdn-json/`, synced from the workspace
+`fixtures/cdn-json/` by `fixtures/sync.py`) and pins how `FlagConfig.from_dict`
+interprets the format the backend publisher emits. A format change that isn't mirrored
+here fails these tests; see the workspace `fixtures/cdn-json/README.md`.
+"""
+
+import json
+from pathlib import Path
+
+import pytest
+
+from switchbox.models import FlagConfig
+
+FIXTURES = Path(__file__).parent / "fixtures" / "cdn-json"
+
+
+def load(name: str) -> dict:
+    return json.loads((FIXTURES / f"{name}.json").read_text())
+
+
+@pytest.mark.parametrize(
+    "name",
+    ["full_config", "defaults", "unknown_fields", "legacy_flat_rules", "empty"],
+)
+def test_every_fixture_parses(name):
+    """Every canonical fixture parses without error."""
+    config = FlagConfig.from_dict(load(name))
+    assert isinstance(config, FlagConfig)
+    assert config.version  # all fixtures carry a version string
+
+
+def test_full_config_flag_types_and_values():
+    flags = FlagConfig.from_dict(load("full_config")).flags
+
+    assert flags["bool_on"].flag_type == "boolean"
+    assert flags["bool_on"].enabled is True
+    assert flags["bool_on"].rollout_pct == 100
+    assert flags["bool_on"].rules == []
+
+    assert flags["bool_off"].enabled is False
+
+    # Variations carry enabled_value; booleans do not.
+    assert flags["string_ab"].flag_type == "string"
+    assert flags["string_ab"].default_value == "control"
+    assert flags["string_ab"].enabled_value == "treatment"
+    assert flags["number_rollout"].enabled_value == 42
+    assert flags["number_rollout"].rollout_pct == 25
+    assert flags["json_variant"].default_value == {"theme": "light"}
+    assert flags["json_variant"].enabled_value == {"theme": "dark"}
+    assert flags["bool_on"].enabled_value is None
+
+
+def test_full_config_all_seven_operators_present():
+    flags = FlagConfig.from_dict(load("full_config")).flags
+    groups = flags["all_operators"].rules
+    ops = {c.operator for g in groups for c in g.conditions}
+    assert ops == {
+        "equals",
+        "not_equals",
+        "contains",
+        "ends_with",
+        "in_list",
+        "gt",
+        "lt",
+    }
+    # in_list value stays a list (both evaluators do membership against a list).
+    in_list = next(c for g in groups for c in g.conditions if c.operator == "in_list")
+    assert in_list.value == ["US", "CA", "GB"]
+
+
+def test_full_config_dnf_structure():
+    """Two-level DNF: a flag is OR of AND-groups."""
+    flags = FlagConfig.from_dict(load("full_config")).flags
+    groups = flags["all_operators"].rules
+    assert len(groups) == 3  # three OR'd groups
+    assert [len(g.conditions) for g in groups] == [2, 2, 3]
+
+
+def test_segments_are_inlined_not_referenced():
+    """The publisher expands segments to flat conditions — the SDK never sees a
+    segment reference."""
+    flags = FlagConfig.from_dict(load("full_config")).flags
+    seg = flags["segment_flag"]
+    assert len(seg.rules) == 1
+    cond = seg.rules[0].conditions[0]
+    assert (cond.attribute, cond.operator, cond.value) == (
+        "plan",
+        "equals",
+        "enterprise",
+    )
+
+
+def test_defaults_applied_for_omitted_fields():
+    flag = FlagConfig.from_dict(load("defaults")).flags["minimal"]
+    assert flag.enabled is True
+    assert flag.rollout_pct == 0
+    assert flag.flag_type == "boolean"
+    assert flag.default_value is None
+    assert flag.enabled_value is None
+    assert flag.rules == []
+
+
+def test_unknown_fields_are_ignored():
+    config = FlagConfig.from_dict(load("unknown_fields"))
+    flag = config.flags["fwd_compat"]
+    # Known fields parsed; unknown ones simply don't appear on the dataclass.
+    assert flag.enabled is True
+    assert not hasattr(flag, "some_future_field")
+
+
+def test_legacy_flat_rule_becomes_single_condition_group():
+    flag = FlagConfig.from_dict(load("legacy_flat_rules")).flags["legacy"]
+    assert len(flag.rules) == 1
+    assert len(flag.rules[0].conditions) == 1
+    cond = flag.rules[0].conditions[0]
+    assert (cond.attribute, cond.operator, cond.value) == ("country", "equals", "US")
+
+
+def test_empty_flags_object():
+    config = FlagConfig.from_dict(load("empty"))
+    assert config.flags == {}

{switchbox_flags-0.4.0 → switchbox_flags-0.6.0}/tests/test_parity_vectors.py

@@ -1,8 +1,10 @@
-"""Runs the shared cross-SDK parity vectors (SEC-4).
+"""Runs the shared cross-SDK parity vectors (SEC-4 / TESTING Phase 5).
 
-`parity_vectors.json` is byte-identical to the copy in switchbox-sdk-js; the JS
-suite runs the same file. Both must stay green so the two SDKs evaluate identical
-inputs identically. See the sdk-parity skill and DECISIONS.md ADR-013.
+The vectors are the canonical `fixtures/parity/parity_vectors.json` (workspace root),
+synced into this repo by `python3 fixtures/sync.py`; the JS suite runs the same bytes.
+Both must stay green so the two SDKs evaluate identical inputs identically. Edit the
+canonical and re-sync — never hand-edit this copy. See the sdk-parity skill and
+DECISIONS.md ADR-013 (coercion) + ADR-024 (shared-fixture mechanism).
 """
 
 import json
@@ -10,10 +12,19 @@ from pathlib import Path
 
 import pytest
 
-from switchbox.evaluator import _match_rule, evaluate
+from switchbox.evaluator import _check_rollout, _match_rule, evaluate
 from switchbox.models import FlagConfig, Rule
 
-_VECTORS = json.loads((Path(__file__).parent / "parity_vectors.json").read_text())
+_VECTORS = json.loads(
+    (Path(__file__).parent / "fixtures" / "parity" / "parity_vectors.json").read_text()
+)
+
+
+def _bucket(user_id: str, flag_key: str) -> int:
+    """Recover the rollout bucket from the real `_check_rollout` code path (which
+    the SDK has no public bucket accessor for): it returns `bucket < pct`, so the
+    smallest pct that flips it True is `bucket + 1`."""
+    return min(p for p in range(101) if _check_rollout(user_id, flag_key, p)) - 1
 
 
 def _flag_from(case):
@@ -33,6 +44,13 @@ def test_evaluate_vectors(case):
     assert evaluate(_flag_from(case), case["user"]) == case["expected"]
 
 
+@pytest.mark.parametrize("case", _VECTORS["rollout_bucket"], ids=lambda c: c["name"])
+def test_rollout_bucket_vectors(case):
+    """The rollout hash itself must produce identical buckets across SDKs —
+    sha256(f'{user_id}:{flag_key}') % 100. The JS suite asserts the same values."""
+    assert _bucket(case["user_id"], case["flag_key"]) == case["expected"]
+
+
 def test_user_id_resolution_ignores_id_when_user_id_present():
     """Null-only (`??`) fallback: `user_id` wins over `id`, so two contexts with
     the same user_id but different id must bucket — and therefore resolve —

{switchbox_flags-0.4.0 → switchbox_flags-0.6.0}/uv.lock

@@ -236,7 +236,7 @@ wheels = [
 
 [[package]]
 name = "switchbox-flags"
-version = "0.4.0"
+version = "0.6.0"
 source = { editable = "." }
 
 [package.optional-dependencies]