Unleash Python Client SDK

Warnings

• breaking Direct access to `UnleashClient.features` was removed in v6.0.0. The internal representation of feature flags is no longer publicly accessible.
  Fix: Instead of `client.features`, use `client.feature_definitions()` which returns a dictionary of feature flag names, types, and projects. If you relied on the internal structure of feature flag objects, you'll need to refactor your code.
• breaking Custom activation strategies require an updated interface in v6.0.0. They no longer inherit from a base class, and the `apply` method's signature changed to `apply(self, parameters: dict, context: dict = None) -> bool`.
  Fix: Refactor custom strategy classes to remove inheritance from `Strategy` and update the `apply` method signature. The `load_provisioning()` method functionality is now handled directly within the `apply` method using the `parameters` argument. Strategies must be registered as instances, not class objects.
• deprecated The `default_value` argument in the `is_enabled()` method was deprecated in v4.0.0.
  Fix: While still functional, it's recommended to rely on a `fallback_function` for more robust default behavior when a feature flag is not found or cannot be evaluated, especially in resilient applications. If both `default_value` and `fallback_function` are provided, the client will `OR` their results.
• gotcha Upon initialization, feature flags will evaluate to `False` until the client has successfully synchronized with the Unleash API. This can lead to unexpected behavior during application startup.
  Fix: To prevent this, consider bootstrapping the client with a local or remote toggle configuration using a `FileCache` (or custom `BaseCache` implementation) and passing it during `UnleashClient` initialization. Alternatively, ensure your application handles the `False` state gracefully during the initial sync period.
• gotcha The SDK runs a background thread for fetching feature flags and sending metrics. This requires special consideration in multi-process environments like WSGI servers (e.g., Gunicorn, uWSGI) or Celery workers.
  Fix: Ensure `client.initialize_client()` and `client.destroy()` are called correctly within each worker process's lifecycle (e.g., in a `post_fork` hook for Gunicorn). Refer to the official documentation for specific guidance on running in multi-process setups to prevent issues with thread management and data consistency.

Install

• pip install UnleashClient Install latest version

Imports

• UnleashClient

  from UnleashClient import UnleashClient

  The primary class is directly importable from the top-level package. Avoid `import UnleashClient` and then `UnleashClient.UnleashClient()`.

Quickstart

This quickstart demonstrates how to initialize the Unleash client, connect to an Unleash server, and evaluate feature flags. It includes examples for checking simple boolean flags, using context for targeted evaluations, and retrieving feature variants. Remember to replace placeholder URLs and API tokens with your actual Unleash server details, ideally through environment variables. The `initialize_client()` method starts background synchronization, and `destroy()` gracefully shuts it down.

import os
from UnleashClient import UnleashClient

UNLEASH_URL = os.environ.get('UNLEASH_API_URL', 'http://localhost:4242/api')
UNLEASH_APP_NAME = os.environ.get('UNLEASH_APP_NAME', 'my-python-app')
UNLEASH_INSTANCE_ID = os.environ.get('UNLEASH_INSTANCE_ID', 'instance-1')
UNLEASH_API_TOKEN = os.environ.get('UNLEASH_API_TOKEN', 'YOUR_API_TOKEN_HERE') # Typically a server-side token

# Initialize the client
client = UnleashClient(
    url=UNLEASH_URL,
    app_name=UNLEASH_APP_NAME,
    instance_id=UNLEASH_INSTANCE_ID,
    custom_headers={'Authorization': UNLEASH_API_TOKEN}
)

# Start the client (connects to Unleash server, fetches flags, etc.)
client.initialize_client()

# Check if a feature is enabled
enabled = client.is_enabled("my_feature_flag")
print(f"Feature 'my_feature_flag' is enabled: {enabled}")

# Check with context
user_context = {
    "userId": "123",
    "sessionId": "abc",
    "properties": {"region": "us-east"}
}
enabled_for_user = client.is_enabled("user_specific_feature", user_context)
print(f"Feature 'user_specific_feature' is enabled for user 123: {enabled_for_user}")

# Get a variant
variant = client.get_variant("variant_toggle", user_context)
print(f"Variant for 'variant_toggle': {variant}")

# Gracefully shut down the client when no longer needed
client.destroy()