Python SDK

Package: signakit-flags
Registry: PyPI
Minimum Python version: 3.11+

The Python SDK fetches your flag configuration from the SignaKit CDN once on startup, then evaluates all flags locally on each request — no network call per evaluation. It is async-first (httpx) with a full synchronous fallback so it works in Django, Flask, FastAPI, WSGI workers, and plain scripts.

Installation

pip install signakit-flags

Set your SDK key as an environment variable:

SIGNAKIT_SDK_KEY=sk_dev_yourOrgId_yourProjectId_random

Initialization

Create the client once at module level — not inside a request handler or view function. A module-level singleton reuses the fetched config across all requests within the same process lifetime and ensures in-memory exposure deduplication works correctly.

import os
from signakit_flags import SignaKitClient

client = SignaKitClient(sdk_key=os.environ["SIGNAKIT_SDK_KEY"])

from contextlib import asynccontextmanager
from fastapi import FastAPI
from lib.signakit import client

@asynccontextmanager
async def lifespan(app: FastAPI):
    result = await client.on_ready()
    if not result.success:
        print(f"[SignaKit] Config load failed: {result.reason}")
    yield

app = FastAPI(lifespan=lifespan)

import os
from signakit_flags import SignaKitClient

client = SignaKitClient(sdk_key=os.environ["SIGNAKIT_SDK_KEY"])
result = client.on_ready_sync()

if not result.success:
    print(f"[SignaKit] Config load failed: {result.reason}")

# ❌ Never do this — re-fetches config on every request, dedup provides no protection
def my_view(request):
    client = SignaKitClient(sdk_key=os.environ["SIGNAKIT_SDK_KEY"])
    await client.on_ready()
    # ...

SignaKitClient(sdk_key, **kwargs)

Raises ValueError if sdk_key is empty or malformed.

The convenience wrapper create_instance(sdk_key) returns SignaKitClient | None — it catches any ValueError and returns None on failure, which can simplify startup code that prefers null-checking to try/except.

Waiting for the client to be ready

Call on_ready() (async) or on_ready_sync() (sync) before evaluating flags. Both fetch the config from the CDN and mark the client ready. Subsequent calls are idempotent — the CDN request uses If-None-Match so unchanged configs return a 304 Not Modified and keep bandwidth minimal.

result = await client.on_ready()

if not result.success:
    print(f"SignaKit failed to load config: {result.reason}")
    # Fall back to defaults — create_user_context() returns None when not ready

result = client.on_ready_sync()

if not result.success:
    print(f"SignaKit failed to load config: {result.reason}")

Neither method raises — failures are returned as OnReadyResult(success=False, reason=str(exc)). After a failed ready, create_user_context() returns None and all flag evaluations return None.

OnReadyResult

is_ready property

if client.is_ready:
    ctx = client.create_user_context(user_id)

Creating a user context

A SignaKitUserContext represents a specific user. Create one per request with the user's ID and any attributes you want to use in targeting rules.

ctx = client.create_user_context("user-123", {
    "plan": "pro",
    "country": "US",
    "beta_tester": True,
})

if ctx is None:
    # Client is not ready — on_ready() was not called or failed
    ...

create_user_context(user_id, attributes?)

Returns SignaKitUserContext | None. Returns None and logs an error if the client is not ready.

ctx = client.create_user_context(user_id, {
    "$userAgent": request.headers.get("User-Agent", ""),
    "plan": "pro",
})

Evaluating a single flag

decision = ctx.decide("new-checkout")

if decision and decision.enabled:
    # Show the new checkout experience
    print(decision.variation_key)  # e.g. "treatment"

decide(flag_key) → Decision | None

Returns a Decision dataclass, or None if the flag does not exist, the client is not ready, or the user does not match any targeting rule.

Always check the return value. A None result means the flag was not found or the user did not match any rule — treat it as the disabled/control state.

decision = ctx.decide("my-flag")
show_feature = decision.enabled if decision is not None else False

decide() is synchronous and CPU-bound — no await needed. Exposure events are dispatched in the background: if a running event loop is detected, the event is scheduled as a coroutine task; otherwise it is sent via the sync transport.

Evaluating all flags at once

decisions = ctx.decide_all()

if decisions.get("new-checkout", {}).enabled:
    ...
if decisions.get("redesigned-nav", {}).enabled:
    ...

decide_all() → Decisions

Returns a dict[str, Decision] keyed by flag key. Only flags where the user matches a targeting rule are included. Archived flags are excluded.

Tracking events

Track a conversion or goal event that you've defined in the SignaKit dashboard. track_event is an async method — use await in async contexts.

await ctx.track_event("purchase_completed", value=99.99, metadata={"plan": "pro"})

track_event(event_key, value?, metadata?)

Returns: Coroutine[None] — fire and forget. Errors are logged but never raised. Bot users are silently skipped.

import asyncio

# In a sync Django view
asyncio.run(ctx.track_event("purchase_completed", value=49.99))

Type hints

All public types are exported directly from signakit_flags:

from signakit_flags import (
    SignaKitClient,
    SignaKitUserContext,
    Decision,
    Decisions,
    OnReadyResult,
    UserAttributes,
    VariableValue,
    TrackEventOptions,
)

Key type aliases

# User attribute values — the $userAgent key accepts a str
UserAttributes = dict[str, str | int | float | bool | list[str]]

# Variable value — string, number, bool, or a JSON object
VariableValue = str | int | float | bool | dict[str, Any]

# decide_all() return type
Decisions = dict[str, Decision]

Decision dataclass

from dataclasses import dataclass

@dataclass(frozen=True, slots=True)
class Decision:
    flag_key: str
    variation_key: str
    enabled: bool
    rule_key: str | None
    rule_type: str | None          # "ab-test" | "multi-armed-bandit" | "targeted" | None
    variables: dict[str, VariableValue]

The SDK is typed with mypy --strict and ships inline type annotations — no stub package needed.

A/B testing

When a flag is running as an experiment, decide() returns the assigned variation. The SDK automatically dispatches an $exposure event the first time a user is evaluated for that flag.

checkout = ctx.decide("checkout-redesign")

variation = checkout.variation_key if checkout else "control"

if variation == "treatment-a":
    return render_checkout_v2(request)
elif variation == "treatment-b":
    return render_checkout_v3(request)
else:
    return render_legacy_checkout(request)

Track your primary metric when the user converts:

# After the user completes the purchase
await ctx.track_event("purchase_completed", value=order.total)

Targeted delivery

When a flag is configured as a targeted rollout (not an experiment), decide() returns enabled=True for users who match the audience rule. No primary metric is needed and no $exposure event is fired — targeted rules are feature rollouts, not experiments.

beta_access = ctx.decide("beta-dashboard")

if beta_access and beta_access.enabled:
    return redirect("/dashboard/beta")

Bucketing is deterministic — the same user_id always produces the same outcome for the same flag configuration.

Error handling

on_ready() and on_ready_sync() never raise. If the config fetch fails, they return OnReadyResult(success=False, reason=...). After that, create_user_context() returns None, and decide() / decide_all() return None / {} — your code should treat these as the default/off state.

result = await client.on_ready()
if not result.success:
    logger.warning("SignaKit unavailable, using defaults: %s", result.reason)

# This is always safe — create_user_context returns None if not ready
ctx = client.create_user_context(user_id, attributes)
if ctx is None:
    show_feature = False
else:
    decision = ctx.decide("my-flag")
    show_feature = decision.enabled if decision else False

Anti-patterns

Related

• Quickstart →
• Django guide →
• Flask guide →
• Concepts: A/B Testing →
• Concepts: Targeted Delivery →