togul 0.1.0__py3-none-any.whl

togul/__init__.py

@@ -0,0 +1,25 @@
+"""Official Python SDK for Togul feature flags and remote config."""
+
+from __future__ import annotations
+
+from .async_client import AsyncTogulClient
+from .client import TogulClient
+from .config import DEFAULT_BASE_URL, Config
+from .errors import TogulAPIError, TogulError
+from .result import EvaluateResult, ValueType
+from .stream import AsyncTogulStreamClient, TogulStreamClient
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AsyncTogulClient",
+    "AsyncTogulStreamClient",
+    "Config",
+    "DEFAULT_BASE_URL",
+    "EvaluateResult",
+    "TogulAPIError",
+    "TogulClient",
+    "TogulError",
+    "TogulStreamClient",
+    "ValueType",
+]

togul/_sse.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, Optional
+
+_DATA_PREFIX = "data: "
+
+
+def parse_sse_event(line: str) -> Optional[Dict[str, Any]]:
+    """Decode one SSE line into an event object.
+
+    Returns ``None`` for anything that is not a ``data:`` line carrying a
+    JSON object: heartbeat comments (``: heartbeat``), blank lines, other
+    SSE fields, malformed JSON, and JSON that is not an object. The Go and
+    PHP SDKs skip those cases identically.
+    """
+    if not line.startswith(_DATA_PREFIX):
+        return None
+
+    raw = line[len(_DATA_PREFIX) :].strip()
+    if not raw:
+        return None
+
+    try:
+        event = json.loads(raw)
+    except ValueError:
+        return None
+
+    return event if isinstance(event, dict) else None

togul/_transport.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Mapping, Optional
+
+from .config import Config
+from .errors import TogulAPIError, TogulError
+from .result import EvaluateResult
+
+EVALUATE_PATH = "/api/v1/evaluate"
+STREAM_PATH = "/api/v1/stream"
+
+
+def cache_key_for(
+    flag_key: str,
+    environment: str,
+    context: Optional[Mapping[str, str]],
+) -> str:
+    """Build the cache key for one evaluation.
+
+    Format: ``flag_key:environment`` followed by ``:key=value`` for every
+    context pair, with keys sorted so call order never changes the key.
+    Identical to ``cacheKeyFor`` (Go), ``cacheKey`` (JS) and
+    ``buildCacheKey`` (PHP).
+    """
+    parts = [flag_key, environment]
+    if context:
+        for key in sorted(context):
+            parts.append(f"{key}={context[key]}")
+    return ":".join(parts)
+
+
+def build_request(
+    config: Config,
+    flag_key: str,
+    context: Optional[Mapping[str, str]],
+) -> Dict[str, Any]:
+    return {
+        "flag_key": flag_key,
+        "environment_key": config.environment,
+        "context": dict(context) if context else {},
+    }
+
+
+def should_retry(status_code: int) -> bool:
+    return status_code == 429 or status_code >= 500
+
+
+def backoff_seconds(attempt: int) -> float:
+    return attempt * 0.1
+
+
+def parse_result(payload: Any, flag_key: str) -> EvaluateResult:
+    if not isinstance(payload, dict):
+        payload = {}
+    return EvaluateResult(
+        flag_key=str(payload.get("flag_key") or flag_key),
+        enabled=bool(payload.get("enabled", False)),
+        value_type=str(payload.get("value_type") or ""),
+        value=payload.get("value"),
+        reason=str(payload.get("reason") or ""),
+    )
+
+
+def api_error_from(status_code: int, body: Any) -> TogulAPIError:
+    message = f"Unexpected status {status_code}"
+    error_code: Optional[str] = None
+    if isinstance(body, dict):
+        if body.get("message"):
+            message = str(body["message"])
+        if body.get("code"):
+            error_code = str(body["code"])
+    return TogulAPIError(message, status_code=status_code, error_code=error_code)
+
+
+def require_api_key(config: Config) -> None:
+    if not config.api_key.strip():
+        raise TogulError("togul: api_key is required")

togul/async_client.py

