Python

The Unleash Python SDK lets you evaluate feature flags in Python applications. It connects to Unleash or Unleash Edge to fetch flag configurations and evaluates them locally against an Unleash context.

You can use this SDK with Unleash Enterprise or Unleash Open Source.

For an overview of how Unleash SDKs work, including offline behavior, feature compatibility across SDKs, and default refresh and metrics intervals, refer to the SDK overview.

Installation

$
pip install UnleashClient

Initialization

You must initialize the SDK before you use it. Note that until the SDK has synchronized with the API, all features will evaluate to false unless you have a bootstrapped configuration or you use fallbacks.

1
from UnleashClient import UnleashClient
2
3
client = UnleashClient(
4
    url="https:<YOUR-API-URL>",
5
    app_name="my-python-app",
6
    custom_headers={'Authorization': '<API token>'})
7
8
client.initialize_client()

Check flags

Once the SDK is initialized, you can evaluate toggles using the is_enabled or get_variant methods.

1
enabled = client.is_enabled("my_toggle")
2
print(enabled)
3
> True
4
5
variant = client.get_variant("variant_toggle")
6
print(variant)
7
> {
8
>    "name": "variant1",
9
>    "payload": {
10
>        "type": "string",
11
>        "value": "val1"
12
>        },
13
>    "enabled": True
14
> }

Stop the client

If your program no longer needs the SDK, you can call destroy(), which shuts down the SDK and flushes any pending metrics to Unleash.

1
client.destroy()

Unleash context

Both the is_enabled and get_variant functions support Unleash contexts as the second parameter.

1
app_context = {
2
    "userId": "test@email.com",
3
    "sessionId": "55845",
4
    "properties": {
5
        "custom-property": "some-value"
6
    }
7
}
8
9
client.is_enabled("user_id_toggle", app_context)
10
client.get_variant("variant_toggle", app_context)

The context values can be any type that has a __str__ implementation. Types that are explicitly supported are:

• Numerics
• Strings
• Dates
• UUIDs

Fallback function

You can specify a fallback function for cases where the client doesn’t recognize the toggle by using the fallback_function keyword argument:

1
def custom_fallback(feature_name: str, context: dict) -> bool:
2
    return True
3
4
client.is_enabled("my_toggle", fallback_function=custom_fallback)

The fallback function must accept the feature name and context as positional arguments in that order.

The client will evaluate the fallback function if the feature flag is not found or an exception occurs when calling the is_enabled() method.

Configuration options

The UnleashClient constructor supports the following configuration options:

Bootstrap

By default, the Python SDK fetches your feature flags from the Unleash API at startup. If you want to make your SDK more resilient (e.g., during network outages), you can bootstrap the client with a local or remote toggle config.

How it works:

• Use a FileCache (or your own BaseCache implementation).

• Pre-seed it with feature flags using bootstrap_from_dict, bootstrap_from_file, or bootstrap_from_url.

• Pass your cache to the UnleashClient on startup.

The default FileCache has built-in methods for bootstrapping from a dictionary, file, or URL.

1
from UnleashClient.cache import FileCache
2
from UnleashClient import UnleashClient
3
4
cache = FileCache("MY_CACHE")
5
cache.bootstrap_from_dict({
6
    "version": 2,
7
    "features": [
8
        {
9
            "name": "my_toggle",
10
            "enabled": True,
11
            "strategies": [{"name": "default"}],
12
        }
13
    ]
14
})
15
16
client = UnleashClient(
17
    url="https://YOUR-API-URL",
18
    app_name="my-python-app",
19
    cache=cache
20
)

Custom strategies

The Python SDK lets you define custom activation strategies if the built-in ones don’t cover your needs. This gives you more fine grained control over how your features evaluate.

A custom strategy is just a class that implements an apply method.

1
class ActiveForEmailStrategy:
2
    def apply(self, parameters: dict, context: dict = None) -> bool:
3
        # Decide if the feature is active for this context
4
        return context.get("email") in parameters

Once you’ve defined your strategy, register it when you initialize the client. The key must match the strategy name in Unleash exactly.

1
## You should have a custom strategy defined in Unleash called 'EmailStrategy'
2
my_custom_strategies = {
3
    "EmailStrategy": ActiveForEmailStrategy()
4
}
5
6
client = UnleashClient(
7
8
    url="https://YOUR-API-URL",
9
    app_name="my-python-app",
10
    custom_headers={'Authorization': '<API token>'},
11
    custom_strategies = my_custom_strategies
12
)

