flagstone-sdk 0.1.0__py3-none-any.whl

flagstone_sdk/__init__.py

@@ -0,0 +1,19 @@
+"""Python SDK for Flagstone feature flags.
+
+    from flagstone_sdk import FlagClient
+
+    client = FlagClient(sdk_key="...", base_url="https://flags.example.com")
+    if client.is_enabled("new-dashboard", {"id": "user-123"}):
+        ...
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .client import FlagClient
+
+try:
+    __version__ = version("flagstone-sdk")
+except PackageNotFoundError:  # running from a source checkout that isn't installed
+    __version__ = "0.0.0"
+
+__all__ = ["FlagClient", "__version__"]

flagstone_sdk/bucketing.py

@@ -0,0 +1,9 @@
+import hashlib
+
+def bucket(flag_key: str, user_id: str) -> int:
+    raw = f"{flag_key}:{user_id}".encode()
+    digest = hashlib.md5(raw).hexdigest()
+    return int(digest[:8], 16) % 100
+
+def in_rollout(flag_key: str, user_id: str, percentage: int) -> bool:
+    return bucket(flag_key, user_id) < percentage

flagstone_sdk/client.py

@@ -0,0 +1,138 @@
+import threading
+
+import httpx
+
+from .disk_cache import DiskCache
+from .evaluator import evaluate
+from .poller import Poller
+from .stream_listener import StreamListener
+
+
+class FlagClient:
+    def __init__(
+        self,
+        sdk_key: str,
+        base_url: str = "http://localhost:8000",
+        poll_interval: int = 30,
+        use_sse: bool = False,
+        cache_path: str | None = "~/.flagstone_cache.json",
+        flush_interval: int = 10,
+    ) -> None:
+        self._sdk_key = sdk_key
+        self._base_url = base_url.rstrip("/")
+        self._flags: dict[str, dict] = {}
+        self._lock = threading.Lock()
+        self._http = httpx.Client(headers={"x-sdk-key": sdk_key}, timeout=10)
+        self._event_buffer: list[dict] = []
+        self._flush_lock = threading.Lock()
+        self._flush_interval = flush_interval
+        self._cache = DiskCache(cache_path) if cache_path else None
+        try:
+            self._refresh()
+        except Exception:
+            if self._cache:
+                cached = self._cache.read()
+                if cached:
+                    with self._lock:
+                        self._flags = cached.get("flags", {})
+        if use_sse:
+            self._listener = StreamListener(
+                url=f"{self._base_url}/sdk/stream",
+                sdk_key=sdk_key,
+                on_update=self._on_sse_update,
+            )
+            self._listener.start()
+        else:
+            self._poller = Poller(self._refresh, poll_interval)
+            self._poller.start()
+        self._schedule_flush()
+
+    def is_enabled(self, flag_key: str, user: dict) -> bool:
+        with self._lock:
+            flag = self._flags.get(flag_key)
+        if flag is None:
+            return False
+        variation_index = evaluate(flag, user)
+        self._buffer_event("exposure", flag_key, variation_index, user)
+        return bool(flag["variations"][variation_index])
+
+    def get_variation(self, flag_key: str, user: dict) -> int:
+        with self._lock:
+            flag = self._flags.get(flag_key)
+        if flag is None:
+            return 0
+        return evaluate(flag, user)
+
+    def track_conversion(self, flag_key: str, user: dict) -> None:
+        with self._lock:
+            flag = self._flags.get(flag_key)
+        variation_index = evaluate(flag, user) if flag else 0
+        self._buffer_event("conversion", flag_key, variation_index, user)
+
+    def _buffer_event(self, event_type: str, flag_key: str, variation_index: int, user: dict) -> None:
+        with self._flush_lock:
+            self._event_buffer.append({
+                "flag_key": flag_key,
+                "event_type": event_type,
+                "variation_index": variation_index,
+                "user_id": user.get("id", ""),
+                "attributes": {k: v for k, v in user.items() if k != "id"},
+            })
+            if len(self._event_buffer) >= 100:
+                self._flush_now()
+
+    def _flush_now(self) -> None:
+        events, self._event_buffer = self._event_buffer, []
+        if events:
+            try:
+                self._http.post(
+                    f"{self._base_url}/sdk/events",
+                    json={"events": events},
+                    timeout=5,
+                )
+            except Exception:
+                pass
+
+    def _schedule_flush(self) -> None:
+        if hasattr(self, "_flush_timer"):
+            self._flush_timer.cancel()
+        t = threading.Timer(self._flush_interval, self._timed_flush)
+        t.daemon = True
+        t.start()
+        self._flush_timer = t
+
+    def _timed_flush(self) -> None:
+        with self._flush_lock:
+            self._flush_now()
+        self._schedule_flush()
+
+    def _refresh(self) -> None:
+        resp = self._http.get(f"{self._base_url}/sdk/config")
+        resp.raise_for_status()
+        config = resp.json()
+        with self._lock:
+            self._flags = config.get("flags", {})
+        if self._cache:
+            self._cache.write(config)
+
+    def _on_sse_update(self, event: dict) -> None:
+        if event.get("event") == "deleted":
+            key = event.get("key")
+            if key:
+                with self._lock:
+                    self._flags.pop(key, None)
+        else:
+            # SSE is a change-signal; fetch updated config
+            try:
+                self._refresh()
+            except Exception:
+                pass
+
+    def close(self) -> None:
+        if hasattr(self, "_flush_timer"):
+            self._flush_timer.cancel()
+        if hasattr(self, "_poller"):
+            self._poller.stop()
+        if hasattr(self, "_listener"):
+            self._listener.stop()
+        self._http.close()

flagstone_sdk/disk_cache.py

@@ -0,0 +1,26 @@
+import json
+from pathlib import Path
+from datetime import datetime, timezone
+
+
+class DiskCache:
+    def __init__(self, path: str = "~/.flagstone_cache.json") -> None:
+        self._path = Path(path).expanduser()
+
+    def write(self, config: dict) -> None:
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = self._path.with_suffix(".tmp")
+        tmp.write_text(json.dumps({
+            "written_at": datetime.now(timezone.utc).isoformat(),
+            "config": config,
+        }))
+        tmp.replace(self._path)
+
+    def read(self) -> dict | None:
+        if not self._path.exists():
+            return None
+        try:
+            data = json.loads(self._path.read_text())
+            return data["config"]
+        except (json.JSONDecodeError, KeyError):
+            return None

flagstone_sdk/evaluator.py

@@ -0,0 +1,25 @@
+from .bucketing import in_rollout
+
+def evaluate(flag: dict, user: dict) -> int:
+    if not flag.get("enabled", True):
+        return flag.get("default_variation", 0)
+    for rule in flag.get("rules", []):
+        if _match_rule(rule, user):
+            return rule["variation"]
+    rollout = flag.get("rollout")
+    if rollout:
+        user_id = user.get("id", "")
+        if in_rollout(flag["key"], user_id, rollout["percentage"]):
+            return rollout["variation"]
+    return flag.get("default_variation", 0)
+
+def _match_rule(rule: dict, user: dict) -> bool:
+    attr = user.get(rule["attribute"])
+    op = rule["operator"]
+    val = rule["value"]
+    if op == "equals":   return attr == val
+    if op == "contains": return isinstance(attr, str) and val in attr
+    if op == "gt":       return isinstance(attr, (int, float)) and attr > val
+    if op == "lt":       return isinstance(attr, (int, float)) and attr < val
+    if op == "in":       return attr in val
+    return False

flagstone_sdk/poller.py

@@ -0,0 +1,24 @@
+import threading
+from collections.abc import Callable
+
+
+class Poller:
+    def __init__(self, refresh: Callable[[], None], interval: int) -> None:
+        self._refresh = refresh
+        self._interval = interval
+        self._stop = threading.Event()
+        self._thread = threading.Thread(target=self._run, daemon=True)
+
+    def start(self) -> None:
+        self._thread.start()
+
+    def stop(self) -> None:
+        self._stop.set()
+        self._thread.join(timeout=5)
+
+    def _run(self) -> None:
+        while not self._stop.wait(self._interval):
+            try:
+                self._refresh()
+            except Exception:
+                pass

flagstone_sdk/stream_listener.py

@@ -0,0 +1,46 @@
+import json
+import threading
+import time
+from collections.abc import Callable
+
+import httpx
+
+
+class StreamListener:
+    def __init__(self, url: str, sdk_key: str, on_update: Callable[[dict], None]) -> None:
+        self._url = url
+        self._sdk_key = sdk_key
+        self._on_update = on_update
+        self._stop = threading.Event()
+        self._thread = threading.Thread(target=self._run, daemon=True)
+
+    def start(self) -> None:
+        self._thread.start()
+
+    def stop(self) -> None:
+        self._stop.set()
+        self._thread.join(timeout=5)
+
+    def _run(self) -> None:
+        backoff = 1
+        while not self._stop.is_set():
+            try:
+                with httpx.Client(
+                    headers={"x-sdk-key": self._sdk_key}, timeout=None
+                ) as http:
+                    with http.stream("GET", self._url) as resp:
+                        backoff = 1
+                        for line in resp.iter_lines():
+                            if self._stop.is_set():
+                                return
+                            if line.startswith("data:"):
+                                data = line[5:].strip()
+                                if data:
+                                    try:
+                                        self._on_update(json.loads(data))
+                                    except json.JSONDecodeError:
+                                        pass
+            except Exception:
+                if not self._stop.is_set():
+                    time.sleep(min(backoff, 60))
+                    backoff = min(backoff * 2, 60)

flagstone_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: flagstone-sdk
+Version: 0.1.0
+Summary: Python SDK for Flagstone feature flags: local flag evaluation, percentage rollouts and A/B experiment events.
+Author: Tejas Ashri
+License-Expression: MIT
+Keywords: feature flags,feature toggles,a/b testing,experiments,rollout
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27
+Dynamic: license-file
+
+# flagstone-sdk
+
+Python SDK for Flagstone feature flags.
+
+The client downloads your project's flag configuration once and **evaluates flags locally**, in your
+application's process. A flag check is a dictionary lookup and a few comparisons, with no network
+call, so it is safe to use in hot paths. The client keeps its copy up to date in the background,
+and keeps working with the last configuration it had if the Flagstone server is unreachable.
+
+## Install
+
+```bash
+pip install flagstone-sdk
+```
+
+Requires Python 3.10 or newer. The only dependency is [httpx](https://www.python-httpx.org/).
+
+## Quickstart
+
+```python
+from flagstone_sdk import FlagClient
+
+client = FlagClient(
+    sdk_key="fs_...",                      # from your project's "SDK keys" page
+    base_url="https://flags.example.com",  # where your Flagstone server runs
+)
+
+user = {"id": "user-123", "plan": "pro", "country": "IN"}
+
+if client.is_enabled("new-dashboard", user):
+    show_new_dashboard()
+
+# Record that this user converted, for the flag's experiment results.
+client.track_conversion("new-dashboard", user)
+
+client.close()  # on shutdown
+```
+
+Create one client when your application starts and share it. Creating a client fetches the
+configuration and starts a background refresh thread.
+
+## Users and targeting
+
+A user is a plain `dict`. `"id"` is required: it decides which side of a percentage rollout the
+user falls on, and the same id always gets the same answer. Any other keys (`plan`, `country`,
+`email`, ...) are attributes that targeting rules can match on. Rules and rollouts are configured in
+the Flagstone admin UI.
+
+## API
+
+| Method | Returns |
+| --- | --- |
+| `is_enabled(flag_key, user)` | `True` if the variation served to this user is truthy. Records an exposure event. Unknown flags return `False`. |
+| `get_variation(flag_key, user)` | Index of the variation served to this user. Does not record an event. Unknown flags return `0`. |
+| `track_conversion(flag_key, user)` | Records a conversion for the variation this user is served. |
+| `close()` | Stops background refreshes and releases the HTTP connection. |
+
+### Options
+
+| Argument | Default | Meaning |
+| --- | --- | --- |
+| `sdk_key` | required | The project's SDK key. |
+| `base_url` | `http://localhost:8000` | URL of your Flagstone server. |
+| `poll_interval` | `30` | Seconds between configuration refreshes when polling. |
+| `use_sse` | `False` | Receive changes over Server-Sent Events instead of polling. Changes arrive within a second, but the connection must be allowed through any proxies in between. |
+| `cache_path` | `~/.flagstone_cache.json` | Where the last configuration is saved, so the client can start even if the server is down. `None` disables the cache. |
+| `flush_interval` | `10` | Seconds between sending batched events. Events are also sent every 100 events. |
+
+## Keep SDK keys on the server
+
+The client downloads the full configuration of the key's project, including targeting rules and the
+values they compare against. Use the SDK only in server-side code. Never put an SDK key in a browser,
+mobile app or any code your users can read.
+
+## Good to know
+
+- Events are delivered on a best-effort basis: if sending a batch fails, that batch is dropped.
+- `close()` does not send events that are still buffered; up to `flush_interval` seconds of events
+  can be lost at shutdown.
+
+## License
+
+MIT. The full license text is included in the package.

flagstone_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+flagstone_sdk/__init__.py,sha256=wH170Q4hRznEE3i0M34cSyejo6W6Ky4IAeFaeUA3T-w,536
+flagstone_sdk/bucketing.py,sha256=Q3JLwfTktvlEYrduJuZKd78RFTXu-uA5YYrSo8_t-rQ,307
+flagstone_sdk/client.py,sha256=euGV7Kq71ZZDEqQzlZylBTerOO7YPbI7tvQdZKi_P5o,4659
+flagstone_sdk/disk_cache.py,sha256=KjAAwCGkqic2H0X5paHZWT29ug8Hx9YdxVZf9RUYO6M,808
+flagstone_sdk/evaluator.py,sha256=HdNDlcchUdJXsn6PjveNaqk7rTo1bmyWSh6OIfZDQhU,987
+flagstone_sdk/poller.py,sha256=uZdOOrPtlfpeH-2fD2d2dxVRabDyVj8LPNnlCuOcQBU,652
+flagstone_sdk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+flagstone_sdk/stream_listener.py,sha256=L24it2TE3XsIsUdNfkFsjYwmZf02MLE0GdaXMGpCSPc,1596
+flagstone_sdk-0.1.0.dist-info/licenses/LICENSE,sha256=W5w8mnnDNnZod-UkbCMdgmuVHo-rBuFeMaLSUewjwuM,1068
+flagstone_sdk-0.1.0.dist-info/METADATA,sha256=otM5sd-Yx_TtnnHRUkiNj7rDzMMq3bRK1sVgMN-Zdac,4403
+flagstone_sdk-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+flagstone_sdk-0.1.0.dist-info/top_level.txt,sha256=5AEbBJdbj_V9BamhxKAdJn2PJmTSL6ahYP7ypGT_M7E,14
+flagstone_sdk-0.1.0.dist-info/RECORD,,

flagstone_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

flagstone_sdk-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tejas Ashri
+
+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.

flagstone_sdk-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+flagstone_sdk