forkcast-sdk 0.1.0__tar.gz

forkcast_sdk-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+node_modules/
+dist/
+.forkcast/
+coverage/
+*.log
+.DS_Store
+.env
+.env.local
+*.tgz
+
+# Python
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+python/dist/
+python/build/

forkcast_sdk-0.1.0/LICENSE

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

forkcast_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.5
+Name: forkcast-sdk
+Version: 0.1.0
+Summary: Python SDK for Forkcast: self-hosted A/B testing & feature flags. Sticky bucketing identical to the JS SDK, targeting, kill switch, FastAPI and Flask integrations.
+Project-URL: Homepage, https://github.com/Alik-Agarwala/forkcast
+Project-URL: Documentation, https://github.com/Alik-Agarwala/forkcast/blob/main/docs/python.md
+Project-URL: Repository, https://github.com/Alik-Agarwala/forkcast
+Project-URL: Issues, https://github.com/Alik-Agarwala/forkcast/issues
+Project-URL: Changelog, https://github.com/Alik-Agarwala/forkcast/blob/main/CHANGELOG.md
+Author: Prantika Ghosh
+Maintainer: Alik Agarwala
+License-Expression: MIT
+License-File: LICENSE
+Keywords: a/b testing,ab-testing,experiments,fastapi,feature-flags,feature-toggles,flask,kill-switch,rollout,split-testing
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: FastAPI
+Classifier: Framework :: Flask
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: build>=1; extra == 'dev'
+Requires-Dist: fastapi>=0.100; extra == 'dev'
+Requires-Dist: flask>=2.2; extra == 'dev'
+Requires-Dist: httpx>=0.24; extra == 'dev'
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: twine>=5; extra == 'dev'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.100; extra == 'fastapi'
+Provides-Extra: flask
+Requires-Dist: flask>=2.2; extra == 'flask'
+Description-Content-Type: text/markdown
+
+# Forkcast for Python
+
+[![PyPI](https://img.shields.io/pypi/v/forkcast-sdk.svg)](https://pypi.org/project/forkcast-sdk/)
+[![Python](https://img.shields.io/pypi/pyversions/forkcast-sdk.svg)](https://pypi.org/project/forkcast-sdk/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/Alik-Agarwala/forkcast/blob/main/LICENSE)
+
+The Python SDK for [Forkcast](https://github.com/Alik-Agarwala/forkcast), the self-hosted A/B testing and feature flag tool. Use it in **FastAPI**, **Flask**, Django, scripts and workers.
+
+- Same buckets as the JavaScript SDK. A user gets the same treatment from your Python API and your React frontend.
+- Local evaluation. Config is fetched once and kept fresh in the background, so every `get_treatment()` is pure hashing with no network call.
+- Works offline. If the server is unreachable, everything falls back to `C` (control) and your app never crashes.
+- No dependencies. Only the Python standard library. FastAPI and Flask helpers are optional.
+- Typed (`py.typed`). Python 3.10+.
+
+```bash
+pip install forkcast-sdk
+```
+
+You import it as `forkcast`.
+
+## Quick start
+
+1. Start a Forkcast server and dashboard (needs Node.js 18+):
+
+   ```bash
+   npx forkcast start
+   ```
+
+   Open http://localhost:4400, create an experiment (say `new-checkout`) and copy a client key from **Environments**.
+
+2. Ask for a treatment in Python:
+
+   ```python
+   from forkcast import Forkcast
+
+   forkcast = Forkcast(
+       api_url="http://localhost:4400",
+       client_key="fc_prod_...",  # from the dashboard
+   )
+
+   fc = forkcast.for_user({"id": "user-42", "country": "IN", "plan": "pro"})
+
+   if fc.get_treatment("new-checkout") == "T1":
+       show_one_click_checkout()
+   else:  # "C", the control
+       show_cart_page()
+
+   fc.track("purchase", value=49.99)  # conversion for the results page
+   ```
+
+3. Change traffic, targeting or the kill switch in the dashboard. Python picks it up within 30 seconds (or instantly with `realtime=True`). There's no redeploy.
+
+## FastAPI
+
+```python
+from fastapi import Depends, FastAPI, Request
+from forkcast import Forkcast, ScopedForkcast
+from forkcast.integrations.fastapi import forkcast_dependency, forkcast_lifespan
+
+forkcast = Forkcast(api_url="http://localhost:4400", client_key="fc_prod_...")
+
+
+def current_user(request: Request) -> dict:
+    return {"id": request.headers.get("x-user-id"), "country": request.headers.get("cf-ipcountry")}
+
+
+get_forkcast = forkcast_dependency(forkcast, current_user)
+app = FastAPI(lifespan=forkcast_lifespan(forkcast))  # flushes events on shutdown
+
+
+@app.get("/checkout")
+def checkout(fc: ScopedForkcast = Depends(get_forkcast)):
+    return {"one_click": fc.get_treatment("new-checkout") == "T1"}
+```
+
+## Flask
+
+```python
+from flask import Flask, request, session
+from forkcast import Forkcast
+from forkcast.integrations.flask import FlaskForkcast, current_forkcast
+
+app = Flask(__name__)
+forkcast = Forkcast(api_url="http://localhost:4400", client_key="fc_prod_...")
+FlaskForkcast(
+    app,
+    forkcast,
+    get_user=lambda: {
+        "id": session.get("user_id"),
+        "country": request.headers.get("CF-IPCountry"),
+    },
+)
+
+
+@app.get("/checkout")
+def checkout():
+    if current_forkcast.get_treatment("new-checkout") == "T1":
+        return "one-click checkout"
+    return "cart page"
+```
+
+In Jinja templates you can write `{% if forkcast.is_enabled("dark-mode") %}`.
+
+## More
+
+- Full Python guide, covering every option and method, Django, gunicorn, testing and local mode: [docs/python.md](https://github.com/Alik-Agarwala/forkcast/blob/main/docs/python.md)
+- Concepts (C/T1/T2, traffic, targeting, environments): [docs/concepts.md](https://github.com/Alik-Agarwala/forkcast/blob/main/docs/concepts.md)
+- Main project, JavaScript SDK and dashboard: [github.com/Alik-Agarwala/forkcast](https://github.com/Alik-Agarwala/forkcast)
+
+MIT licensed.

forkcast_sdk-0.1.0/README.md

@@ -0,0 +1,110 @@
+# Forkcast for Python
+
+[![PyPI](https://img.shields.io/pypi/v/forkcast-sdk.svg)](https://pypi.org/project/forkcast-sdk/)
+[![Python](https://img.shields.io/pypi/pyversions/forkcast-sdk.svg)](https://pypi.org/project/forkcast-sdk/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/Alik-Agarwala/forkcast/blob/main/LICENSE)
+
+The Python SDK for [Forkcast](https://github.com/Alik-Agarwala/forkcast), the self-hosted A/B testing and feature flag tool. Use it in **FastAPI**, **Flask**, Django, scripts and workers.
+
+- Same buckets as the JavaScript SDK. A user gets the same treatment from your Python API and your React frontend.
+- Local evaluation. Config is fetched once and kept fresh in the background, so every `get_treatment()` is pure hashing with no network call.
+- Works offline. If the server is unreachable, everything falls back to `C` (control) and your app never crashes.
+- No dependencies. Only the Python standard library. FastAPI and Flask helpers are optional.
+- Typed (`py.typed`). Python 3.10+.
+
+```bash
+pip install forkcast-sdk
+```
+
+You import it as `forkcast`.
+
+## Quick start
+
+1. Start a Forkcast server and dashboard (needs Node.js 18+):
+
+   ```bash
+   npx forkcast start
+   ```
+
+   Open http://localhost:4400, create an experiment (say `new-checkout`) and copy a client key from **Environments**.
+
+2. Ask for a treatment in Python:
+
+   ```python
+   from forkcast import Forkcast
+
+   forkcast = Forkcast(
+       api_url="http://localhost:4400",
+       client_key="fc_prod_...",  # from the dashboard
+   )
+
+   fc = forkcast.for_user({"id": "user-42", "country": "IN", "plan": "pro"})
+
+   if fc.get_treatment("new-checkout") == "T1":
+       show_one_click_checkout()
+   else:  # "C", the control
+       show_cart_page()
+
+   fc.track("purchase", value=49.99)  # conversion for the results page
+   ```
+
+3. Change traffic, targeting or the kill switch in the dashboard. Python picks it up within 30 seconds (or instantly with `realtime=True`). There's no redeploy.
+
+## FastAPI
+
+```python
+from fastapi import Depends, FastAPI, Request
+from forkcast import Forkcast, ScopedForkcast
+from forkcast.integrations.fastapi import forkcast_dependency, forkcast_lifespan
+
+forkcast = Forkcast(api_url="http://localhost:4400", client_key="fc_prod_...")
+
+
+def current_user(request: Request) -> dict:
+    return {"id": request.headers.get("x-user-id"), "country": request.headers.get("cf-ipcountry")}
+
+
+get_forkcast = forkcast_dependency(forkcast, current_user)
+app = FastAPI(lifespan=forkcast_lifespan(forkcast))  # flushes events on shutdown
+
+
+@app.get("/checkout")
+def checkout(fc: ScopedForkcast = Depends(get_forkcast)):
+    return {"one_click": fc.get_treatment("new-checkout") == "T1"}
+```
+
+## Flask
+
+```python
+from flask import Flask, request, session
+from forkcast import Forkcast
+from forkcast.integrations.flask import FlaskForkcast, current_forkcast
+
+app = Flask(__name__)
+forkcast = Forkcast(api_url="http://localhost:4400", client_key="fc_prod_...")
+FlaskForkcast(
+    app,
+    forkcast,
+    get_user=lambda: {
+        "id": session.get("user_id"),
+        "country": request.headers.get("CF-IPCountry"),
+    },
+)
+
+
+@app.get("/checkout")
+def checkout():
+    if current_forkcast.get_treatment("new-checkout") == "T1":
+        return "one-click checkout"
+    return "cart page"
+```
+
+In Jinja templates you can write `{% if forkcast.is_enabled("dark-mode") %}`.
+
+## More
+
+- Full Python guide, covering every option and method, Django, gunicorn, testing and local mode: [docs/python.md](https://github.com/Alik-Agarwala/forkcast/blob/main/docs/python.md)
+- Concepts (C/T1/T2, traffic, targeting, environments): [docs/concepts.md](https://github.com/Alik-Agarwala/forkcast/blob/main/docs/concepts.md)
+- Main project, JavaScript SDK and dashboard: [github.com/Alik-Agarwala/forkcast](https://github.com/Alik-Agarwala/forkcast)
+
+MIT licensed.

forkcast_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,97 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "forkcast-sdk"
+dynamic = ["version"]
+description = "Python SDK for Forkcast: self-hosted A/B testing & feature flags. Sticky bucketing identical to the JS SDK, targeting, kill switch, FastAPI and Flask integrations."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "Prantika Ghosh" }]
+maintainers = [{ name = "Alik Agarwala" }]
+keywords = [
+  "ab-testing",
+  "a/b testing",
+  "experiments",
+  "feature-flags",
+  "feature-toggles",
+  "split-testing",
+  "rollout",
+  "kill-switch",
+  "fastapi",
+  "flask",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Framework :: FastAPI",
+  "Framework :: Flask",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Software Development :: Libraries",
+  "Typing :: Typed",
+]
+dependencies = []
+
+[project.optional-dependencies]
+fastapi = ["fastapi>=0.100"]
+flask = ["flask>=2.2"]
+dev = [
+  "pytest>=7",
+  "fastapi>=0.100",
+  "httpx>=0.24",
+  "flask>=2.2",
+  "ruff>=0.5",
+  "mypy>=1.8",
+  "build>=1",
+  "twine>=5",
+]
+
+[project.urls]
+Homepage = "https://github.com/Alik-Agarwala/forkcast"
+Documentation = "https://github.com/Alik-Agarwala/forkcast/blob/main/docs/python.md"
+Repository = "https://github.com/Alik-Agarwala/forkcast"
+Issues = "https://github.com/Alik-Agarwala/forkcast/issues"
+Changelog = "https://github.com/Alik-Agarwala/forkcast/blob/main/CHANGELOG.md"
+
+[tool.hatch.version]
+path = "src/forkcast/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/forkcast"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/forkcast", "tests", "README.md", "LICENSE", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+filterwarnings = ["ignore:Using `httpx` with `starlette.testclient`"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP", "BLE"]
+ignore = ["UP006", "UP007", "UP035", "UP045"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["B008"]
+"../examples/*" = ["B008"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+packages = ["forkcast"]
+mypy_path = "src"

forkcast_sdk-0.1.0/src/forkcast/__init__.py

@@ -0,0 +1,52 @@
+"""Forkcast: self-hosted A/B testing and feature flags.
+
+Python SDK for the Forkcast server. Evaluation is local and deterministic, and
+buckets users exactly like the JavaScript SDK, so a user gets the same
+treatment from your Python API and your React frontend.
+
+    from forkcast import Forkcast
+
+    forkcast = Forkcast(api_url="http://localhost:4400", client_key="fc_prod_...")
+    fc = forkcast.for_user({"id": "user-42", "country": "IN"})
+    if fc.get_treatment("new-checkout") == "T1":
+        ...
+
+Framework helpers live in ``forkcast.integrations.fastapi`` and
+``forkcast.integrations.flask``.
+"""
+
+from ._version import __version__
+from .client import (
+    OVERRIDE_QUERY_PARAM,
+    Forkcast,
+    ForkcastError,
+    ScopedForkcast,
+    create_forkcast,
+    parse_override_param,
+)
+from .evaluate import evaluate, pick_variant
+from .hashing import BUCKETS, bucket_of, murmur3
+from .targeting import OPERATORS, compare_semver, get_attribute, match_audience, match_condition
+from .types import CONTROL, Evaluation
+
+__all__ = [
+    "BUCKETS",
+    "CONTROL",
+    "OPERATORS",
+    "OVERRIDE_QUERY_PARAM",
+    "Evaluation",
+    "Forkcast",
+    "ForkcastError",
+    "ScopedForkcast",
+    "__version__",
+    "bucket_of",
+    "compare_semver",
+    "create_forkcast",
+    "evaluate",
+    "get_attribute",
+    "match_audience",
+    "match_condition",
+    "murmur3",
+    "parse_override_param",
+    "pick_variant",
+]

forkcast_sdk-0.1.0/src/forkcast/_js.py

@@ -0,0 +1,138 @@
+"""JavaScript value semantics needed for exact parity with the JS SDK.
+
+Targeting rules are evaluated by both SDKs, so a condition such as
+``plan eq "pro"`` or ``age gte 18`` must give the same answer in Python and
+JavaScript. JS converts values with ``String(x)`` and ``Number(x)``; these
+helpers reproduce those conversions for JSON-like Python values.
+"""
+
+from __future__ import annotations
+
+import math
+import re
+from decimal import Decimal
+from typing import Any
+
+
+class _Undefined:
+    """Stand-in for JavaScript ``undefined`` (a missing attribute or value)."""
+
+    _instance: _Undefined | None = None
+
+    def __new__(cls) -> _Undefined:
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __repr__(self) -> str:
+        return "UNDEFINED"
+
+    def __bool__(self) -> bool:
+        return False
+
+
+UNDEFINED: Any = _Undefined()
+
+
+def is_nullish(value: Any) -> bool:
+    """``value == null`` in JavaScript (``null`` or ``undefined``)."""
+    return value is None or value is UNDEFINED
+
+
+def _number_to_string(value: float) -> str:
+    """``Number.prototype.toString()`` for a finite, non-zero float."""
+    sign = "-" if value < 0 else ""
+    # repr() gives the shortest round-tripping digits, exactly like JS.
+    _, digits_tuple, exponent = Decimal(repr(abs(value))).as_tuple()
+    digits = "".join(str(d) for d in digits_tuple).rstrip("0") or "0"
+    k = len(digits)
+    # Trailing zeros were stripped, so recompute the decimal point position.
+    n = int(exponent) + len("".join(str(d) for d in digits_tuple))
+    if k <= n <= 21:
+        return sign + digits + "0" * (n - k)
+    if 0 < n <= 21:
+        return sign + digits[:n] + "." + digits[n:]
+    if -6 < n <= 0:
+        return sign + "0." + "0" * (-n) + digits
+    e = n - 1
+    mantissa = digits[0] + ("." + digits[1:] if k > 1 else "")
+    return f"{sign}{mantissa}e{'+' if e > 0 else '-'}{abs(e)}"
+
+
+def js_string(value: Any) -> str:
+    """``String(value)`` in JavaScript."""
+    if value is UNDEFINED:
+        return "undefined"
+    if value is None:
+        return "null"
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, int):
+        # JSON numbers are doubles in JS, so huge integers lose precision there.
+        return str(value) if abs(value) <= 2**53 else js_string(float(value))
+    if isinstance(value, float):
+        if math.isnan(value):
+            return "NaN"
+        if math.isinf(value):
+            return "Infinity" if value > 0 else "-Infinity"
+        if value == 0:
+            return "0"
+        return _number_to_string(value)
+    if isinstance(value, str):
+        return value
+    if isinstance(value, (list, tuple)):
+        return ",".join("" if is_nullish(v) else js_string(v) for v in value)
+    if isinstance(value, dict):
+        return "[object Object]"
+    return str(value)
+
+
+_DECIMAL = re.compile(r"^[+-]?(?:\d+\.?\d*(?:[eE][+-]?\d+)?|\.\d+(?:[eE][+-]?\d+)?)$")
+_PREFIXED = {"0x": 16, "0o": 8, "0b": 2}
+
+
+def js_number(value: Any) -> float:
+    """``Number(value)`` in JavaScript."""
+    if value is UNDEFINED:
+        return math.nan
+    if value is None:
+        return 0.0
+    if isinstance(value, bool):
+        return 1.0 if value else 0.0
+    if isinstance(value, (int, float)):
+        try:
+            return float(value)
+        except OverflowError:
+            return math.inf if value > 0 else -math.inf
+    if isinstance(value, str):
+        s = value.strip()
+        if s == "":
+            return 0.0
+        if s in ("Infinity", "+Infinity"):
+            return math.inf
+        if s == "-Infinity":
+            return -math.inf
+        base = _PREFIXED.get(s[:2].lower())
+        if base:
+            try:
+                return float(int(s[2:], base))
+            except ValueError:
+                return math.nan
+        if _DECIMAL.match(s):
+            try:
+                return float(s)
+            except (ValueError, OverflowError):
+                return math.nan
+        return math.nan
+    if isinstance(value, (list, tuple)):
+        return js_number(js_string(value))
+    return math.nan
+
+
+_LEADING_INT = re.compile(r"^\s*([+-]?\d+)")
+
+
+def js_parse_int(value: str) -> int:
+    """``parseInt(value, 10) || 0`` in JavaScript."""
+    m = _LEADING_INT.match(value)
+    return int(m.group(1)) if m else 0

forkcast_sdk-0.1.0/src/forkcast/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"