flagbase-sdk 0.1.0

Python SDK for FlagBase — a self-hostable feature flag and A/B testing platform

flagbase-python-sdk

Official Python SDK for FlagBase — a self-hostable feature flag and A/B testing platform.

Installation

pip install flagbase

Quick Start

from flagbase import FlagClient

client = FlagClient(
    api_key="proj_sk_...",       # Generate in your FlagBase dashboard
    host="http://localhost:8000", # Your FlagBase server URL
)

# Basic flag check
if client.is_enabled("new_checkout_ui", user_id="user_123"):
    show_new_checkout()
else:
    show_old_checkout()

client.close()

Usage

Initialisation

client = FlagClient(
    api_key="proj_sk_...",   # Required
    host="http://...",        # Required — your FlagBase server URL
    cache_ttl=30,             # Optional — local cache TTL in seconds (default 30)
    timeout=0.5,              # Optional — HTTP timeout in seconds (default 0.5)
    default_value=False,      # Optional — returned if server unreachable (default False)
)

is_enabled(flag_name, user_id, context=None, default_value=None)

Returns True or False. Never raises.

enabled = client.is_enabled("dark_mode", user_id="user_123")

# With targeting context
enabled = client.is_enabled(
    "premium_feature",
    user_id="user_123",
    context={
        "email": "[e-mail]",
        "country": "IN",
        "custom_attributes": {"plan": "premium"}
    }
)

evaluate(flag_name, user_id, context=None)

Returns an EvaluationResult with enabled, variant, reason, and flag_name.

result = client.evaluate("new_checkout_ui", user_id="user_123")
print(result.enabled)  # True
print(result.reason)   # "rollout_included"
print(result.variant)  # None (variants available in v4 A/B testing)

track(event_name, user_id, flag_name, variant=None)

Track a conversion event. Non-blocking — returns immediately.

client.track(
    event_name="purchase_completed",
    user_id="user_123",
    flag_name="new_checkout_ui",
)

Context manager

with FlagClient(api_key="proj_sk_...", host="http://...") as client:
    enabled = client.is_enabled("my_flag", user_id="user_123")
# client.close() called automatically

Error Handling

The SDK never raises exceptions in normal use. All errors are caught internally and default_value is returned instead:

Error	Behaviour
Network timeout	Returns default_value, logs warning
HTTP 401 (bad API key)	Returns default_value, logs error
Server error (5xx)	Returns default_value, logs warning
Any unexpected error	Returns default_value, logs error

Caching

Flag results are cached locally for 30 seconds (configurable via cache_ttl). This means:

• Repeated calls to is_enabled() for the same flag + user don't hit the network
• Flag changes take up to cache_ttl seconds to propagate to the SDK

Requirements

• Python 3.10+
• httpx >= 0.27.0

Running the Backend

This SDK requires a running FlagBase server. See the FlagBase backend repo for setup instructions.

License

MIT