Python SDK

The Python SDK provides a thread-safe client for evaluating feature flags in Python applications.

Installation

pip install featuresignals

Requirements: Python 3.9+

Quick Start

from featuresignals import FeatureSignalsClient, ClientOptions, EvalContext

client = FeatureSignalsClient(
    "fs_srv_your_api_key",
    ClientOptions(env_key="production", base_url="http://localhost:8080"),
)

client.wait_for_ready()

ctx = EvalContext(key="user-123", attributes={"country": "US"})
enabled = client.bool_variation("new-feature", ctx, False)
print(f"Feature enabled: {enabled}")

client.close()

Configuration

from featuresignals import ClientOptions, EvalContext

options = ClientOptions(
    env_key="production",                    # Required: environment slug
    base_url="http://localhost:8080",        # API server URL
    polling_interval=30.0,                   # Polling interval (seconds)
    streaming=False,                         # Use SSE instead of polling
    sse_retry=5.0,                          # SSE reconnect delay (seconds)
    timeout=10.0,                           # HTTP request timeout (seconds)
    context=EvalContext(key="server"),        # Default evaluation context
)

Options Reference

Option	Type	Default	Description
env_key	str	(required)	Environment slug
base_url	str	https://api.featuresignals.com	API server URL
polling_interval	float	30.0	Refresh interval (seconds)
streaming	bool	False	Enable SSE streaming
sse_retry	float	5.0	SSE reconnect delay (seconds)
timeout	float	10.0	HTTP timeout (seconds)
context	EvalContext	EvalContext(key="server")	Default context for flag fetch

Callbacks

def on_ready():
    print("Flags loaded!")

def on_error(err):
    print(f"Error: {err}")

def on_update(flags):
    print(f"Updated {len(flags)} flags")

client = FeatureSignalsClient(
    "api-key",
    options,
    on_ready=on_ready,
    on_error=on_error,
    on_update=on_update,
)

Evaluation Context

from featuresignals import EvalContext

# Simple context
ctx = EvalContext(key="user-123")

# With attributes
ctx = EvalContext(
    key="user-123",
    attributes={
        "country": "US",
        "plan": "enterprise",
        "beta": True,
    },
)

# Immutable builder
ctx = EvalContext(key="user-123").with_attribute("country", "US")

Variation Methods

# Boolean
enabled = client.bool_variation("flag-key", ctx, False)

# String
theme = client.string_variation("theme", ctx, "light")

# Number (int or float)
limit = client.number_variation("rate-limit", ctx, 100)

# JSON (dict/list)
config = client.json_variation("feature-config", ctx, {})

Readiness

# Blocking wait (with timeout)
ready = client.wait_for_ready(timeout=10.0)  # Returns bool

# Non-blocking check
if client.is_ready():
    # flags are loaded
    pass

Getting All Flags

all_flags = client.all_flags()  # dict[str, Any]

Shutdown

client.close()

The client uses daemon threads, so they'll be cleaned up on process exit even without calling close().

OpenFeature Integration

See OpenFeature for using the Python SDK with OpenFeature.