rocketflag 0.1.0__tar.gz

rocketflag-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,120 @@
+# 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/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "rocketflag"
+version = "0.1.0"
+description = "Python SDK of the RocketFlag Service"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+authors = [{ name = "RocketFlag Developers" }]
+keywords = ["feature", "flags", "experiments"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://rocketflag.app"
+Repository = "https://github.com/RocketFlag/python-sdk"
+Issues = "https://github.com/RocketFlag/python-sdk/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

rocketflag-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

rocketflag-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/rocketflag/py.typed

@@ -0,0 +1 @@
+

rocketflag-0.1.0/src/rocketflag.egg-info/PKG-INFO

@@ -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/src/rocketflag.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE.md
+README.md
+pyproject.toml
+src/rocketflag/__init__.py
+src/rocketflag/client.py
+src/rocketflag/errors.py
+src/rocketflag/py.typed
+src/rocketflag.egg-info/PKG-INFO
+src/rocketflag.egg-info/SOURCES.txt
+src/rocketflag.egg-info/dependency_links.txt
+src/rocketflag.egg-info/requires.txt
+src/rocketflag.egg-info/top_level.txt
+tests/test_client.py

rocketflag-0.1.0/src/rocketflag.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

rocketflag-0.1.0/src/rocketflag.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[dev]
+pytest>=8

rocketflag-0.1.0/src/rocketflag.egg-info/top_level.txt

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

rocketflag-0.1.0/tests/test_client.py

@@ -0,0 +1,139 @@
+import json
+import threading
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from urllib.parse import parse_qs, urlparse
+
+import pytest
+
+from rocketflag import (
+    APIError,
+    Client,
+    Flag,
+    InvalidResponseError,
+    NetworkError,
+    create_client,
+)
+
+
+class FlagHandler(BaseHTTPRequestHandler):
+    responses = {}
+    hits = 0
+
+    def do_GET(self):
+        type(self).hits += 1
+        parsed = urlparse(self.path)
+        body, status = self.responses.get(parsed.path, (b"{}", 404))
+        if callable(body):
+            body, status = body(parsed)
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json")
+        self.end_headers()
+        self.wfile.write(body)
+
+    def log_message(self, format, *args):
+        return
+
+
+@pytest.fixture
+def server():
+    FlagHandler.hits = 0
+    FlagHandler.responses = {}
+    httpd = HTTPServer(("127.0.0.1", 0), FlagHandler)
+    thread = threading.Thread(target=httpd.serve_forever, daemon=True)
+    thread.start()
+    host, port = httpd.server_address
+    yield f"http://{host}:{port}", FlagHandler
+    httpd.shutdown()
+    httpd.server_close()
+
+
+def flag_json(**overrides):
+    payload = {"name": "signup", "enabled": True, "id": "abc123"}
+    payload.update(overrides)
+    return json.dumps(payload).encode()
+
+
+def test_get_flag_success(server):
+    base, handler = server
+    handler.responses["/v1/flags/abc123"] = (flag_json(), 200)
+    client = create_client(api_url=base)
+    flag = client.get_flag("abc123")
+    assert flag == Flag(name="signup", enabled=True, id="abc123")
+    assert flag.enabled is True
+
+
+def test_passes_context_as_query_string(server):
+    base, handler = server
+    seen = {}
+
+    def body(parsed):
+        seen["query"] = parse_qs(parsed.query)
+        return flag_json(), 200
+
+    handler.responses["/v1/flags/abc123"] = (body, 200)
+    client = Client(api_url=base)
+    client.get_flag("abc123", {"cohort": "beta", "env": "prod"})
+    assert seen["query"]["cohort"] == ["beta"]
+    assert seen["query"]["env"] == ["prod"]
+
+
+def test_cache_hits_on_second_call(server):
+    base, handler = server
+    handler.responses["/v1/flags/abc123"] = (flag_json(), 200)
+    client = create_client(api_url=base, ttl_seconds=60)
+    first = client.get_flag("abc123", {"cohort": "beta"})
+    second = client.get_flag("abc123", {"cohort": "beta"})
+    assert first == second
+    assert handler.hits == 1
+
+
+def test_ttl_zero_bypasses_cache(server):
+    base, handler = server
+    handler.responses["/v1/flags/abc123"] = (flag_json(), 200)
+    client = create_client(api_url=base, ttl_seconds=60)
+    client.get_flag("abc123")
+    client.get_flag("abc123", ttl_seconds=0)
+    assert handler.hits == 2
+
+
+def test_api_error_on_404(server):
+    base, handler = server
+    handler.responses["/v1/flags/missing"] = (b"not found", 404)
+    client = create_client(api_url=base)
+    with pytest.raises(APIError) as exc:
+        client.get_flag("missing")
+    assert exc.value.status == 404
+
+
+def test_invalid_json(server):
+    base, handler = server
+    handler.responses["/v1/flags/abc123"] = (b"not-json", 200)
+    client = create_client(api_url=base)
+    with pytest.raises(InvalidResponseError):
+        client.get_flag("abc123")
+
+
+def test_invalid_shape(server):
+    base, handler = server
+    handler.responses["/v1/flags/abc123"] = (b'{"name": 1}', 200)
+    client = create_client(api_url=base)
+    with pytest.raises(InvalidResponseError):
+        client.get_flag("abc123")
+
+
+def test_requires_flag_id():
+    client = create_client()
+    with pytest.raises(ValueError):
+        client.get_flag("")
+
+
+def test_env_must_be_alphanumeric():
+    client = create_client()
+    with pytest.raises(ValueError, match="alphanumeric"):
+        client.get_flag("abc", {"env": "prod-1"})
+
+
+def test_network_error():
+    client = create_client(api_url="http://127.0.0.1:1")
+    with pytest.raises(NetworkError):
+        client.get_flag("abc123")