Python SDK

switchbox-flags — constructor, methods, and configuration.

The Python SDK is published to PyPI as switchbox-flags and imported as switchbox. It has zero runtime dependencies (Python stdlib only) and is thread-safe.

pip install switchbox-flags

The same reference ships in the package README on PyPI.

Switchbox(...)

from switchbox import Switchbox

client = Switchbox(
    sdk_key="your-sdk-key",   # required
    poll_interval=30,          # seconds between background refreshes
    on_error=None,             # callback(exc) on fetch/parse failure
    timeout=10,                # per-fetch HTTP timeout, seconds
    cdn_base_url=None,         # override the CDN host (advanced)
)

Creates a client. It performs an initial synchronous fetch on construction, then starts a background daemon thread that refreshes the config every poll_interval seconds. Create one client at startup and reuse it.

Parameter	Type	Default	Description
`sdk_key`	`str`	—	The environment's SDK key from the dashboard.
`poll_interval`	`int`	`30`	Seconds between background config refreshes.
`on_error`	`Callable[[Exception], None] \| None`	`None`	Invoked when a fetch or parse fails. The client keeps serving the last good config.
`timeout`	`int`	`10`	HTTP timeout for each fetch, in seconds.
`cdn_base_url`	`str \| None`	`None`	Override the CDN base URL. Defaults to the Switchbox edge; you rarely need this.

client.ready

if client.ready:
    ...

A property — True once a config has been loaded at least once. Useful to gate startup logic on the first successful fetch.

client.enabled(flag_key, user=None)

client.enabled("new_checkout", user={"user_id": "42"})  # -> bool

Returns whether a boolean flag is enabled for the user. Returns False if the flag doesn't exist or no config has loaded — a safe default.

Parameter	Type	Description
`flag_key`	`str`	The flag key to evaluate.
`user`	`dict \| None`	User context for targeting and rollouts.

client.get_value(flag_key, user=None, default=None)

client.get_value("search_algorithm", user={"user_id": "42"}, default="v1")

Returns the resolved value of a string, number, or JSON flag (a json flag comes back as a parsed object/array). Returns default if the flag doesn't exist or no config is available.

Parameter	Type	Description
`flag_key`	`str`	The flag key to evaluate.
`user`	`dict \| None`	User context for targeting and rollouts.
`default`	`Any`	Returned when the flag is absent or unresolved.

client.get_all_flags(user=None)

client.get_all_flags(user={"user_id": "42"})
# {"dark_mode": True, "search_algorithm": "v2", "max_results": 50}

Returns every flag resolved for the user, as a dict. Empty dict if no config is available.

client.close()

client.close()

Stops the background polling thread. Call it on application shutdown.

Context manager

Switchbox supports with, which calls close() automatically:

with Switchbox(sdk_key="your-sdk-key") as client:
    if client.enabled("new_checkout", user={"user_id": "42"}):
        show_new_checkout()

Offline behaviour

If the CDN is unreachable, the SDK keeps serving the last successfully fetched config — your flags keep working. If it has never fetched a config (e.g. the network was down at startup), enabled() returns False and get_value() returns your default. No exceptions are raised into your call path; failures go to on_error if you supplied it.

Evaluation order — how a value is resolved.
JavaScript SDK · React SDK.