Python OpenFeature provider

The Unleash OpenFeature Python provider lets Python applications evaluate Unleash feature flags through the OpenFeature API.

The provider wraps the Unleash Python SDK and uses the same backend SDK behavior for polling, local evaluation, caching, metrics, and shutdown.

Requirements

• Python 3.10 or later

Installation

Install the provider. The provider declares the OpenFeature Python SDK and the Unleash Python SDK as dependencies, so you don’t need to add them separately.

$
pip install unleash-openfeature-python-provider

Configuration

Create an UnleashFlagProvider with the same options you would pass to the Unleash Python SDK client, then register it with OpenFeature. The provider builds and owns the Unleash client.

1
from openfeature import api
2
3
from unleash_openfeature_python_provider import UnleashFlagProvider
4
5
provider = UnleashFlagProvider(
6
    url="<YOUR_UNLEASH_URL>/api",
7
    app_name="my-python-app",
8
    custom_headers={"Authorization": "<YOUR_API_TOKEN>"},
9
)
10
11
api.set_provider_and_wait(provider)

set_provider_and_wait starts the Unleash client and waits for startup to complete before the provider is registered for use. After startup, the SDK continues refreshing feature flag data in the background.

Evaluate a flag

Build an OpenFeature client and evaluate flags through the OpenFeature API:

1
from openfeature import api
2
from openfeature.evaluation_context import EvaluationContext
3
4
client = api.get_client()
5
6
context = EvaluationContext(targeting_key="user-123")
7
8
enabled = client.get_boolean_value("my-feature", False, context)

The provider supports all OpenFeature evaluation methods. Boolean evaluation uses the flag’s enabled state. All other types resolve from the payload of the flag’s variant:

• String values accept string and csv payloads.
• Integer and float values accept number payloads.
• Object values accept json payloads.

If the flag doesn’t exist, the flag is disabled, or the variant payload is missing, has a different type, or can’t be parsed, the evaluation returns the default value. The detail methods, such as get_string_details, additionally report the evaluation reason and the assigned variant name.

Context mapping

The provider maps the OpenFeature evaluation context to an Unleash context before each evaluation.

The following OpenFeature fields map directly to top-level Unleash context fields:

• currentTime
• userId
• sessionId
• remoteAddress
• environment
• appName

If you set targeting_key, the provider maps it to userId. The targeting_key takes precedence over a userId field set on the evaluation context.

The provider adds all other scalar fields, such as strings, numbers, booleans, and date-time values, to the Unleash context properties. It discards nested values, such as lists and dictionaries, and logs each discarded field at debug level using the standard logging module.

Shutdown

Shut down OpenFeature when your application exits. This also shuts down the underlying Unleash client.

1
api.shutdown()

Example

To try the provider against your Unleash instance, clone the provider repository and run the boolean flag example with your Unleash URL and API token:

$
uv run python examples/boolean_flag.py \
>
  --url '<YOUR_UNLEASH_URL>/api' \
>
  --api-key "$UNLEASH_API_KEY" \
>
  --flag-key my-feature \
>
  --targeting-key user-123