Active PyPI 1.0.3 soasap

SOASAP Python SDK

Lightweight, production-ready feature flags SDK for Python 3.10+ — O(1) thread-safe local evaluation, non-blocking startup with disk cache, real-time SSE updates, zero runtime dependencies, and graceful offline behavior. Flask, FastAPI, Django, Celery.

GitHub Documentation PyPI

Installation

Install from PyPI. Supports Python 3.10, 3.11, 3.12, and 3.13+.

pip install soasap

Quick start

Create a client with create_soasap_client(), enable preload=True for non-blocking startup sync, and read flags synchronously anywhere in your process.

import os
from soasap import create_soasap_client

flags = create_soasap_client(
    api_key=os.environ["SOASAP_API_KEY"],
    preload=True,
)

# Sync reads — never throw, never hit the network
if flags.get_bool("new-checkout"):
    print("New checkout enabled")

Use feature flags

Evaluate flags on the hot path with zero network I/O. Getters never throw — safe for production request handlers.

@app.get("/")
def index():
    if g.soasap.get_bool("maintenance-mode"):
        return "Maintenance", 503
    return "OK"

Typed access

Bool, number, string, and JSON remote config. JSON keys from the dashboard are returned as stored (typically camelCase).

enabled = flags.get_bool("feature-x")
limit   = flags.get_number("rate-limit", 100)
theme   = flags.get_string("ui-theme", "light")
config  = flags.get_json("checkout-config", {"enableUpsells": False, "maxItems": 10})

Startup sync

preload=True (recommended) starts the SSE worker in a daemon thread, loads the disk cache on cold start, and never blocks module initialization or server boot. Without it, lazy mode defers the network connection until the first flag read.

In lazy mode, the first evaluation uses default values (or the local disk cache if available) while the SSE stream connects in the background.

# Immediate sync (recommended)
flags = create_soasap_client(
    api_key=os.environ["SOASAP_API_KEY"],
    preload=True,
)

# Lazy sync — first read falls back to defaults or disk cache
flags = create_soasap_client(api_key=os.environ["SOASAP_API_KEY"])

Flask integration

Attach one client instance per process via a before-request hook. Call flags.close() on shutdown to flush the disk cache.

import os
import atexit
from flask import Flask, g
from soasap import create_soasap_client

flags = create_soasap_client(
    api_key=os.environ["SOASAP_API_KEY"],
    preload=True,
)

app = Flask(__name__)

@app.before_request
def attach_flags():
    g.soasap = flags

atexit.register(flags.close)

Error handling & observability

Hook background diagnostics without affecting the hot path. Sources: NETWORK, DISK, PARSER.

from soasap import SoasapErrorSource, create_soasap_client

create_soasap_client(
    api_key="...",
    on_error=lambda ctx: print(
        f"[{ctx.source.value}] transient={ctx.is_transient} {ctx.exception}"
    ),
)

# SoasapErrorSource.NETWORK | .DISK | .PARSER

Production safety & guardrails

Immutable snapshots — snapshot reference swap; readers never see partial updates
Memory cap protection (anti-DoS) — 5 MB SSE payload cap; oversized streams are dropped and reset
Payload validation — root element must be a JSON object {}; invalid payloads are ignored
IO coalescing (disk debounce) — disk writes coalesced at most once every ~2.5 seconds
Zero runtime dependencies — stdlib only in production
One client per process — for Gunicorn/uWSGI, create one client per worker process

The SDK never throws from flag getters.

Offline resiliency

Scenario	Behavior
API unavailable	Uses stale cached flags
SSE disconnected	Keeps last known snapshot
First startup without cache	Returns default values
Invalid payload	Payload ignored
Disk cache failure	In-memory mode continues
Persistent network issues	Automatic reconnect with backoff

Disk cache: %LOCALAPPDATA%\soasap\cache (Windows), ~/.local/share/soasap/cache (Linux/macOS).
Override with cache_directory="/custom/path".

Architecture

[Read path]  get_bool() → current_snapshot ref → O(1) lookup
                              ↑
                              | (snapshot reference swap)
[Background] SSE → SseEventParser (5MB cap) → DiskWriteCoalescer → disk

Supported runtimes

Python 3.10 / 3.11 / 3.12 / 3.13+
Compatible with Flask, FastAPI, Django, and async web frameworks (sync reads on hot path)

← All SDKs