Use SwitchPilot with Python

Control product features from Python backends, API servers, jobs, and server-side scripts.

Server-side essentials
Security and runtime requirements for every integration.

Official SDKs are server-side only.

Never expose API keys in browser or client code.

Store API keys in environment variables.

The default fallback is false.

SDKs fail safely if SwitchPilot is unreachable.

Default cache TTL: 60 seconds.

Default stale-if-error window: 5 minutes.

Python SDK

switchpilot

v0.2.0

Python 3.10+

Requirements

The official Python SDK requires Python 3.10 or newer and is designed for server-side usage only.

It works with FastAPI, Django, Flask, scripts, jobs, backend services, and API servers.

1. Install the SDK

terminal
pip install switchpilot

2. Configure the API key

.env
SWITCHPILOT_API_KEY="sp_live_xxxxxxxxx"

The key is shown once. If it is lost, regenerate it in Project Settings and replace SWITCHPILOT_API_KEY before restarting or redeploying the service. The previous key stops working immediately.

3. Initialize the client and check a flag

switchpilot_client.py
import os
from switchpilot import SwitchPilot

flags = SwitchPilot(
    api_key=os.environ["SWITCHPILOT_API_KEY"]
)

enabled = flags.is_enabled("new-dashboard")

4. Check a flag

dashboard.py
if flags.is_enabled("new-dashboard"):
    show_new_dashboard()
else:
    show_current_dashboard()

FastAPI example

Import the reusable client from your server module, then check it inside the route.

main.py
from fastapi import FastAPI

app = FastAPI()

@app.get("/dashboard-mode")
def dashboard_mode() -> dict[str, str]:
    enabled = flags.is_enabled("new-dashboard")
    return {"mode": "new" if enabled else "current"}

Safe fallback behavior

The default is False. Missing flags, invalid responses, timeouts and normal network failures return the fallback instead of raising during flag evaluation.

per-call fallback
flags.is_enabled("new-dashboard", True)

Cache and refresh

flags.py
all_flags = flags.get_all()
fresh_flags = flags.refresh()
status = flags.get_status()

The in-memory cache lasts 60 seconds by default. While fresh, evaluations are local. A dashboard change can take about one minute to appear unless you call refresh() manually.

ETag and Last Known Good

client.py
flags = SwitchPilot(
    api_key=os.environ["SWITCHPILOT_API_KEY"],
    cache_ttl=60,
    stale_if_error=300,
    fallback=False,
)

The SDK automatically uses ETags; a 304 renews freshness without downloading or parsing the flags again. If synchronization fails, the last valid configuration remains usable for five minutes beyond its normal TTL. Only then does the fallback apply.

Concurrent threads share a refresh. A 429 response is not retried in a loop: the SDK respects Retry-After and exposes the deadline throughget_status(), which performs no I/O.