Unleash Yggdrasil Engine

1.3.0 · active · verified Sat Apr 11

yggdrasil-engine is a Python package that provides the core evaluation logic for Unleash feature flags. Implemented in Rust and exposed to Python via PyO3, it offers a high-performance, consistent, and cross-language engine for feature flag evaluation. It is primarily an internal dependency of the UnleashClient Python SDK, ensuring fast and reliable local flag evaluation. The current version is 1.3.0. Releases are typically tied to updates in the Unleash feature flag system.

Warnings

gotcha Direct Usage vs. UnleashClient: Most users should interact with the `UnleashClient` Python SDK, which internally uses `yggdrasil-engine`. Direct interaction with `yggdrasil-engine`'s API is uncommon and may expose lower-level details not intended for general application development.
Fix: Use `UnleashClient` for feature flag management; `yggdrasil-engine` is an underlying dependency that handles the efficient evaluation.
gotcha Rust Toolchain for Source Builds: While `yggdrasil-engine` provides pre-compiled Python wheels, building from source or contributing to the project requires a Rust toolchain and `maturin` for PyO3 bindings. Standard `pip install` typically handles pre-built binaries.
Fix: For development from source, ensure Rust and `maturin` are installed. For general usage, `pip install yggdrasil-engine` should suffice by leveraging pre-built wheels.
gotcha Evaluation Performance Context: `yggdrasil-engine` offers evaluation in hundreds of nanoseconds, making it extremely fast. However, the overall performance of feature flag checks in an application will largely be dominated by network latency (fetching flags from the Unleash server) rather than the engine's evaluation speed.
Fix: Focus on optimizing `UnleashClient`'s refresh intervals and caching strategies to minimize network calls, rather than concerns about the `yggdrasil-engine`'s internal evaluation speed.
breaking Breaking changes in the UnleashClient SDK (e.g., migration to v6) may indirectly impact how `yggdrasil-engine` is consumed or the expected format of inputs if the `UnleashClient`'s internal API changes its interaction with the engine. Always consult the `UnleashClient` migration guides when upgrading.
Fix: Refer to the `UnleashClient` migration documentation for guidance when upgrading, especially between major versions.

Install

pip install yggdrasil-engine Install yggdrasil-engine

Imports

UnleashEngine
```
from yggdrasil_engine.engine import UnleashEngine
```
While this is the direct import, users typically interact with UnleashClient, which uses this internally. Direct instantiation of UnleashEngine is uncommon for end-users.

Quickstart

The `yggdrasil-engine` library serves as a low-level, high-performance evaluation engine. End-users typically interact with the higher-level `UnleashClient` Python SDK, which abstracts away the complexities of the underlying engine. This quickstart demonstrates how to use `UnleashClient` to evaluate feature flags, which implicitly utilizes `yggdrasil-engine`.

import os
from UnleashClient import UnleashClient

# NOTE: yggdrasil-engine is an internal dependency of UnleashClient.
# Most users will interact with UnleashClient, which leverages yggdrasil-engine
# for high-performance feature flag evaluation.

# Configure UnleashClient (using environment variables for sensitive data)
unleash_url = os.environ.get('UNLEASH_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', 'my-instance')
unleash_api_token = os.environ.get('UNLEASH_API_TOKEN', '')

client = UnleashClient(
    url=unleash_url,
    app_name=unleash_app_name,
    instance_id=unleash_instance_id,
    custom_headers={'Authorization': unleash_api_token} if unleash_api_token else None
)

# Initialize the client. This will fetch feature flags from the Unleash server.
client.initialize_client()

# Check if a feature flag is enabled
feature_name = "my-awesome-feature"
is_enabled = client.is_enabled(feature_name)

if is_enabled:
    print(f"Feature '{feature_name}' is enabled!")
else:
    print(f"Feature '{feature_name}' is disabled.")

# Get a variant for a feature flag
variant = client.get_variant("my-variant-feature", context={'userId': 'user123'})
print(f"Variant for 'my-variant-feature': {variant['name']}")

# Clean up resources when done
client.destroy()

view raw JSON →