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

{switchbox_flags-0.1.0 → switchbox_flags-0.3.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.3.0/PKG-INFO

@@ -0,0 +1,244 @@
+Metadata-Version: 2.4
+Name: switchbox-flags
+Version: 0.3.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 Switchbox
+
+client = Switchbox(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 Switchbox(...) as client:` for automatic cleanup
+
+## Usage
+
+### Boolean Flags
+
+```python
+from switchbox import Switchbox
+
+client = Switchbox(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 Switchbox(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 = 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)
+)
+```
+
+| 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
+
+### `Switchbox(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.3.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 Switchbox
+
+client = Switchbox(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 Switchbox(...) as client:` for automatic cleanup
+
+## Usage
+
+### Boolean Flags
+
+```python
+from switchbox import Switchbox
+
+client = Switchbox(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 Switchbox(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 = 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)
+)
+```
+
+| 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
+
+### `Switchbox(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.3.0}/pyproject.toml

@@ -4,11 +4,11 @@ build-backend = "hatchling.build"
 
 [project]
 name = "switchbox-flags"
-version = "0.1.0"
+version = "0.3.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.3.0/switchbox/__init__.py

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

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

@@ -1,49 +1,69 @@
+from __future__ import annotations
+
 from typing import Any, Callable
 
 from switchbox.cache import FlagCache
 from switchbox.evaluator import evaluate
 from switchbox.sync import SyncWorker
 
+CDN_BASE_URL = "https://cdn.switchbox.dev"
+
 
-class Client:
+class Switchbox:
     """Switchbox feature flag client.
 
     Fetches flag configs from a CDN and evaluates them locally.
 
     Usage::
 
-        client = Client(cdn_url="https://cdn.example.com/proj/production/flags.json")
+        client = Switchbox(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 Switchbox(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 _eval_flag(self, flag_key: str, user: dict | None, fallback: Any) -> Any:
+        """Look up a flag and evaluate it, returning *fallback* if it's absent.
+
+        The shared path behind enabled()/get_value() — they differ only in
+        their fallback and how they coerce the result.
+        """
+        flag = self._cache.get_flag(flag_key)
+        if flag is None:
+            return fallback
+        return evaluate(flag, user)
+
     def enabled(self, flag_key: str, user: dict | None = None) -> bool:
         """Check if a boolean flag is enabled for a user.
 
         Returns False if the flag doesn't exist (safe default).
         """
-        flag = self._cache.get_flag(flag_key)
-        if flag is None:
-            return False
-        result = evaluate(flag, user)
-        return bool(result)
+        return bool(self._eval_flag(flag_key, user, False))
 
     def get_value(
         self, flag_key: str, user: dict | None = None, default: Any = None
@@ -52,10 +72,7 @@ class Client:
 
         Returns *default* if the flag doesn't exist.
         """
-        flag = self._cache.get_flag(flag_key)
-        if flag is None:
-            return default
-        return evaluate(flag, user)
+        return self._eval_flag(flag_key, user, default)
 
     def get_all_flags(self, user: dict | None = None) -> dict[str, Any]:
         """Get all flag values resolved for a user."""
@@ -68,7 +85,7 @@ class Client:
         """Stop the background sync. Call on shutdown."""
         self._sync.stop()
 
-    def __enter__(self) -> Client:
+    def __enter__(self) -> Switchbox:
         return self
 
     def __exit__(self, *args: object) -> None: