rocketflag 0.1.0__py3-none-any.whl

rocketflag/__init__.py

@@ -0,0 +1,18 @@
+"""Official Python SDK for RocketFlag."""
+
+from .client import DEFAULT_API_URL, DEFAULT_VERSION, Client, Flag, create_client
+from .errors import APIError, InvalidResponseError, NetworkError, RocketFlagError
+
+__all__ = [
+    "APIError",
+    "Client",
+    "DEFAULT_API_URL",
+    "DEFAULT_VERSION",
+    "Flag",
+    "InvalidResponseError",
+    "NetworkError",
+    "RocketFlagError",
+    "create_client",
+]
+
+__version__ = "0.1.0"

rocketflag/client.py

@@ -0,0 +1,152 @@
+"""RocketFlag evaluation client.
+
+Mirrors the Node and Go SDKs: GET {api_url}/{version}/flags/{flag_id}
+with optional query-string user context (cohort, env, …) and an opt-in
+in-memory TTL cache keyed by flag ID + context.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass
+from typing import Any, Mapping, Optional, Union
+
+from .errors import APIError, InvalidResponseError, NetworkError
+
+DEFAULT_API_URL = "https://api.rocketflag.app"
+DEFAULT_VERSION = "v1"
+_ALPHANUMERIC = re.compile(r"^[a-zA-Z0-9]+$")
+
+ContextValue = Union[str, int, float, bool]
+UserContext = Mapping[str, ContextValue]
+
+
+@dataclass(frozen=True)
+class Flag:
+    """A evaluated feature flag."""
+
+    name: str
+    enabled: bool
+    id: str
+
+
+def _validate_flag(payload: Any) -> Flag:
+    if not isinstance(payload, dict):
+        raise InvalidResponseError("Invalid response format: response is not an object")
+    name = payload.get("name")
+    enabled = payload.get("enabled")
+    flag_id = payload.get("id")
+    if not isinstance(name, str) or not isinstance(enabled, bool) or not isinstance(flag_id, str):
+        raise InvalidResponseError("Invalid response from server")
+    return Flag(name=name, enabled=enabled, id=flag_id)
+
+
+def _validate_context(user_context: UserContext) -> None:
+    for key, value in user_context.items():
+        if isinstance(value, bool):
+            continue
+        if isinstance(value, (str, int, float)):
+            if key == "env":
+                if not isinstance(value, str) or not _ALPHANUMERIC.match(value):
+                    raise ValueError(f"env values must be alphanumeric. Invalid value for env: {value!r}")
+            continue
+        raise ValueError(
+            f"userContext values must be of type str, int, float, or bool. Invalid value for key: {key}"
+        )
+
+
+def _cache_key(flag_id: str, params: Mapping[str, str]) -> str:
+    items = sorted(params.items())
+    query = urllib.parse.urlencode(items)
+    return f"{flag_id}?{query}"
+
+
+class Client:
+    """RocketFlag API client."""
+
+    def __init__(
+        self,
+        version: str = DEFAULT_VERSION,
+        api_url: str = DEFAULT_API_URL,
+        *,
+        ttl_seconds: Optional[float] = None,
+        opener: Optional[urllib.request.OpenerDirector] = None,
+    ) -> None:
+        self.version = version
+        self.api_url = api_url.rstrip("/")
+        self._default_ttl_ms = 0.0 if ttl_seconds is None else float(ttl_seconds) * 1000.0
+        self._cache: dict[str, tuple[Flag, float]] = {}
+        self._opener = opener or urllib.request.build_opener()
+
+    def get_flag(
+        self,
+        flag_id: str,
+        user_context: Optional[UserContext] = None,
+        *,
+        ttl_seconds: Optional[float] = None,
+    ) -> Flag:
+        if not flag_id:
+            raise ValueError("flagId is required")
+        if not isinstance(flag_id, str):
+            raise TypeError("flagId must be a string")
+
+        context: UserContext = user_context or {}
+        if not isinstance(context, Mapping):
+            raise TypeError("userContext must be an object")
+        _validate_context(context)
+
+        params = {key: str(value).lower() if isinstance(value, bool) else str(value) for key, value in context.items()}
+        path = f"{self.api_url}/{self.version}/flags/{urllib.parse.quote(flag_id, safe='')}"
+        url = f"{path}?{urllib.parse.urlencode(params)}" if params else path
+
+        effective_ttl_ms = self._default_ttl_ms if ttl_seconds is None else float(ttl_seconds) * 1000.0
+        cache_key = ""
+        if effective_ttl_ms > 0:
+            cache_key = _cache_key(flag_id, params)
+            entry = self._cache.get(cache_key)
+            if entry is not None:
+                flag, expires_at = entry
+                if expires_at > time.time() * 1000.0:
+                    return Flag(name=flag.name, enabled=flag.enabled, id=flag.id)
+                del self._cache[cache_key]
+
+        request = urllib.request.Request(url, method="GET")
+        try:
+            with self._opener.open(request) as response:
+                status = getattr(response, "status", None) or response.getcode()
+                if status != 200:
+                    status_text = getattr(response, "reason", "") or ""
+                    raise APIError(f"API request failed with status {status}", status, status_text)
+                raw = response.read()
+        except APIError:
+            raise
+        except urllib.error.HTTPError as exc:
+            raise APIError(f"API request failed with status {exc.code}", exc.code, exc.reason or "") from exc
+        except urllib.error.URLError as exc:
+            raise NetworkError(f"Network error: {exc.reason}") from exc
+        except OSError as exc:
+            raise NetworkError(f"Network error: {exc}") from exc
+
+        try:
+            payload = json.loads(raw.decode("utf-8"))
+        except (ValueError, UnicodeDecodeError) as exc:
+            raise InvalidResponseError("Failed to parse JSON response") from exc
+
+        flag = _validate_flag(payload)
+        if effective_ttl_ms > 0:
+            self._cache[cache_key] = (flag, time.time() * 1000.0 + effective_ttl_ms)
+        return flag
+
+
+def create_client(
+    version: str = DEFAULT_VERSION,
+    api_url: str = DEFAULT_API_URL,
+    ttl_seconds: Optional[float] = None,
+) -> Client:
+    """Create a client. Signature matches Node's createRocketflagClient(version, apiUrl, { ttlSeconds })."""
+    return Client(version, api_url, ttl_seconds=ttl_seconds)

rocketflag/errors.py

@@ -0,0 +1,22 @@
+"""Errors raised by the RocketFlag Python SDK."""
+
+
+class RocketFlagError(Exception):
+    """Base class for SDK errors."""
+
+
+class NetworkError(RocketFlagError):
+    """Raised when the request fails to reach the API."""
+
+
+class APIError(RocketFlagError):
+    """Raised when the API returns a non-OK HTTP status."""
+
+    def __init__(self, message: str, status: int, status_text: str = "") -> None:
+        super().__init__(message)
+        self.status = status
+        self.status_text = status_text
+
+
+class InvalidResponseError(RocketFlagError):
+    """Raised when the API response is not a valid flag object."""

rocketflag/py.typed

@@ -0,0 +1 @@
+

rocketflag-0.1.0.dist-info/METADATA

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: rocketflag
+Version: 0.1.0
+Summary: Python SDK of the RocketFlag Service
+Author: RocketFlag Developers
+License: MIT
+Project-URL: Homepage, https://rocketflag.app
+Project-URL: Repository, https://github.com/RocketFlag/python-sdk
+Project-URL: Issues, https://github.com/RocketFlag/python-sdk/issues
+Keywords: feature,flags,experiments
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# RocketFlag Python SDK
+
+Official Python SDK for [RocketFlag](https://rocketflag.app). Same evaluation API as the [Node](https://github.com/RocketFlag/node-sdk) and [Go](https://github.com/RocketFlag/go-sdk) SDKs: create a client, fetch a flag, branch on `flag.enabled`.
+
+## Installation
+
+```bash
+pip install rocketflag
+```
+
+Python 3.9+. No third-party runtime dependencies.
+
+Published releases go to [PyPI](https://pypi.org/project/rocketflag/) via GitHub Releases. For an unreleased commit:
+
+```bash
+pip install git+https://github.com/RocketFlag/python-sdk.git
+```
+
+## Basic usage
+
+```python
+from rocketflag import create_client
+
+rocketflag = create_client()  # default API URL and version (v1)
+
+flag = rocketflag.get_flag("IFldMzqP5jtv9wAL")
+if flag.enabled:
+    render_new_dashboard()
+else:
+    render_legacy_dashboard()
+```
+
+You can also construct `Client` directly:
+
+```python
+from rocketflag import Client
+
+client = Client()
+flag = client.get_flag("IFldMzqP5jtv9wAL")
+```
+
+### Custom version or API URL
+
+```python
+rocketflag = create_client("v2", "https://your-api-domain.com")
+```
+
+## Cohorts and environment
+
+```python
+flag = rocketflag.get_flag("IFldMzqP5jtv9wAL", {
+    "cohort": "beta",
+    "env": "prod",
+})
+```
+
+`env` must be alphanumeric, matching the Node SDK.
+
+## Caching
+
+Opt-in in-memory cache, keyed by flag ID **and** user context. Same behaviour as Node/Go.
+
+```python
+# Cache flag responses for 5 minutes.
+rocketflag = create_client(ttl_seconds=300)
+
+flag = rocketflag.get_flag("IFldMzqP5jtv9wAL", {"cohort": "beta"})
+
+# Force a fresh fetch.
+flag = rocketflag.get_flag("IFldMzqP5jtv9wAL", ttl_seconds=0)
+
+# Shorter TTL for one call.
+flag = rocketflag.get_flag("IFldMzqP5jtv9wAL", ttl_seconds=10)
+```
+
+Without a client default or per-call TTL, every call hits the API. The cache has no size cap; entries expire on the next lookup after TTL.
+
+## Errors
+
+```python
+from rocketflag import APIError, InvalidResponseError, NetworkError, create_client
+
+rocketflag = create_client()
+
+try:
+    flag = rocketflag.get_flag("IFldMzqP5jtv9wAL")
+except APIError as err:
+    print(f"API Error: {err.status} {err.status_text}")
+except InvalidResponseError as err:
+    print(f"Invalid Response Error: {err}")
+except NetworkError as err:
+    print(f"Network Error: {err}")
+```
+
+- `APIError` — non-OK HTTP status (includes `status` / `status_text`). A `404` means the flag ID is unknown.
+- `InvalidResponseError` — body is not JSON or not a flag object (`name`, `enabled`, `id`).
+- `NetworkError` — connection failure.
+
+## Response
+
+A successful call returns a `Flag`:
+
+```python
+Flag(name="The user-created flag name", enabled=True, id="asklWQQZdslhfsszZWkj")
+```
+
+The HTTP API may also return:
+
+1. `200` with that object
+2. `404` — flag ID not found
+3. `500` — rare server error; RocketFlag is alerted
+
+## Development
+
+```bash
+python -m pip install -e ".[dev]"
+python -m pytest
+```
+
+A container demo that hits the live API lives in [`demo/`](demo/).

rocketflag-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+rocketflag/__init__.py,sha256=imGCk95VYBVBuxGrCGl_yna7_m56qwlg9Lt2lLXEKzU,425
+rocketflag/client.py,sha256=ZrBU-wyNqyz7fl8OTY-N79srvn7C1KwFlHxnWwK9h60,5585
+rocketflag/errors.py,sha256=iq5zeIAOjwYkoC8XQkuo2GvNWFUAx_ZZInLBfgKvKNQ,614
+rocketflag/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+rocketflag-0.1.0.dist-info/licenses/LICENSE.md,sha256=nnTqnHayljxSS4sRzG22yaqrp4J8GjbuIp1fT3MrtcE,1058
+rocketflag-0.1.0.dist-info/METADATA,sha256=sBxFQ1ttnwpaCSr8qIbWLNl8Zeg7TLs1A-P-ym3K1Ag,3993
+rocketflag-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+rocketflag-0.1.0.dist-info/top_level.txt,sha256=SOYXa8LVr54deealtuW0SiTu-UVyW4wL0oAHYlH9j50,11
+rocketflag-0.1.0.dist-info/RECORD,,

rocketflag-0.1.0.dist-info/WHEEL

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

rocketflag-0.1.0.dist-info/licenses/LICENSE.md

@@ -0,0 +1,13 @@
+Copyright 2026 JK Gunnink
+
+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.

rocketflag-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+rocketflag