@@ -0,0 +1,120 @@
+from __future__ import annotations
+
+import asyncio
+from types import TracebackType
+from typing import List, Mapping, Optional, Type
+
+import httpx
+
+from . import _transport as t
+from .cache import TTLCache
+from .client import CacheListener, safe_json
+from .config import Config
+from .errors import TogulError
+from .result import EvaluateResult
+
+
+class AsyncTogulClient:
+    """Asyncio Togul client for FastAPI, Starlette and other ASGI apps.
+
+    ``invalidate_cache`` and ``invalidate_flag`` stay synchronous: they only
+    touch the in-memory cache under a lock, so awaiting them would buy
+    nothing.
+    """
+
+    def __init__(
+        self,
+        config: Config,
+        http_client: Optional[httpx.AsyncClient] = None,
+    ) -> None:
+        self._config = config
+        self._owns_http = http_client is None
+        self._http = http_client or httpx.AsyncClient(
+            base_url=config.base_url,
+            timeout=config.timeout,
+        )
+        self._cache = TTLCache(config.cache_ttl)
+        self._listeners: List[CacheListener] = []
+
+    @property
+    def config(self) -> Config:
+        return self._config
+
+    @property
+    def cache(self) -> TTLCache:
+        return self._cache
+
+    async def evaluate(
+        self,
+        flag_key: str,
+        context: Optional[Mapping[str, str]] = None,
+    ) -> EvaluateResult:
+        key = t.cache_key_for(flag_key, self._config.environment, context)
+        cached = self._cache.get(key)
+        if cached is not None:
+            return cached
+
+        result = await self._fetch(flag_key, context)
+        self._cache.set(key, result)
+        return result
+
+    def invalidate_cache(self) -> None:
+        self._cache.flush()
+        self._notify("")
+
+    def invalidate_flag(self, flag_key: str) -> None:
+        self._cache.invalidate_flag(flag_key)
+        self._notify(flag_key)
+
+    def on_cache_invalidated(self, listener: CacheListener) -> None:
+        self._listeners.append(listener)
+
+    async def aclose(self) -> None:
+        if self._owns_http:
+            await self._http.aclose()
+
+    async def __aenter__(self) -> AsyncTogulClient:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: Optional[Type[BaseException]],
+        exc: Optional[BaseException],
+        tb: Optional[TracebackType],
+    ) -> None:
+        await self.aclose()
+
+    async def _fetch(
+        self,
+        flag_key: str,
+        context: Optional[Mapping[str, str]],
+    ) -> EvaluateResult:
+        t.require_api_key(self._config)
+        payload = t.build_request(self._config, flag_key, context)
+        headers = {"X-API-Key": self._config.api_key}
+        last_error: Optional[BaseException] = None
+
+        for attempt in range(self._config.retry_count):
+            if attempt > 0:
+                await asyncio.sleep(t.backoff_seconds(attempt))
+
+            try:
+                response = await self._http.post(t.EVALUATE_PATH, json=payload, headers=headers)
+            except httpx.HTTPError as exc:
+                last_error = exc
+                continue
+
+            if response.status_code >= 400:
+                error = t.api_error_from(response.status_code, safe_json(response))
+                if not t.should_retry(response.status_code):
+                    raise error
+                last_error = error
+                continue
+
+            return t.parse_result(safe_json(response), flag_key)
+
+        raise TogulError(f"togul: all retries failed: {last_error}") from last_error
+
+    def _notify(self, flag_key: str) -> None:
+        for listener in self._listeners:
+            listener(flag_key)

togul/cache.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+import threading
+import time
+from typing import Dict, NamedTuple, Optional
+
+from .result import EvaluateResult
+
+
+class _Entry(NamedTuple):
+    result: EvaluateResult
+    expires_at: float
+
+
+class TTLCache:
+    """An in-memory, thread-safe cache of evaluation results.
+
+    Eviction is lazy: an entry is dropped when it is read after expiry, or
+    when it carries a blank ``value_type`` (a malformed or legacy payload).
+    This mirrors the Go, JS and PHP SDKs exactly.
+    """
+
+    def __init__(self, ttl: float) -> None:
+        self._ttl = ttl
+        self._store: Dict[str, _Entry] = {}
+        self._lock = threading.RLock()
+
+    def get(self, key: str) -> Optional[EvaluateResult]:
+        with self._lock:
+            entry = self._store.get(key)
+            if entry is None:
+                return None
+            if time.monotonic() > entry.expires_at:
+                del self._store[key]
+                return None
+            if entry.result.value_type == "":
+                del self._store[key]
+                return None
+            return entry.result
+
+    def set(self, key: str, result: EvaluateResult) -> None:
+        with self._lock:
+            self._store[key] = _Entry(result, time.monotonic() + self._ttl)
+
+    def flush(self) -> None:
+        with self._lock:
+            self._store.clear()
+
+    def invalidate_flag(self, flag_key: str) -> None:
+        prefix = flag_key + ":"
+        with self._lock:
+            for key in [k for k in self._store if k.startswith(prefix)]:
+                del self._store[key]

togul/client.py

