Skip to content
RocketFlag Docs

Python SDK

The RocketFlag Python SDK is a stdlib-only client for evaluating flags from Python 3.9+ applications.

Installation

Section titled “Installation”
Terminal window
pip install rocketflag

Basic Usage

Section titled “Basic Usage”
from rocketflag import create_client


rocketflag = create_client()


flag = rocketflag.get_flag("ABC123def456")
if flag.enabled:
    print(f'Feature "{flag.name}" is enabled!')

You can also construct Client directly:

from rocketflag import Client


client = Client()
flag = client.get_flag("ABC123def456")

Advanced Usage

Section titled “Advanced Usage”

Working with Cohorts

Section titled “Working with Cohorts”

Pass a cohort identifier to target specific users:

flag = rocketflag.get_flag("ABC123def456", {"cohort": "user@example.com"})

Attributes and sticky rollouts

Section titled “Attributes and sticky rollouts”

Add a targetingKey for sticky percentage rollouts, and any other keys as audience attributes:

flag = rocketflag.get_flag(
    "ABC123def456",
    {"targetingKey": "user-42", "plan": "pro", "country": "AU"},
)

Percentage rollouts are sticky per key: the same targetingKey (or, without one, the same cohort) gets the same answer every time, so send a stable user identifier. Other keys are matched against the flag’s audience and are only read when the flag has one. Matching is exact and case-sensitive, and an attribute you do not send never matches. cohort, env and targetingKey are reserved and cannot be audience attributes. No SDK signature changed: this is the same context you already pass. See Sticky rollouts. With caching on, each distinct targetingKey is a separate cache entry.

Context values must be str, int, float, or bool. None raises ValueError, so leave out an attribute you do not have. UserContext and ContextValue are exported from rocketflag for type annotations.

Working with Group Flags (Environments)

Section titled “Working with Group Flags (Environments)”

When using Group Flags, specify the environment (environment names may contain letters, numbers, hyphens, and underscores):

flag = rocketflag.get_flag("ABC123def456", {"env": "production"})

Custom Configuration

Section titled “Custom Configuration”
rocketflag = create_client("v1", "https://your-custom-proxy.com")

Caching Responses

Section titled “Caching Responses”

Opt-in in-memory cache keyed by flag ID and user context:

# Cache flag responses for 5 minutes.
rocketflag = create_client(ttl_seconds=300)


flag = rocketflag.get_flag("ABC123def456", {"cohort": "beta"})


# Force a fresh fetch.
flag = rocketflag.get_flag("ABC123def456", ttl_seconds=0)

Without a client default or per-call TTL, every call hits the API. Each distinct context is its own cache entry, so a targetingKey per user means an entry per user. The cache is thread-safe, holds at most 10,000 entries by default, and evicts the least recently used (LRU) entry when full. You can configure the limit with max_entries:

rocketflag = create_client(ttl_seconds=300, max_entries=50_000)

Error Handling

Section titled “Error Handling”
from rocketflag import APIError, InvalidResponseError, NetworkError, create_client


rocketflag = create_client()


try:
    flag = rocketflag.get_flag("ABC123def456")
except APIError as err:
    print(f"API Error: {err.status} {err.status_text}")
except InvalidResponseError as err:
    print(f"Invalid Response Error: {err}")
except NetworkError as err:
    print(f"Network Error: {err}")
  • APIError — non-OK HTTP status (includes status / status_text). A 404 means the flag ID is unknown.
  • InvalidResponseError — body is not JSON or not a flag object.
  • NetworkError — connection failure.

Source

Section titled “Source”