switchbox-flags 0.1.0__tar.gz → 0.2.0__tar.gz

{switchbox_flags-0.1.0 → switchbox_flags-0.2.0}/.github/workflows/test.yml

@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.14"]
+        python-version: ["3.10", "3.11", "3.12"]
     steps:
       - uses: actions/checkout@v4
 
@@ -25,5 +25,5 @@ jobs:
       - name: Lint
         run: ruff check .
 
-      - name: Test
-        run: pytest -v
+      - name: Test with coverage
+        run: pytest -v --cov=switchbox --cov-report=term-missing --cov-fail-under=80

switchbox_flags-0.2.0/PKG-INFO

@@ -0,0 +1,244 @@
+Metadata-Version: 2.4
+Name: switchbox-flags
+Version: 0.2.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
+Project-URL: Issues, https://github.com/ignat14/switchbox-sdk-python/issues
+Author: Switchbox
+License-Expression: MIT
+License-File: LICENSE
+Keywords: feature-flags,feature-toggles,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=6.0; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Switchbox
+
+Feature flags served from a CDN. Zero dependencies. Sub-millisecond evaluation.
+
+[![PyPI](https://img.shields.io/pypi/v/switchbox-flags)](https://pypi.org/project/switchbox-flags/)
+[![Python](https://img.shields.io/pypi/pyversions/switchbox-flags)](https://pypi.org/project/switchbox-flags/)
+[![License](https://img.shields.io/pypi/l/switchbox-flags)](https://github.com/ignat14/switchbox-sdk-python/blob/main/LICENSE)
+
+## What is this?
+
+Switchbox is a feature flag SDK that reads configs from a CDN instead of an API server. Flag configs are static JSON files on the edge — your app fetches them directly. Rules and rollouts are evaluated locally in the SDK, not on a server.
+
+## Install
+
+```
+pip install switchbox-flags
+```
+
+## Quick Start
+
+```python
+from switchbox import Client
+
+client = Client(sdk_key="your-sdk-key-from-dashboard")
+
+if client.enabled("new_checkout", user={"user_id": "42"}):
+    show_new_checkout()
+
+client.close()
+```
+
+## Features
+
+- **CDN-first** — fetches flag configs from static JSON on a CDN, no server in the read path
+- **Zero dependencies** — Python stdlib only, nothing to install beyond the package
+- **Sub-millisecond evaluation** — rules and rollouts evaluated locally in-process
+- **Background polling** — syncs configs every 30 seconds (configurable)
+- **Offline resilient** — keeps working on cached configs if the CDN is unreachable
+- **Thread-safe** — safe to use from multiple threads
+- **Context manager** — supports `with Client(...) as client:` for automatic cleanup
+
+## Usage
+
+### Boolean Flags
+
+```python
+from switchbox import Client
+
+client = Client(sdk_key="your-sdk-key-from-dashboard")
+
+if client.enabled("dark_mode"):
+    enable_dark_mode()
+
+client.close()
+```
+
+### String / Number Flags
+
+```python
+version = client.get_value("search_algorithm", user={"user_id": "42"}, default="v1")
+print(f"Using search {version}")
+
+max_results = client.get_value("max_search_results", user={"user_id": "42"}, default=10)
+```
+
+### All Flags at Once
+
+```python
+flags = client.get_all_flags(user={"user_id": "42"})
+# {"dark_mode": True, "search_algorithm": "v2", "max_search_results": 50}
+```
+
+### Targeting Rules
+
+Pass a `user` dict with attributes you want to target on. Rules are configured in the dashboard.
+
+```python
+user = {
+    "user_id": "42",
+    "email": "alice@company.com",
+    "plan": "enterprise",
+    "age": "30",
+}
+
+# Flag with rule: email ends_with "@company.com"
+client.enabled("internal_tools", user=user)  # True
+
+# Flag with rule: plan equals "enterprise"
+client.enabled("advanced_analytics", user=user)  # True
+
+# Flag with rule: plan in_list ["pro", "enterprise"]
+client.enabled("export_csv", user=user)  # True
+```
+
+Supported operators: `equals`, `not_equals`, `contains`, `ends_with`, `in_list`, `gt`, `lt`.
+
+Rules use OR logic — if any rule matches, the flag is on for that user.
+
+### Percentage Rollouts
+
+Rollouts use deterministic hashing (`sha256(user_id:flag_key) % 100`). The same user always gets the same result for a given flag — no flickering between requests.
+
+```python
+# Flag with rollout_pct=25 — 25% of users get this flag
+client.enabled("new_onboarding", user={"user_id": "42"})  # deterministic True/False
+```
+
+A `user_id` (or `id`) key is required in the user dict for percentage rollouts.
+
+### Offline / Fail-safe Behavior
+
+If the CDN is unreachable, the SDK keeps using the last successfully fetched config. Your flags keep working.
+
+If the SDK has never successfully fetched a config (e.g., CDN is down on first startup), `enabled()` returns `False` and `get_value()` returns the `default` you pass in. No exceptions are raised.
+
+### Context Manager
+
+```python
+with Client(sdk_key="your-sdk-key-from-dashboard") as client:
+    if client.enabled("new_checkout", user={"user_id": "42"}):
+        show_new_checkout()
+# client.close() is called automatically
+```
+
+## Configuration
+
+```python
+client = Client(
+    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)
+)
+```
+
+| Parameter       | Type                           | Default | Description                                    |
+|-----------------|--------------------------------|---------|------------------------------------------------|
+| `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   |
+
+The SDK builds the CDN URL automatically from the SDK key. You can override with `cdn_base_url` if self-hosting.
+
+## How It Works
+
+```
+┌──────────┐       ┌──────────┐       ┌─────────────┐
+│Dashboard │──────>│ API      │──────>│  Postgres   │
+│          │ HTTP  │ (Fly.io) │  SQL  │  (Neon)     │
+└──────────┘       └────┬─────┘       └─────────────┘
+                        │
+                        │ publish on every change
+                        v
+                 ┌─────────────┐       ┌──────────────┐
+                 │CDN Publisher│──────>│Cloudflare R2 │
+                 │             │  PUT  │(static JSON) │
+                 └─────────────┘       └──────┬───────┘
+                                              │
+                                              │ HTTP GET (SDK polls)
+                                              v
+                                       ┌──────────────┐
+                                       │  Your App    │
+                                       │  (this SDK)  │
+                                       └──────────────┘
+```
+
+1. You create and toggle flags in the dashboard or API
+2. On every change, the API generates a static JSON file and uploads it to Cloudflare R2
+3. This SDK polls that JSON file from the CDN every 30 seconds
+4. Flag evaluation (rules, rollouts) happens locally — no network call per flag check
+
+The API server is only in the write path. All read traffic goes to the CDN.
+
+## API Reference
+
+### `Client(sdk_key, poll_interval=30, on_error=None)`
+
+Creates a new client. Performs an initial synchronous fetch on creation, then starts background polling.
+
+### `client.enabled(flag_key, user=None) -> bool`
+
+Check if a boolean flag is enabled. Returns `False` if the flag doesn't exist.
+
+| Parameter  | Type           | Description                          |
+|------------|----------------|--------------------------------------|
+| `flag_key` | `str`          | The flag key to check                |
+| `user`     | `dict \| None` | User context for targeting/rollouts  |
+
+### `client.get_value(flag_key, user=None, default=None) -> Any`
+
+Get the resolved value of any flag type (string, number, JSON). Returns `default` if the flag doesn't exist.
+
+| Parameter  | Type           | Description                          |
+|------------|----------------|--------------------------------------|
+| `flag_key` | `str`          | The flag key to check                |
+| `user`     | `dict \| None` | User context for targeting/rollouts  |
+| `default`  | `Any`          | Value returned if flag doesn't exist |
+
+### `client.get_all_flags(user=None) -> dict[str, Any]`
+
+Get all flag values resolved for a user. Returns an empty dict if no config is available.
+
+### `client.close() -> None`
+
+Stop background polling. Call this on application shutdown.
+
+## Contributing
+
+```sh
+git clone https://github.com/ignat14/switchbox-sdk-python.git
+cd switchbox-sdk-python
+pip install -e ".[dev]"
+pytest
+ruff check .
+```
+
+## License
+
+MIT

switchbox_flags-0.2.0/README.md

@@ -0,0 +1,218 @@
+# Switchbox
+
+Feature flags served from a CDN. Zero dependencies. Sub-millisecond evaluation.
+
+[![PyPI](https://img.shields.io/pypi/v/switchbox-flags)](https://pypi.org/project/switchbox-flags/)
+[![Python](https://img.shields.io/pypi/pyversions/switchbox-flags)](https://pypi.org/project/switchbox-flags/)
+[![License](https://img.shields.io/pypi/l/switchbox-flags)](https://github.com/ignat14/switchbox-sdk-python/blob/main/LICENSE)
+
+## What is this?
+
+Switchbox is a feature flag SDK that reads configs from a CDN instead of an API server. Flag configs are static JSON files on the edge — your app fetches them directly. Rules and rollouts are evaluated locally in the SDK, not on a server.
+
+## Install
+
+```
+pip install switchbox-flags
+```
+
+## Quick Start
+
+```python
+from switchbox import Client
+
+client = Client(sdk_key="your-sdk-key-from-dashboard")
+
+if client.enabled("new_checkout", user={"user_id": "42"}):
+    show_new_checkout()
+
+client.close()
+```
+
+## Features
+
+- **CDN-first** — fetches flag configs from static JSON on a CDN, no server in the read path
+- **Zero dependencies** — Python stdlib only, nothing to install beyond the package
+- **Sub-millisecond evaluation** — rules and rollouts evaluated locally in-process
+- **Background polling** — syncs configs every 30 seconds (configurable)
+- **Offline resilient** — keeps working on cached configs if the CDN is unreachable
+- **Thread-safe** — safe to use from multiple threads
+- **Context manager** — supports `with Client(...) as client:` for automatic cleanup
+
+## Usage
+
+### Boolean Flags
+
+```python
+from switchbox import Client
+
+client = Client(sdk_key="your-sdk-key-from-dashboard")
+
+if client.enabled("dark_mode"):
+    enable_dark_mode()
+
+client.close()
+```
+
+### String / Number Flags
+
+```python
+version = client.get_value("search_algorithm", user={"user_id": "42"}, default="v1")
+print(f"Using search {version}")
+
+max_results = client.get_value("max_search_results", user={"user_id": "42"}, default=10)
+```
+
+### All Flags at Once
+
+```python
+flags = client.get_all_flags(user={"user_id": "42"})
+# {"dark_mode": True, "search_algorithm": "v2", "max_search_results": 50}
+```
+
+### Targeting Rules
+
+Pass a `user` dict with attributes you want to target on. Rules are configured in the dashboard.
+
+```python
+user = {
+    "user_id": "42",
+    "email": "alice@company.com",
+    "plan": "enterprise",
+    "age": "30",
+}
+
+# Flag with rule: email ends_with "@company.com"
+client.enabled("internal_tools", user=user)  # True
+
+# Flag with rule: plan equals "enterprise"
+client.enabled("advanced_analytics", user=user)  # True
+
+# Flag with rule: plan in_list ["pro", "enterprise"]
+client.enabled("export_csv", user=user)  # True
+```
+
+Supported operators: `equals`, `not_equals`, `contains`, `ends_with`, `in_list`, `gt`, `lt`.
+
+Rules use OR logic — if any rule matches, the flag is on for that user.
+
+### Percentage Rollouts
+
+Rollouts use deterministic hashing (`sha256(user_id:flag_key) % 100`). The same user always gets the same result for a given flag — no flickering between requests.
+
+```python
+# Flag with rollout_pct=25 — 25% of users get this flag
+client.enabled("new_onboarding", user={"user_id": "42"})  # deterministic True/False
+```
+
+A `user_id` (or `id`) key is required in the user dict for percentage rollouts.
+
+### Offline / Fail-safe Behavior
+
+If the CDN is unreachable, the SDK keeps using the last successfully fetched config. Your flags keep working.
+
+If the SDK has never successfully fetched a config (e.g., CDN is down on first startup), `enabled()` returns `False` and `get_value()` returns the `default` you pass in. No exceptions are raised.
+
+### Context Manager
+
+```python
+with Client(sdk_key="your-sdk-key-from-dashboard") as client:
+    if client.enabled("new_checkout", user={"user_id": "42"}):
+        show_new_checkout()
+# client.close() is called automatically
+```
+
+## Configuration
+
+```python
+client = Client(
+    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)
+)
+```
+
+| Parameter       | Type                           | Default | Description                                    |
+|-----------------|--------------------------------|---------|------------------------------------------------|
+| `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   |
+
+The SDK builds the CDN URL automatically from the SDK key. You can override with `cdn_base_url` if self-hosting.
+
+## How It Works
+
+```
+┌──────────┐       ┌──────────┐       ┌─────────────┐
+│Dashboard │──────>│ API      │──────>│  Postgres   │
+│          │ HTTP  │ (Fly.io) │  SQL  │  (Neon)     │
+└──────────┘       └────┬─────┘       └─────────────┘
+                        │
+                        │ publish on every change
+                        v
+                 ┌─────────────┐       ┌──────────────┐
+                 │CDN Publisher│──────>│Cloudflare R2 │
+                 │             │  PUT  │(static JSON) │
+                 └─────────────┘       └──────┬───────┘
+                                              │
+                                              │ HTTP GET (SDK polls)
+                                              v
+                                       ┌──────────────┐
+                                       │  Your App    │
+                                       │  (this SDK)  │
+                                       └──────────────┘
+```
+
+1. You create and toggle flags in the dashboard or API
+2. On every change, the API generates a static JSON file and uploads it to Cloudflare R2
+3. This SDK polls that JSON file from the CDN every 30 seconds
+4. Flag evaluation (rules, rollouts) happens locally — no network call per flag check
+
+The API server is only in the write path. All read traffic goes to the CDN.
+
+## API Reference
+
+### `Client(sdk_key, poll_interval=30, on_error=None)`
+
+Creates a new client. Performs an initial synchronous fetch on creation, then starts background polling.
+
+### `client.enabled(flag_key, user=None) -> bool`
+
+Check if a boolean flag is enabled. Returns `False` if the flag doesn't exist.
+
+| Parameter  | Type           | Description                          |
+|------------|----------------|--------------------------------------|
+| `flag_key` | `str`          | The flag key to check                |
+| `user`     | `dict \| None` | User context for targeting/rollouts  |
+
+### `client.get_value(flag_key, user=None, default=None) -> Any`
+
+Get the resolved value of any flag type (string, number, JSON). Returns `default` if the flag doesn't exist.
+
+| Parameter  | Type           | Description                          |
+|------------|----------------|--------------------------------------|
+| `flag_key` | `str`          | The flag key to check                |
+| `user`     | `dict \| None` | User context for targeting/rollouts  |
+| `default`  | `Any`          | Value returned if flag doesn't exist |
+
+### `client.get_all_flags(user=None) -> dict[str, Any]`
+
+Get all flag values resolved for a user. Returns an empty dict if no config is available.
+
+### `client.close() -> None`
+
+Stop background polling. Call this on application shutdown.
+
+## Contributing
+
+```sh
+git clone https://github.com/ignat14/switchbox-sdk-python.git
+cd switchbox-sdk-python
+pip install -e ".[dev]"
+pytest
+ruff check .
+```
+
+## License
+
+MIT

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

@@ -4,11 +4,11 @@ build-backend = "hatchling.build"
 
 [project]
 name = "switchbox-flags"
-version = "0.1.0"
+version = "0.2.0"
 description = "Feature flag SDK with zero dependencies"
 readme = "README.md"
 license = "MIT"
-requires-python = ">=3.14"
+requires-python = ">=3.10"
 authors = [{ name = "Switchbox" }]
 keywords = ["feature-flags", "feature-toggles", "sdk"]
 classifiers = [
@@ -16,7 +16,9 @@ classifiers = [
     "Intended Audience :: Developers",
     "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
     "Typing :: Typed",
 ]
 
@@ -32,11 +34,18 @@ packages = ["switchbox"]
 testpaths = ["tests"]
 
 [tool.ruff]
-target-version = "py314"
+target-version = "py310"
 line-length = 100
 
 [tool.ruff.lint]
 select = ["E", "F", "I", "W"]
 
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+    "pytest-cov>=7.0.0",
+    "ruff>=0.15.5",
+]
+
 [project.optional-dependencies]
-dev = ["pytest>=7", "ruff>=0.4"]
+dev = ["pytest>=7", "ruff>=0.4", "pytest-cov>=6.0"]

{switchbox_flags-0.1.0 → switchbox_flags-0.2.0}/switchbox/client.py

@@ -4,6 +4,8 @@ from switchbox.cache import FlagCache
 from switchbox.evaluator import evaluate
 from switchbox.sync import SyncWorker
 
+CDN_BASE_URL = "https://cdn.switchbox.dev"
+
 
 class Client:
     """Switchbox feature flag client.
@@ -12,28 +14,37 @@ class Client:
 
     Usage::
 
-        client = Client(cdn_url="https://cdn.example.com/proj/production/flags.json")
+        client = Client(sdk_key="your-sdk-key")
         if client.enabled("new_feature", user={"user_id": "42"}):
             ...
         client.close()
 
     Or as a context manager::
 
-        with Client(cdn_url="...") as client:
+        with Client(sdk_key="your-sdk-key") as client:
             if client.enabled("new_feature"):
                 ...
     """
 
     def __init__(
         self,
-        cdn_url: str,
+        sdk_key: str,
         poll_interval: int = 30,
         on_error: Callable[[Exception], None] | None = None,
+        timeout: int = 10,
+        cdn_base_url: str | None = None,
     ) -> 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)
+        self._sync = SyncWorker(cdn_url, self._cache, poll_interval, on_error, timeout=timeout)
         self._sync.start()
 
+    @property
+    def ready(self) -> bool:
+        """Return True when configs have been loaded at least once."""
+        return self._cache.get_config() is not None
+
     def enabled(self, flag_key: str, user: dict | None = None) -> bool:
         """Check if a boolean flag is enabled for a user.
 

{switchbox_flags-0.1.0 → switchbox_flags-0.2.0}/switchbox/evaluator.py

@@ -21,35 +21,38 @@ def evaluate(flag: Flag, user_context: dict | None = None) -> bool | str | int |
     4. Rollout percentage check → enabled value or default_value
     5. Nothing matched → default_value
     """
-    # 1. Disabled flag always returns default
-    if not flag.enabled:
-        return flag.default_value
-
-    # 2. No user context
-    if not user_context:
-        if flag.rollout_pct == 100:
-            return _enabled_value(flag)
-        return flag.default_value
-
-    # 3. Check rules (OR logic — any match wins)
-    if flag.rules:
-        for rule in flag.rules:
-            if _match_rule(rule, user_context):
+    try:
+        # 1. Disabled flag always returns default
+        if not flag.enabled:
+            return flag.default_value
+
+        # 2. No user context
+        if not user_context:
+            if flag.rollout_pct == 100:
+                return _enabled_value(flag)
+            return flag.default_value
+
+        # 3. Check rules (OR logic — any match wins)
+        if flag.rules:
+            for rule in flag.rules:
+                if _match_rule(rule, user_context):
+                    return _enabled_value(flag)
+
+        # 4. Rollout percentage
+        user_id = user_context.get("user_id") or user_context.get("id")
+        if user_id is not None:
+            if _check_rollout(str(user_id), flag.key, flag.rollout_pct):
+                return _enabled_value(flag)
+        else:
+            # No user ID for hashing — can only serve 100% rollouts
+            if flag.rollout_pct == 100:
                 return _enabled_value(flag)
+            return flag.default_value
 
-    # 4. Rollout percentage
-    user_id = user_context.get("user_id") or user_context.get("id")
-    if user_id is not None:
-        if _check_rollout(str(user_id), flag.key, flag.rollout_pct):
-            return _enabled_value(flag)
-    else:
-        # No user ID for hashing — can only serve 100% rollouts
-        if flag.rollout_pct == 100:
-            return _enabled_value(flag)
+        # 5. Nothing matched
+        return flag.default_value
+    except Exception:
         return flag.default_value
-
-    # 5. Nothing matched
-    return flag.default_value
 
 
 def _enabled_value(flag: Flag) -> bool | str | int | Any:
@@ -66,6 +69,9 @@ def _match_rule(rule: Rule, user_context: dict) -> bool:
 
     context_value = user_context[rule.attribute]
 
+    if context_value is None:
+        return False
+
     if rule.operator == "equals":
         return str(context_value) == str(rule.value)
     elif rule.operator == "not_equals":