@@ -0,0 +1,125 @@
+from __future__ import annotations
+
+import time
+from types import TracebackType
+from typing import Any, Callable, List, Mapping, Optional, Type
+
+import httpx
+
+from . import _transport as t
+from .cache import TTLCache
+from .config import Config
+from .errors import TogulError
+from .result import EvaluateResult
+
+CacheListener = Callable[[str], None]
+
+
+def safe_json(response: httpx.Response) -> Any:
+    """Decode a response body, returning None when it is not JSON."""
+    try:
+        return response.json()
+    except ValueError:
+        return None
+
+
+class TogulClient:
+    """Synchronous Togul client.
+
+    Use this from Django, Celery, scripts, and any other blocking context.
+    For asyncio applications (FastAPI, Starlette) use ``AsyncTogulClient``.
+    """
+
+    def __init__(self, config: Config, http_client: Optional[httpx.Client] = None) -> None:
+        self._config = config
+        self._owns_http = http_client is None
+        self._http = http_client or httpx.Client(
+            base_url=config.base_url,
+            timeout=config.timeout,
+        )
+        self._cache = TTLCache(config.cache_ttl)
+        self._listeners: List[CacheListener] = []
+
+    @property
+    def config(self) -> Config:
+        return self._config
+
+    @property
+    def cache(self) -> TTLCache:
+        """The cache this client reads. A stream client invalidates it."""
+        return self._cache
+
+    def evaluate(
+        self,
+        flag_key: str,
+        context: Optional[Mapping[str, str]] = None,
+    ) -> EvaluateResult:
+        key = t.cache_key_for(flag_key, self._config.environment, context)
+        cached = self._cache.get(key)
+        if cached is not None:
+            return cached
+
+        result = self._fetch(flag_key, context)
+        self._cache.set(key, result)
+        return result
+
+    def invalidate_cache(self) -> None:
+        self._cache.flush()
+        self._notify("")
+
+    def invalidate_flag(self, flag_key: str) -> None:
+        self._cache.invalidate_flag(flag_key)
+        self._notify(flag_key)
+
+    def on_cache_invalidated(self, listener: CacheListener) -> None:
+        self._listeners.append(listener)
+
+    def close(self) -> None:
+        if self._owns_http:
+            self._http.close()
+
+    def __enter__(self) -> TogulClient:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: Optional[Type[BaseException]],
+        exc: Optional[BaseException],
+        tb: Optional[TracebackType],
+    ) -> None:
+        self.close()
+
+    def _fetch(
+        self,
+        flag_key: str,
+        context: Optional[Mapping[str, str]],
+    ) -> EvaluateResult:
+        t.require_api_key(self._config)
+        payload = t.build_request(self._config, flag_key, context)
+        headers = {"X-API-Key": self._config.api_key}
+        last_error: Optional[BaseException] = None
+
+        for attempt in range(self._config.retry_count):
+            if attempt > 0:
+                time.sleep(t.backoff_seconds(attempt))
+
+            try:
+                response = self._http.post(t.EVALUATE_PATH, json=payload, headers=headers)
+            except httpx.HTTPError as exc:
+                last_error = exc
+                continue
+
+            if response.status_code >= 400:
+                error = t.api_error_from(response.status_code, safe_json(response))
+                if not t.should_retry(response.status_code):
+                    raise error
+                last_error = error
+                continue
+
+            return t.parse_result(safe_json(response), flag_key)
+
+        raise TogulError(f"togul: all retries failed: {last_error}") from last_error
+
+    def _notify(self, flag_key: str) -> None:
+        for listener in self._listeners:
+            listener(flag_key)

togul/config.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+import dataclasses
+
+DEFAULT_BASE_URL = "https://api.togul.io"
+
+
+@dataclasses.dataclass(frozen=True)
+class Config:
+    """Connection and caching settings for a Togul client.
+
+    Args:
+        api_key: Environment-scoped API key (``server`` or ``sdk`` scope to
+            evaluate, ``sdk`` or ``stream`` scope to stream).
+        environment: Environment key, e.g. ``"production"``.
+        timeout: HTTP request timeout in seconds.
+        cache_ttl: How long an evaluation result stays cached, in seconds.
+        retry_count: Total request attempts, not extra retries. ``2`` means
+            the SDK issues at most two requests.
+        base_url: API origin. Trailing slashes are stripped.
+    """
+
+    api_key: str
+    environment: str
+    timeout: float = 5.0
+    cache_ttl: float = 30.0
+    retry_count: int = 2
+    base_url: str = DEFAULT_BASE_URL
+
+    def __post_init__(self) -> None:
+        normalized = self.base_url.rstrip("/") or DEFAULT_BASE_URL
+        object.__setattr__(self, "base_url", normalized)

togul/contrib/__init__.py

@@ -0,0 +1,3 @@
+"""Framework integrations. Each module imports its framework lazily."""
+
+from __future__ import annotations

togul/contrib/django.py

