Skip to main content

Python client for the Unleash feature toggle system!

Project description

unleash-client-python

Coverage Status PyPI version PyPI - Python Version License: MIT

This is the Python client for Unleash. It implements Client Specifications 1.0 and checks compliance based on spec in unleash/client-specifications

What it supports:

  • Default activation strategies using 32-bit Murmurhash3
  • Custom strategies
  • Full client lifecycle:
    • Client registers with Unleash server
    • Client periodically fetches feature toggles and stores to on-disk cache
    • Client periodically sends metrics to Unleash Server
  • Tested on Linux (Ubuntu), OSX, and Windows

Check out the project documentation and the changelog.

Installation

Check out the package on Pypi!

pip install UnleashClient

For Flask Users

If you're looking into running Unleash from Flask, you might want to take a look at Flask-Unleash, the Unleash Flask extension. The extension builds upon this SDK to reduce the amount of boilerplate code you need to write to integrate with Flask. Of course, if you'd rather use this package directly, that will work too.

Usage

Initialization

from UnleashClient import UnleashClient

client = UnleashClient(
    url="https://unleash.herokuapp.com",
    app_name="my-python-app",
    custom_headers={'Authorization': '<API token>'})

client.initialize_client()

If you're running Unleash in a Docker container or self hosting, your URL should look like http://localhost:4242/api (with the /api suffix).

To clean up gracefully:

client.destroy()

If the client is already initialized, calling initialize_client() again will raise a warning. This is not recommended client usage as it results in unneccessary calls to the Unleash server.

Arguments

Argument Description Required? Type Default Value
url Unleash server URL Y String N/A
app_name Name of your program Y String N/A
environment Name of current environment N String default
instance_id Unique ID for your program N String unleash-client-python
refresh_interval How often the unleash client should check for configuration changes. N Integer 15
refresh_jitter Maximum delay added to refresh interval value. N Integer None
metrics_interval How often the unleash client should send metrics to server. N Integer 60
metrics_jitter Maximum delay added to sending metrics to server interval. N Integer None
disable_metrics Disables sending metrics to Unleash server. N Boolean F
disable_registration Disables registration with Unleash server. N Boolean F
custom_headers Custom headers to send to Unleash. N Dictionary {}
custom_strategies Custom strategies you'd like UnleashClient to support. N Dictionary {}
cache_directory Location of the cache directory. When unset, FCache will determine the location N Str Unset
project_name Unleash project Id to load feature flags from N Str ""
verbose_log_level Numerical log level (https://docs.python.org/3/library/logging.html#logging-levels) for cases where checking a feature flag fails. N Integer 30 (Warning)

Checking if a feature is enabled

A check of a simple toggle:

client.is_enabled("My Toggle")

Specifying a default value:

client.is_enabled("My Toggle", default_value=True)

Supplying application context:

app_context = {"userId": "test@email.com"}
client.is_enabled("User ID Toggle", app_context)

Supplying a fallback function:

def custom_fallback(feature_name: str, context: dict) -> bool:
    return True

client.is_enabled("My Toggle", fallback_function=custom_fallback)
  • Must accept the fature name and context as an argument.
  • Client will evaluate the fallback function only if exception occurs when calling the is_enabled() method i.e. feature flag not found or other general exception.
  • If both a default_value and fallback_function are supplied, client will define the default value by ORing the default value and the output of the fallback function.

Getting a variant

Checking for a variant:

context = {'userId': '2'}  # Context must have userId, sessionId, or remoteAddr.  If none are present, distribution will be random.

variant = client.get_variant("MyvariantToggle", context)

print(variant)
> {
>    "name": "variant1",
>    "payload": {
>        "type": "string",
>        "value": "val1"
>        },
>    "enabled": True
> }

For more information about variants, see the Variant documentation.

Running in a WSGI Context

WSGI is a fairly common way of running webserver applications for both Flask and Django, if you're running in WSGI there are a few caveats that you should be aware of:

  • By default WSGI removes the GIL and disables threading, this SDK requires threads to work for the background updates of feature toggles, without it, your application will run but will not reflect updates to state of feature toggles when changed. To get around this, you'll need to enable threading, you can do this by setting enable-threads in your WSGI configuration

  • If you need to scale out your application with multiple processes by setting the processes flag in your WSGI configuration, note that this can cause issues with updates as well, in order to resolve these, you'll also need to enable the lazy-apps flag in WSGI, this will cause each process to trigger a clean reload of your application. More information on the rammifcations of this change can be found here

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

UnleashClient-5.0.1.tar.gz (17.4 kB view hashes)

Uploaded Source

Built Distribution

UnleashClient-5.0.1-py3-none-any.whl (25.1 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page