Metadata-Version: 2.4
Name: switchpilot
Version: 0.1.0
Summary: Official server-side Python SDK for SwitchPilot feature flags
License-Expression: MIT
Requires-Python: >=3.10
Requires-Dist: httpx<1,>=0.27
Provides-Extra: dev
Requires-Dist: pytest<10,>=8; extra == 'dev'
Requires-Dist: ruff<1,>=0.15; extra == 'dev'
Description-Content-Type: text/markdown

# switchpilot

The official server-side Python SDK for SwitchPilot feature flags.

## Install

```sh
pip install switchpilot
```

## Quick start

```python
import os
from switchpilot import SwitchPilot

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

if flags.is_enabled("new-dashboard"):
    print("New dashboard enabled")
```

## Python example

```python
all_flags = flags.get_all()
fresh_flags = flags.refresh()
```

`get_all()` uses a valid cache. `refresh()` always makes a network request.

## FastAPI example

Create one reusable server-side client:

```python
import os
from fastapi import FastAPI
from switchpilot import SwitchPilot

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

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

## Django example

Create the client in a server-only module, then use it from a view:

```python
import os
from django.http import JsonResponse
from switchpilot import SwitchPilot

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

def dashboard_mode(request):
    enabled = flags.is_enabled("new-dashboard")
    return JsonResponse({"mode": "new" if enabled else "current"})
```

## Safe fallbacks

The default fallback is `False`. Missing flags, invalid responses, timeouts, and normal network or API failures do not raise during flag evaluation:

```python
flags.is_enabled("new-dashboard")        # False on failure
flags.is_enabled("new-dashboard", True)  # per-call fallback
```

If SwitchPilot is unreachable, `get_all()` and `refresh()` return cached flags when available, or `{}` otherwise.

## Caching

Flags are cached in memory for 30 seconds by default. Configure `cache_ttl` to change the TTL; each client instance has its own cache.

## Custom endpoint for local development

```python
import os
from switchpilot import SwitchPilot

flags = SwitchPilot(
    api_key=os.environ["SWITCHPILOT_API_KEY"],
    endpoint="https://switchpilot-one.vercel.app/api/sdk/flags",
)

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

## Server-side only warning

This package is a server-side SDK. Never use it in frontend or browser code, and never expose a SwitchPilot API key to users. Keep API keys in server-side environment variables.