@@ -0,0 +1,138 @@
+from __future__ import annotations
+
+import functools
+from typing import Any, Callable, Dict, Optional, TypeVar, cast
+
+from django.conf import settings
+from django.core.exceptions import ImproperlyConfigured
+from django.http import Http404
+from django.utils.module_loading import import_string
+
+from ..client import TogulClient
+from ..config import Config
+
+_client: Optional[TogulClient] = None
+
+ContextBuilder = Callable[[Any], Dict[str, str]]
+ViewFunc = TypeVar("ViewFunc", bound=Callable[..., Any])
+
+
+def build_context(request: Any) -> Dict[str, str]:
+    """Map a Django request onto the flag evaluation context.
+
+    Maps the authenticated user's primary key to ``user_id`` and nothing
+    else, matching ``togul-laravel``'s middleware. An anonymous request
+    yields an empty context rather than a blank ``user_id``, so its cache
+    key stays ``flag:environment`` and rule matching never sees a
+    present-but-empty attribute.
+
+    Applications that need more — a country, a plan, an experiment cohort —
+    point ``settings.TOGUL["CONTEXT_BUILDER"]`` at their own function
+    instead of editing this one. Every value must be a string: the API
+    types ``context`` as ``additionalProperties: {type: string}``.
+    """
+    context: Dict[str, str] = {}
+
+    user = getattr(request, "user", None)
+    if user is not None and getattr(user, "is_authenticated", False):
+        context["user_id"] = str(user.pk)
+
+    return context
+
+
+def _settings() -> Dict[str, Any]:
+    raw = getattr(settings, "TOGUL", None)
+    if not raw or not raw.get("API_KEY") or not raw.get("ENVIRONMENT"):
+        raise ImproperlyConfigured("settings.TOGUL must define at least API_KEY and ENVIRONMENT")
+    return dict(raw)
+
+
+def get_client() -> TogulClient:
+    """Return the process-wide Togul client, building it on first use.
+
+    ``base_url`` is intentionally not read from settings: like
+    ``togul-laravel/config/togul.php``, the framework layer exposes only the
+    key, environment, timeout, TTL and retry count. Construct a ``Config``
+    directly to point at a non-production origin.
+    """
+    global _client
+    if _client is None:
+        raw = _settings()
+        _client = TogulClient(
+            Config(
+                api_key=raw["API_KEY"],
+                environment=raw["ENVIRONMENT"],
+                timeout=raw.get("TIMEOUT", 5.0),
+                cache_ttl=raw.get("CACHE_TTL", 30.0),
+                retry_count=raw.get("RETRY_COUNT", 2),
+            )
+        )
+    return _client
+
+
+def reset_client() -> None:
+    """Drop the cached client. Useful in tests and after a settings reload."""
+    global _client
+    if _client is not None:
+        _client.close()
+    _client = None
+
+
+def _resolve_context_builder() -> ContextBuilder:
+    raw = getattr(settings, "TOGUL", None) or {}
+    builder = raw.get("CONTEXT_BUILDER")
+    if isinstance(builder, str):
+        resolved: ContextBuilder = import_string(builder)
+        return resolved
+    if callable(builder):
+        return cast(ContextBuilder, builder)
+    return build_context
+
+
+class TogulMiddleware:
+    """Attach ``request.togul`` and ``request.togul_context`` to every request.
+
+    Add ``"togul.contrib.django.TogulMiddleware"`` to ``MIDDLEWARE``.
+    """
+
+    def __init__(self, get_response: Callable[[Any], Any]) -> None:
+        self.get_response = get_response
+        self.build_context = _resolve_context_builder()
+
+    def __call__(self, request: Any) -> Any:
+        request.togul = get_client()
+        request.togul_context = self.build_context(request)
+        return self.get_response(request)
+
+
+def togul_flag(flag_key: str) -> Callable[[ViewFunc], ViewFunc]:
+    """Gate a view behind a flag, raising ``Http404`` when it is disabled.
+
+    This is the Django form of ``togul-laravel``'s route guard
+    (``->middleware('togul:new-dashboard')`` → ``abort(404)``). Django
+    middleware takes no per-route arguments, so the guard is a decorator::
+
+        @togul_flag("new-dashboard")
+        def dashboard(request):
+            ...
+
+    The context comes from ``request.togul_context`` when ``TogulMiddleware``
+    already built it, and is built on demand otherwise — so the decorator
+    works with or without the middleware installed.
+    """
+
+    def decorator(view: ViewFunc) -> ViewFunc:
+        @functools.wraps(view)
+        def wrapped(request: Any, *args: Any, **kwargs: Any) -> Any:
+            context = getattr(request, "togul_context", None)
+            if context is None:
+                context = _resolve_context_builder()(request)
+
+            if not get_client().evaluate(flag_key, context).enabled:
+                raise Http404(f"togul: flag {flag_key!r} is disabled")
+
+            return view(request, *args, **kwargs)
+
+        return cast(ViewFunc, wrapped)
+
+    return decorator

togul/contrib/fastapi.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+from typing import Any, AsyncIterator, Callable, Optional, cast
+
+from starlette.requests import Request
+
+from ..async_client import AsyncTogulClient
+from ..config import Config
+from ..stream import AsyncTogulStreamClient
+
+logger = logging.getLogger("togul")
+
+
+def create_lifespan(
+    config: Config,
+    *,
+    stream: bool = True,
+    client: Optional[AsyncTogulClient] = None,
+) -> Callable[[Any], Any]:
+    """Build a lifespan context manager for FastAPI or Starlette.
+
+    The client is stored on ``app.state.togul``. When ``stream`` is true an
+    ``AsyncTogulStreamClient`` runs as a background task (on
+    ``app.state.togul_stream_task``) so SSE events invalidate the cache in
+    real time. Both are shut down cleanly on application exit — including an
+    injected ``client``, which the lifespan owns for the app's lifetime.
+
+    Usage::
+
+        app = FastAPI(lifespan=create_lifespan(Config(...)))
+    """
+
+    @contextlib.asynccontextmanager
+    async def lifespan(app: Any) -> AsyncIterator[None]:
+        togul = client or AsyncTogulClient(config)
+        app.state.togul = togul
+
+        stream_client: Optional[AsyncTogulStreamClient] = None
+        task: Optional[asyncio.Task[None]] = None
+
+        if stream:
+            stream_client = AsyncTogulStreamClient(config, togul.cache)
+            task = asyncio.create_task(stream_client.connect())
+            task.add_done_callback(_log_stream_failure)
+            app.state.togul_stream_task = task
+
+        try:
+            yield
+        finally:
+            if task is not None:
+                task.cancel()
+                try:
+                    await task
+                except asyncio.CancelledError:
+                    pass
+                except Exception:
+                    # The stream task already failed on its own — for example a 401
+                    # from an API key without `stream` scope. Shutdown must still
+                    # close both pools.
+                    pass
+            if stream_client is not None:
+                await stream_client.aclose()
+            await togul.aclose()
+
+    return lifespan
+
+
+def _log_stream_failure(task: asyncio.Task[None]) -> None:
+    """Surface an ``AsyncTogulStreamClient`` background task that died on its own.
+
+    Without this, a failed stream task (a 401/403 from an API key that lacks
+    ``stream`` scope, for example) fails silently: real-time invalidation
+    stops, the cache quietly degrades to TTL-only, and nothing is reported
+    until Python's default handler prints "Task exception was never
+    retrieved" at garbage-collection time.
+    """
+    if task.cancelled():
+        return
+    exc = task.exception()
+    if exc is not None:
+        logger.error(
+            "togul: stream task failed, real-time cache invalidation has stopped "
+            "(falling back to TTL-only caching): %r",
+            exc,
+        )
+
+
+def get_togul(request: Request) -> AsyncTogulClient:
+    """FastAPI dependency: ``togul = Depends(get_togul)``."""
+    return cast(AsyncTogulClient, request.app.state.togul)

