shipeasy (Python)

Server SDK for Shipeasy — feature flags, dynamic configs, kill switches, A/B experiments, and metric tracking. Server-key only; never embed in a browser.

📚 Full documentation: https://shipeasy-ai.github.io/sdk-python/ — also browsable under docs/. This README is generated from those docs.

🤖 Using an AI agent?

This SDK ships an installable agent skill — a copy-paste-ready guide to configure() + Client(user), testing, experiments, error reporting, and more, with links the agent can pull for deeper docs:

• Skill: docs/skill/SKILL.md · raw: https://shipeasy-ai.github.io/sdk-python/skill/SKILL.md
• Install it (ships with the package — no network): shipeasy-skill install → .claude/skills/shipeasy-python/SKILL.md (or via the Shipeasy CLI: shipeasy docs skill --sdk python --install)

Humans: you can copy that skill straight into your own project's agent skills directory (e.g. .claude/skills/shipeasy-python/SKILL.md) so your coding agent always uses the correct Shipeasy patterns. Every doc page and snippet is also fetchable by URL — start from the manifest at https://shipeasy-ai.github.io/sdk-python/manifest.json.

Install

# pip
pip install shipeasy

# poetry
poetry add shipeasy

# uv
uv add shipeasy

Requires Python 3.9+. Per-framework setup (Django / Flask / FastAPI) and the anon-id middleware are on the Installation page.

Quickstart — configure() once, then Client(user) per request

import shipeasy

shipeasy.configure(
    api_key="sdk_server_...",
    attributes=lambda u: {"user_id": u.id, "country": u.country, "plan": u.plan},
)

# construct once per callsite (cheap; binds the user)
client = shipeasy.Client(current_user)

if client.get_flag("new_checkout"):
    ...
config = client.get_config("billing_copy")
result = client.get_experiment("checkout_button", default_params={"color": "blue"})
client.log_exposure("checkout_button")    # at the decision point
client.track("purchase", {"amount": 49})  # on conversion

Constructing Client(user) before configure() raises RuntimeError.

Documentation

Copy-paste snippets live under docs/snippets/ (release · metrics · i18n · ops); an installable agent skill is at docs/skill/SKILL.md.

Testing

Use configure_for_testing() — the test-mode sibling of configure(). It does zero network, needs no api_key, and seeds the values your code under test should see via override arguments. Then read through the ordinary shipeasy.Client(user) — the same call your production code uses.

import shipeasy
from shipeasy import Client

shipeasy.configure_for_testing(
    flags={"new_checkout": True},
    configs={"billing_copy": {"title": "Welcome"}},
    experiments={"checkout_button": ("treatment", {"color": "green"})},
)

# construct once per callsite (cheap; binds the user)
client = Client({"user_id": "u_123"})

assert client.get_flag("new_checkout") is True
assert client.get_config("billing_copy") == {"title": "Welcome"}

result = client.get_experiment("checkout_button", default_params={"color": "blue"})
assert result.in_experiment and result.group == "treatment"
assert result.params == {"color": "green"}

# track()/log_exposure() are no-ops in test mode — safe to call, send nothing
client.track("purchase", {"amount": 49})

More — the on-the-spot override helpers and a working example shipeasy-snapshot.json — on the Testing page.

License

MIT. Evaluation is tested against the cross-language MurmurHash3 vectors in experiment-platform/04-evaluation.md.