Events

The Python SDK lets you tap into its behavior through impression data and lifecycle events. Provide an event_callback function when you initialize the client.

The callback receives a single UnleashEvent. The SDK emits the following event types:

• Impression events: emitted when is_enabled() or get_variant() is called for a flag with impression data enabled.
• READY: triggered once when the SDK first loads feature flags from the Unleash server or a local backup.
• FETCHED: triggered when a new version of feature flags is pulled from the server (not on 304 Not Modified). Includes a features property with all flags returned by that fetch.

Impression callbacks run in-process — keep them fast to avoid blocking your app.

1
from blinker import signal
2
from UnleashClient import UnleashClient
3
from UnleashClient.events import UnleashEvent, UnleashEventType
4
5
send_data = signal('send-data')
6
7
@send_data.connect
8
def receive_data(sender, **kw):
9
    if kw["data"].event_type == UnleashEventType.READY:
10
        print("SDK is ready: toggles loaded from Unleash or backup")
11
    elif kw["data"].event_type == UnleashEventType.FETCHED:
12
        print("Fetched new feature flags:", kw["data"].features)
13
14
def example_callback(event: UnleashEvent):
15
    send_data.send('anonymous', data=event)
16
17
client = UnleashClient(
18
    url="https://YOUR-API-URL",
19
    app_name="my-python-app",
20
    custom_headers={'Authorization': '<API token>'},
21
    event_callback=example_callback
22
)
23
client.initialize_client()
24
client.is_enabled("testFlag")

Custom cache

By default, the Python SDK stores feature flags in an on-disk cache using fcache. If you need a different storage backend, for example, Redis, memory-only, or a custom database, you can provide your own cache implementation.

Below is an example custom CustomCache using fcache under the hood.

1
from typing import Optional, Any
2
from UnleashClient.cache import BaseCache
3
from fcache.cache import FileCache as _FileCache
4
5
class CustomCache(BaseCache):
6
    # This is specific for FileCache.  Depending on the cache you're using, this may look different!
7
    def __init__(self, name: str, directory: Optional[str] = None):
8
        self._cache = _FileCache(name, app_cache_dir=directory)
9
10
    def set(self, key: str, value: Any):
11
        self._cache[key] = value
12
        self._cache.sync()
13
14
    def mset(self, data: dict):
15
        self._cache.update(data)
16
        self._cache.sync()
17
18
    def get(self, key: str, default: Optional[Any] = None):
19
        return self._cache.get(key, default)
20
21
    def exists(self, key: str):
22
        return key in self._cache
23
24
    def destroy(self):
25
        return self._cache.delete()

Pass your cache instance to the client with the cache argument:

1
client = UnleashClient(
2
    url="https://YOUR-API-URL",
3
    app_name="my-python-app",
4
    cache=CustomCache("my-cache")
5
)

Running in multi-process setups

The Python SDK runs a background thread to keep feature flags in sync with the Unleash server. Some runtime environments, like WSGI servers and Celery workers, need extra setup to make sure the SDK works correctly.

WSGI

When using WSGI servers (e.g., for Flask or Django apps), be aware that:

• Many WSGI setups disable threading by default. The SDK needs threads to poll for updates in the background.
• Make sure to set enable-threads in your WSGI config.

When running under uWSGI with multiple processes (using the --processes option), you may need to enable the lazy-apps option. This ensures each process gets a fresh SDK instance.

See The Art of Graceful Reloading for more details.

Celery

When using the SDK in Celery tasks, make sure you initialize it inside the worker_process_init event. Otherwise, the worker may run but won’t poll for feature flag updates.

1
from UnleashClient import UnleashClient
2
from celery.signals import worker_process_init
3
4
client = UnleashClient(
5
    url="https://YOUR-API-URL",
6
    app_name="my-python-app",
7
    custom_headers={'Authorization': '<API token>'}
8
)
9
10
@worker_process_init.connect
11
def configure_workers(sender=None, conf=None, **kwargs):
12
    client.initialize_client()

Migrating to v6

If you use custom strategies or access the features property on the Unleash Client, read the complete v6 migration guide before upgrading.