togul/errors.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from typing import Optional
+
+
+class TogulError(Exception):
+    """Base class for every error raised by the Togul SDK."""
+
+
+class TogulAPIError(TogulError):
+    """Raised when the Togul API returns a non-2xx response."""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: int = 0,
+        error_code: Optional[str] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.error_code = error_code

togul/result.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+import dataclasses
+from typing import Any, Literal
+
+ValueType = Literal["boolean", "string", "number", "json"]
+
+
+@dataclasses.dataclass(frozen=True)
+class EvaluateResult:
+    """A single flag evaluation, mirroring the API's ``EvaluateResponse``.
+
+    Attributes:
+        flag_key: The evaluated flag key.
+        enabled: Whether the flag itself is enabled.
+        value_type: One of ``boolean``, ``string``, ``number``, ``json``.
+            An empty string means the API response was malformed.
+        value: The flag value. Its Python type follows ``value_type``.
+        reason: One of ``disabled``, ``rule_match``, ``default``.
+    """
+
+    flag_key: str
+    enabled: bool
+    value_type: str
+    value: Any
+    reason: str

togul/stream.py

@@ -0,0 +1,179 @@
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import List, Optional
+
+import httpx
+
+from . import _transport as t
+from ._sse import parse_sse_event
+from .cache import TTLCache
+from .client import CacheListener, safe_json
+from .config import Config
+from .errors import TogulAPIError
+
+INITIAL_BACKOFF = 1.0
+MAX_BACKOFF = 30.0
+
+
+def _is_auth_error(exc: BaseException) -> bool:
+    return isinstance(exc, TogulAPIError) and exc.status_code in (401, 403)
+
+
+def _stream_timeout(config: Config) -> httpx.Timeout:
+    """No read deadline: an SSE connection is intentionally long-lived."""
+    return httpx.Timeout(None, connect=config.timeout)
+
+
+class _BaseStreamClient:
+    def __init__(self, config: Config, cache: TTLCache) -> None:
+        self._config = config
+        self._cache = cache
+        self._listeners: List[CacheListener] = []
+        self._stop = False
+        #: Internal test hook: end connect() after one stream attempt.
+        self.stop_after_first_stream = False
+
+    def on_cache_invalidated(self, listener: CacheListener) -> None:
+        self._listeners.append(listener)
+
+    def stop(self) -> None:
+        """Ask the reconnect loop to exit at the next opportunity."""
+        self._stop = True
+
+    def _handle_line(self, line: str) -> None:
+        event = parse_sse_event(line)
+        if event is None:
+            return
+
+        flag_key = str(event.get("flag_key") or "")
+        if flag_key:
+            self._cache.invalidate_flag(flag_key)
+        else:
+            self._cache.flush()
+
+        for listener in self._listeners:
+            listener(flag_key)
+
+    def _next_backoff(self, backoff: float) -> float:
+        return min(backoff * 2, MAX_BACKOFF)
+
+
+class TogulStreamClient(_BaseStreamClient):
+    """Blocking SSE client that keeps a cache fresh.
+
+    ``connect()`` never returns on its own: it reconnects with exponential
+    backoff until ``stop()`` is called, or until the API rejects the key
+    with 401/403 — which is re-raised, because retrying cannot fix it.
+    """
+
+    def __init__(
+        self,
+        config: Config,
+        cache: TTLCache,
+        http_client: Optional[httpx.Client] = None,
+    ) -> None:
+        super().__init__(config, cache)
+        self._owns_http = http_client is None
+        self._http = http_client or httpx.Client(
+            base_url=config.base_url,
+            timeout=_stream_timeout(config),
+        )
+
+    def _sleep(self, seconds: float) -> None:
+        time.sleep(seconds)
+
+    def connect(self) -> None:
+        backoff = INITIAL_BACKOFF
+        while not self._stop:
+            try:
+                self._stream_once()
+                backoff = INITIAL_BACKOFF
+            except Exception as exc:
+                if _is_auth_error(exc):
+                    raise
+                if self._stop:
+                    return
+                self._sleep(backoff)
+                backoff = self._next_backoff(backoff)
+            if self.stop_after_first_stream:
+                return
+
+    def close(self) -> None:
+        self.stop()
+        if self._owns_http:
+            self._http.close()
+
+    def _stream_once(self) -> None:
+        t.require_api_key(self._config)
+        headers = {
+            "Accept": "text/event-stream",
+            "X-API-Key": self._config.api_key,
+        }
+        with self._http.stream("GET", t.STREAM_PATH, headers=headers) as response:
+            if response.status_code != 200:
+                response.read()
+                raise t.api_error_from(response.status_code, safe_json(response))
+            for line in response.iter_lines():
+                if self._stop:
+                    return
+                self._handle_line(line)
+
+
+class AsyncTogulStreamClient(_BaseStreamClient):
+    """Asyncio SSE client. Run it as a background task."""
+
+    def __init__(
+        self,
+        config: Config,
+        cache: TTLCache,
+        http_client: Optional[httpx.AsyncClient] = None,
+    ) -> None:
+        super().__init__(config, cache)
+        self._owns_http = http_client is None
+        self._http = http_client or httpx.AsyncClient(
+            base_url=config.base_url,
+            timeout=_stream_timeout(config),
+        )
+
+    async def _sleep(self, seconds: float) -> None:
+        await asyncio.sleep(seconds)
+
+    async def connect(self) -> None:
+        backoff = INITIAL_BACKOFF
+        while not self._stop:
+            try:
+                await self._stream_once()
+                backoff = INITIAL_BACKOFF
+            except asyncio.CancelledError:
+                raise
+            except Exception as exc:
+                if _is_auth_error(exc):
+                    raise
+                if self._stop:
+                    return
+                await self._sleep(backoff)
+                backoff = self._next_backoff(backoff)
+            if self.stop_after_first_stream:
+                return
+
+    async def aclose(self) -> None:
+        self.stop()
+        if self._owns_http:
+            await self._http.aclose()
+
+    async def _stream_once(self) -> None:
+        t.require_api_key(self._config)
+        headers = {
+            "Accept": "text/event-stream",
+            "X-API-Key": self._config.api_key,
+        }
+        async with self._http.stream("GET", t.STREAM_PATH, headers=headers) as response:
+            if response.status_code != 200:
+                await response.aread()
+                raise t.api_error_from(response.status_code, safe_json(response))
+            async for line in response.aiter_lines():
+                if self._stop:
+                    return
+                self._handle_line(line)

