UnleashClient

class UnleashClient.UnleashClient(url: str, app_name: str, environment: str = 'default', instance_id: str = 'unleash-client-python', refresh_interval: int = 15, refresh_jitter: int | None = None, metrics_interval: int = 60, metrics_jitter: int | None = None, disable_metrics: bool = False, disable_registration: bool = False, custom_headers: dict | None = None, custom_options: dict | None = None, request_timeout: int = 30, request_retries: int = 3, custom_strategies: dict | None = None, cache_directory: str | None = None, project_name: str | None = None, verbose_log_level: int = 30, cache: BaseCache | None = None, scheduler: BaseScheduler | None = None, scheduler_executor: str | None = None, multiple_instance_mode: InstanceAllowType = InstanceAllowType.WARN, event_callback: Callable[[UnleashEvent], None] | None = None)

A client for the Unleash feature toggle system.

Parameters:

  • url – URL of the unleash server, required.

  • app_name – Name of the application using the unleash client, required.

  • environment – Name of the environment using the unleash client, optional & defaults to “default”.

  • instance_id – Unique identifier for unleash client instance, optional & defaults to “unleash-client-python”

  • refresh_interval – Provisioning refresh interval in seconds, optional & defaults to 15 seconds

  • refresh_jitter – Provisioning refresh interval jitter in seconds, optional & defaults to None

  • metrics_interval – Metrics refresh interval in seconds, optional & defaults to 60 seconds

  • metrics_jitter – Metrics refresh interval jitter in seconds, optional & defaults to None

  • disable_metrics – Disables sending metrics to unleash server, optional & defaults to false.

  • disable_registration – Disables registration with unleash server, optional & defaults to false.

  • custom_headers – Default headers to send to unleash server, optional & defaults to empty.

  • custom_options – Default requests parameters, optional & defaults to empty. Can be used to skip SSL verification.

  • custom_strategies – Dictionary of custom strategy names : custom strategy objects.

  • cache_directory – Location of the cache directory. When unset, FCache will determine the location.

  • verbose_log_level – Numerical log level (https://docs.python.org/3/library/logging.html#logging-levels) for cases where checking a feature flag fails.

  • cache – Custom cache implementation that extends UnleashClient.cache.BaseCache. When unset, UnleashClient will use Fcache.

  • scheduler – Custom APScheduler object. Use this if you want to customize jobstore or executors. When unset, UnleashClient will create it’s own scheduler.

  • scheduler_executor – Name of APSCheduler executor to use if using a custom scheduler.

  • multiple_instance_mode – Determines how multiple instances being instantiated is handled by the SDK, when set to InstanceAllowType.BLOCK, the client constructor will fail when more than one instance is detected, when set to InstanceAllowType.WARN, multiple instances will be allowed but log a warning, when set to InstanceAllowType.SILENTLY_ALLOW, no warning or failure will be raised when instantiating multiple instances of the client. Defaults to InstanceAllowType.WARN

  • event_callback – Function to call if impression events are enabled. WARNING: Depending on your event library, this may have performance implications!

Params request_timeout:

Timeout for requests to unleash server in seconds, optional & defaults to 30 seconds

Params request_retries:

Number of retries for requests to unleash server, optional & defaults to 3

initialize_client(fetch_toggles: bool = True) → None

Initializes client and starts communication with central unleash server(s).

This kicks off:

  • Client registration

  • Provisioning poll

  • Stats poll

If fetch_toggles is False, feature toggle polling will be turned off and instead the client will only load features from the cache. This is usually used to cater the multi-process setups, e.g. Django, Celery, etc.

This will raise an exception on registration if the URL is invalid. It is done automatically if called inside a context manager as in:

with UnleashClient(
    url="https://foo.bar",
    app_name="myClient1",
    instance_id="myinstanceid"
    ) as client:
    pass
destroy() → None

Gracefully shuts down the Unleash client by stopping jobs, stopping the scheduler, and deleting the cache.

You shouldn’t need this too much!

is_enabled(feature_name: str, context: dict | None = None, fallback_function: Callable | None = None) → bool

Checks if a feature toggle is enabled.

Notes:

  • If client hasn’t been initialized yet or an error occurs, flat will default to false.

Parameters:

  • feature_name – Name of the feature

  • context – Dictionary with context (e.g. IPs, email) for feature toggle.

  • fallback_function – Allows users to provide a custom function to set default value.

Returns:

Feature flag result

get_variant(feature_name: str, context: dict | None = None) → dict

Checks if a feature toggle is enabled. If so, return variant.

Notes:

  • If client hasn’t been initialized yet or an error occurs, flat will default to false.

Parameters:

  • feature_name – Name of the feature

  • context – Dictionary with context (e.g. IPs, email) for feature toggle.

Returns:

Variant and feature flag status.