Feature Toggles with Unleash in Python — Core Concepts

Implement gradual rollouts, A/B tests, and kill switches in Python using Unleash feature toggles with activation strategies.

Feature toggles decouple deployment from release. You can deploy code containing a new feature without exposing it to users, then control visibility through configuration rather than code changes. This reduces deployment risk and enables gradual rollouts, A/B testing, and instant rollbacks.

Unleash is an open-source feature management platform that provides a server, dashboard, and SDKs for multiple languages including Python.

How Unleash works

The architecture has three parts:

Unleash server: Stores toggle definitions, strategies, and state. Runs as a standalone service with a PostgreSQL database.
Admin UI: Web dashboard where you create toggles, configure strategies, and monitor usage.
SDK (Python client): Runs in your application, fetches toggle state, and evaluates strategies locally.

The SDK polls the server periodically (default: every 15 seconds) and caches toggle definitions in memory. This means toggle checks are fast local operations — no network call per check.

Setting up the Python SDK

from UnleashClient import UnleashClient

client = UnleashClient(
    url="http://unleash-server:4242/api",
    app_name="order-service",
    instance_id="order-service-pod-1",
    custom_headers={"Authorization": "your-api-token"},
)

client.initialize_client()

Check a toggle:

if client.is_enabled("new-checkout-flow"):
    return new_checkout()
else:
    return old_checkout()

With context for targeted rollouts:

context = {
    "userId": str(user.id),
    "properties": {
        "plan": user.plan,
        "country": user.country,
    }
}

if client.is_enabled("premium-dashboard", context):
    return render_premium_dashboard()

Activation strategies

Strategies define who sees a feature. Unleash includes several built-in strategies:

Standard (on/off)

The simplest. The toggle is either enabled for everyone or disabled for everyone.

Gradual rollout

Enable for a percentage of users. Unleash uses a consistent hashing algorithm based on user ID and toggle name, so the same user always gets the same result (no flickering).

User IDs

Enable for specific user IDs. Good for internal testing or beta users.

IPs

Enable for specific IP addresses or ranges. Useful for office-based testing.

Custom strategies

Define your own logic. For example, enable for users in specific countries or on specific subscription plans.

You can combine strategies — “enable for 10% of users AND only in the US” — to create precise targeting.

Toggle types

Unleash categorizes toggles by lifecycle:

Release toggles: Control feature rollout. Remove after full rollout.
Experiment toggles: A/B testing. Remove after experiment concludes.
Operational toggles: Kill switches for graceful degradation. Keep long-term.
Permission toggles: Control access by user segment. May be permanent.

This categorization helps teams track technical debt. A release toggle that has been active for six months is probably stale and should be cleaned up.

Variants

Variants extend toggles for A/B testing. Instead of just on/off, a toggle can return different variants:

variant = client.get_variant("checkout-button-color", context)

if variant["name"] == "blue":
    button_color = "#0066CC"
elif variant["name"] == "green":
    button_color = "#00CC66"
else:
    button_color = "#333333"  # default

Variants support weighted distribution (e.g., 50% blue, 50% green) and payload data (JSON attached to each variant).

Common misconception

“Feature toggles add too much complexity to the codebase.” Toggles add complexity only when they accumulate. The discipline is removing toggles after they serve their purpose. Release toggles should have an expiration date. Unleash helps by tracking toggle age and flagging stale toggles.

When to use Unleash

Unleash fits teams that want self-hosted feature management with no vendor lock-in. If you are already paying for LaunchDarkly or similar, Unleash may not add value. But for teams that want open-source control, privacy compliance (data stays on your infrastructure), and a clean REST API, Unleash is a strong choice.

One thing to remember: Unleash separates deployment from release — deploy code anytime, control who sees it through strategies and gradual rollouts, and roll back instantly by flipping a toggle.

pythonunleashfeature-management