togul-0.1.0.dist-info/METADATA

@@ -0,0 +1,318 @@
+Metadata-Version: 2.5
+Name: togul
+Version: 0.1.0
+Summary: Official Python SDK for Togul feature flags and remote config
+Project-URL: Homepage, https://togul.io
+Project-URL: Documentation, https://docs.togul.io
+Project-URL: Source, https://github.com/togulapp/togul-python
+Author: Togul
+License: MIT
+License-File: LICENSE
+Keywords: feature-flags,feature-toggle,remote-config,togul
+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: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<1,>=0.24
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Provides-Extra: django
+Requires-Dist: django>=4.2; extra == 'django'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.100; extra == 'fastapi'
+Description-Content-Type: text/markdown
+
+# Togul Python SDK
+
+Official Python SDK for Togul feature flags.
+
+## Install
+
+```bash
+pip install togul
+```
+
+Framework integrations are extras:
+
+```bash
+pip install "togul[django]"
+pip install "togul[fastapi]"
+```
+
+## Quick start (sync)
+
+```python
+"""Minimal synchronous usage."""
+
+from __future__ import annotations
+
+import os
+
+from togul import Config, TogulClient
+
+config = Config(
+    api_key=os.environ["TOGUL_API_KEY"],
+    environment=os.environ.get("TOGUL_ENVIRONMENT", "production"),
+)
+
+with TogulClient(config) as client:
+    result = client.evaluate("new-dashboard", {"user_id": "u-123", "plan": "premium"})
+    print(f"{result.flag_key}: enabled={result.enabled} value={result.value!r} ({result.reason})")
+```
+
+`TogulClient` is blocking. Use it from Django views, Celery tasks, scripts, or
+anywhere else that isn't running an event loop. The `with` block closes the
+underlying HTTP connection pool on exit; if you pass your own `httpx.Client`,
+the SDK leaves it open and you own its lifecycle.
+
+See [`examples/basic.py`](examples/basic.py).
+
+## Async
+
+For FastAPI, Starlette, or any asyncio application, use `AsyncTogulClient`:
+
+```python
+from togul import AsyncTogulClient, Config
+
+config = Config(api_key="...", environment="production")
+
+async with AsyncTogulClient(config) as client:
+    result = await client.evaluate("new-dashboard", {"user_id": "u-123"})
+```
+
+The API mirrors `TogulClient` exactly, `evaluate` just needs an `await`.
+`invalidate_cache()` and `invalidate_flag()` stay synchronous on both clients:
+they only touch the in-memory cache under a lock, so there's nothing to await.
+
+## Real-time updates
+
+Both clients cache evaluation results for `cache_ttl` seconds. A stream
+client keeps that cache fresh by invalidating entries as flags change,
+instead of waiting for the TTL to expire.
+
+Sync, run on a background thread:
+
+```python
+import threading
+
+from togul import Config, TogulClient, TogulStreamClient
+
+config = Config(api_key="...", environment="production")
+client = TogulClient(config)
+stream = TogulStreamClient(config, client.cache)
+
+threading.Thread(target=stream.connect, daemon=True).start()
+# ... use client.evaluate(...) as usual; stream.stop() to shut it down.
+```
+
+Async, run as a task:
+
+```python
+import asyncio
+
+from togul import AsyncTogulClient, AsyncTogulStreamClient, Config
+
+config = Config(api_key="...", environment="production")
+client = AsyncTogulClient(config)
+stream = AsyncTogulStreamClient(config, client.cache)
+
+task = asyncio.create_task(stream.connect())
+# ... await client.evaluate(...) as usual; stream.stop() then cancel the task.
+```
+
+`connect()` never returns on its own. It reconnects with exponential backoff
+(starting at 1s, doubling up to a 30s cap, reset after a clean disconnect)
+until `stop()` is called. A 401 or 403 response is the one exception: it is
+re-raised out of `connect()` immediately, because reconnecting with a
+rejected key cannot fix anything.
+
+The FastAPI integration below wires the async stream client into the
+application lifespan automatically; you don't need to manage the task by
+hand there.
+
+## Django
+
+Add the middleware and a `TOGUL` settings block:
+
+```python
+MIDDLEWARE = [
+    # ... your other middleware ...
+    "togul.contrib.django.TogulMiddleware",
+]
+
+TOGUL = {
+    "API_KEY": os.environ["TOGUL_API_KEY"],
+    "ENVIRONMENT": os.environ.get("TOGUL_ENVIRONMENT", "production"),
+    "CACHE_TTL": 30.0,
+    # "CONTEXT_BUILDER": "myapp.flags.build_context",
+}
+```
+
+| Key | Default | Notes |
+|---|---|---|
+| `API_KEY` | required | |
+| `ENVIRONMENT` | required | |
+| `TIMEOUT` | `5.0` | HTTP timeout in seconds. |
+| `CACHE_TTL` | `30.0` | Seconds an evaluation stays cached. |
+| `RETRY_COUNT` | `2` | Total request attempts (see below), not extra retries. |
+| `CONTEXT_BUILDER` | the built-in `build_context` | Dotted path or callable; see below. |
+
+There is deliberately no `BASE_URL` key. This matches `togul-laravel`'s
+`config/togul.php`, which exposes the same narrow set of framework-layer
+options. If you need a non-production origin, construct a `Config` directly
+(see [`examples/basic.py`](examples/basic.py)) rather than going through
+Django settings.
+
+`TogulMiddleware` attaches `request.togul` (a `TogulClient`) and
+`request.togul_context` (built by `CONTEXT_BUILDER`, or the default
+`build_context` if unset) to every request. The default `build_context` maps
+*only* the authenticated user's primary key to `user_id`, and omits it
+entirely for an anonymous request rather than sending a blank value. If your
+flags need anything else — a plan, a country, an experiment cohort — point
+`CONTEXT_BUILDER` at your own function; don't edit the default.
+
+```python
+def dashboard(request):
+    result = request.togul.evaluate("new-dashboard", request.togul_context)
+    if result.enabled:
+        return render(request, "dashboard/new.html")
+    return render(request, "dashboard/legacy.html")
+```
+
+For gating an entire view, use the `@togul_flag("key")` decorator instead.
+It raises `Http404` when the flag is disabled, and works with or without the
+middleware installed (it builds context on demand if `request.togul_context`
+isn't there):
+
+```python
+from togul.contrib.django import togul_flag
+
+
+@togul_flag("new-dashboard")
+def beta_dashboard(request):
+    return render(request, "dashboard/new.html")
+```
+
+See [`examples/django_settings.py`](examples/django_settings.py).
+
+## FastAPI
+
+```python
+from fastapi import Depends, FastAPI
+
+from togul import AsyncTogulClient, Config
+from togul.contrib.fastapi import create_lifespan, get_togul
+
+config = Config(api_key="...", environment="production")
+
+app = FastAPI(lifespan=create_lifespan(config))
+
+
+@app.get("/dashboard")
+async def dashboard(
+    user_id: str,
+    togul: AsyncTogulClient = Depends(get_togul),
+) -> dict:
+    result = await togul.evaluate("new-dashboard", {"user_id": user_id})
+    return {"variant": "new" if result.enabled else "legacy", "reason": result.reason}
+```
+
+`create_lifespan(config, *, stream=True, client=None)` builds an
+`AsyncTogulClient`, stores it on `app.state.togul`, and — since `stream`
+defaults to `True` — starts an `AsyncTogulStreamClient` as a background task
+so SSE events invalidate the cache in real time. Both are shut down cleanly
+on application exit. Pass `client=` to supply your own pre-built
+`AsyncTogulClient` (for tests, or a custom `httpx.AsyncClient`); the lifespan
+still closes it on shutdown. Pass `stream=False` to skip the background
+connection and rely on `cache_ttl` alone.
+
+`get_togul` is a plain `Depends()` provider that reads `app.state.togul`.
+
+See [`examples/fastapi_app.py`](examples/fastapi_app.py).
+
+## Configuration reference
+
+Every field of `Config`:
+
+| Field | Type | Default | Meaning |
+|---|---|---|---|
+| `api_key` | `str` | required | Environment-scoped API key. |
+| `environment` | `str` | required | Environment key, e.g. `"production"`. |
+| `timeout` | `float` | `5.0` | HTTP request timeout, in seconds. |
+| `cache_ttl` | `float` | `30.0` | How long an evaluation result stays cached, in seconds. |
+| `retry_count` | `int` | `2` | **Total** request attempts, not extra retries — `2` means the SDK issues at most two requests, i.e. one retry. |
+| `base_url` | `str` | `"https://api.togul.io"` | API origin. Trailing slashes are stripped. |
+
+`Config` is a frozen dataclass: build a new one to change settings.
+
+`evaluate()` is the only evaluation method — there are no typed
+`evaluate_string` / `evaluate_boolean` helpers. Read `result.value` and
+interpret it according to `result.value_type`.
+
+## Caching and invalidation
+
+Both clients keep an in-memory, thread-safe TTL cache of `EvaluateResult`s.
+An entry is dropped lazily, the first time it's read after `cache_ttl`
+seconds have passed, or if it carries a malformed (empty) `value_type`.
+
+The cache key is `flag_key:environment`, followed by `:key=value` for every
+context pair, with context keys sorted so call order never changes the key.
+For example, `evaluate("new-dashboard", {"plan": "premium", "user_id": "u-123"})`
+against environment `production` produces
+`new-dashboard:production:plan=premium:user_id=u-123`.
+
+`invalidate_cache()` clears the whole cache; `invalidate_flag(flag_key)`
+clears only entries for that flag. A `TogulStreamClient` /
+`AsyncTogulStreamClient` calls these automatically as SSE events arrive. A
+line that is not a well-formed `data:` JSON object — a heartbeat, a blank
+line, or a malformed payload — is ignored entirely: no invalidation, no
+flush. A well-formed event naming a `flag_key` invalidates just that flag; a
+well-formed event that omits it flushes the whole cache. Register
+`on_cache_invalidated(...)` on the stream client to observe SSE-driven
+invalidations, e.g. for logging — the stream client invalidates the cache
+directly and only notifies its own listeners, so it never routes through the
+evaluation client. A listener registered on the evaluation client instead
+fires only for invalidations *you* trigger by calling that client's own
+`invalidate_cache()` / `invalidate_flag()` directly; it will not fire for SSE
+events.
+
+## Error handling
+
+Every error the SDK raises is a `TogulError`. `TogulAPIError` is the subclass
+raised when the API itself returns a non-2xx response; it carries
+`status_code` and, when the response body has one, `error_code`.
+
+Retries apply only to HTTP `429` and any `5xx` response, plus network-level
+failures. Every other `4xx` (400, 401, 403, 404, ...) raises immediately with
+no retry. Each retry waits `attempt × 100ms` before trying again, so with the
+default `retry_count` of 2 the single retry is delayed by 100ms. When
+retries are exhausted, the client raises a `TogulError` wrapping the last
+failure.
+
+**There is no fail-open fallback.** Unlike SDKs that silently return a
+default value when evaluation fails, this SDK never guesses on your behalf:
+a failed `evaluate()` call raises, and it's up to your code to decide what
+happens next — return a default, log and re-raise, fall back to cached
+behavior, whatever fits your product. If you want fail-open behavior, wrap
+`evaluate()` in a `try`/`except TogulError` yourself.
+
+## Requirements
+
+Python 3.9+. Django integration requires Django 4.2+. FastAPI integration
+requires FastAPI 0.100+.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

togul-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+togul/__init__.py,sha256=InLsdeJHm84g3Cr4V1BwLkRpYKt9ZI0JZdD64TQKtxE,632
+togul/_sse.py,sha256=ArGL2zl68bG86om6UNuB3HI7YTYD5QlBl-nFTHee8LE,781
+togul/_transport.py,sha256=U-Btvcr6upezqiloeg18C7jaQBfxg6MxChiKx_ZPg0o,2236
+togul/async_client.py,sha256=h-PY-hwrMrNEo7KRaRNwYGmkw1poPb1eR4tsrrSrz58,3609
+togul/cache.py,sha256=Xkp9QVuBq3uJrCstS7EbaH2zgNmfsF49K8D--Maexqc,1580
+togul/client.py,sha256=UldslGFUfZ37oRXpRf1js-dJYCg3zPlxs-q4lh56pQQ,3725
+togul/config.py,sha256=7NRqJVZ8IFRY8jozdtxf8gddQgoL6Vf6Hh0f3j310Mg,1054
+togul/errors.py,sha256=ZERnVTafBHav-bQNUBB5F4RG4p4SheEdh8E2sVkd1us,539
+togul/result.py,sha256=GruUnEEgSTMABXhnvyyFz6PmBDyT4S0hsFeDTNcz6iw,767
+togul/stream.py,sha256=OD8_xou7EprmmmYRnUlFia_jclvUHW-fF3d0Mc_y06A,5616
+togul/contrib/__init__.py,sha256=5bQYr8MLpreK-0m-V1j1P4b3Rv5YHVOMnRfCPCbSE8c,108
+togul/contrib/django.py,sha256=SbN2PasPPcdUYmlKYML52uqYLatvg6FMKFQ-JbiHQKo,4800
+togul/contrib/fastapi.py,sha256=2RWYxrqmwFkWX4nL-spN2JebveGdV8sD8MzDNcqNIrc,3142
+togul/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+togul-0.1.0.dist-info/METADATA,sha256=9vpqSBUp3dbUnFjv7FFJkMYi9n1_1pgFFZ4h2cALrRw,11649
+togul-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+togul-0.1.0.dist-info/licenses/LICENSE,sha256=qqlwhIgv1axiq5bM0dq8U_Ti4bJ-2_hZH8X1mKRjW1U,1062
+togul-0.1.0.dist-info/RECORD,,

togul-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

togul-0.1.0.dist-info/licenses/LICENSE

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