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

Migrating to v6

If you use custom strategies or access the features property on the Unleash Client, read the complete migration guide before upgrading to v6.

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

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()

For more information about configuring UnleashClient, check out the project reference docs!

Checking if a feature is enabled

A check of a simple toggle:

client.is_enabled("my_toggle")

To supply application context, use the second positional argument:

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

Fallback function and default values

You can specify a fallback function for cases where the client doesn't recognize the toggle by using the fallback_function keyword argument:

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

client.is_enabled("my_toggle", fallback_function=custom_fallback)

You can also use the fallback_function argument to replace the obsolete default_value keyword argument by using a lambda that ignores its inputs. Whatever the lambda returns will be used as the default value.

client.is_enabled("my_toggle", fallback_function=lambda feature_name, context: True)

The fallback function must accept the feature name and context as positional arguments in that order.

The client will evaluate the fallback function only if an exception occurs when calling the is_enabled() method. This happens when the client can't find the feature flag. The client may also throw other, general exceptions.

For more information about usage, see the Usage documentation.

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("variant_toggle", context)

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

For more information about variants, see the Variant documentation.

Developing

For development, you'll need to setup the environment to run the tests. This repository is using tox to run the test suite to test against multiple versions of Python. Running the tests is as simple as running this command in the makefile:

tox -e py311

This command will take care of downloading the client specifications and putting them in the correct place in the repository, and install all the dependencies you need.

However, there are some caveats to this method. There is no easy way to run a single test, and running the entire test suite can be slow.

Manual setup

First, make sure you have pip or pip3 installed.

Then setup your viritual environment:

Linux & Mac:

python3 -m venv venv
source venv/bin/activate

Windows + cmd:

python -m venv venv
venv\Scripts\activate.bat

Powershell:

python -m venv venv
venv\Scripts\activate.bat

Once you've done your setup, run:

pip install -r requirements.txt

Run the get-spec script to download the client specifications tests:

./scripts/get-spec.sh

Now you can run the tests by running pytest in the root directory.

In order to run a single test, run the following command:

pytest testfile.py::function_name

# example: pytest tests/unit_tests/test_client.py::test_consistent_results

Linting

In order to lint all the files you can run the following command:

make fmt

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-6.2.2.tar.gz (39.6 kB view details)

Uploaded Source

Built Distribution

unleashclient-6.2.2-py3-none-any.whl (30.9 kB view details)

Uploaded Python 3

File details

Details for the file unleashclient-6.2.2.tar.gz.

File metadata

  • Download URL: unleashclient-6.2.2.tar.gz
  • Upload date:
  • Size: 39.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for unleashclient-6.2.2.tar.gz
Algorithm Hash digest
SHA256 d6efd8b9e2f93afe980502f73627af1b3dcf1f202c89e53af1cb53ee9a94ba68
MD5 2b0088f4bb2d31179b7a8b399b8dc0c1
BLAKE2b-256 044e30e32919f0da1540ffad63dc5c1469efcc34d1da35125dc344b70e66caf9

See more details on using hashes here.

Provenance

The following attestation bundles were made for unleashclient-6.2.2.tar.gz:

Publisher: release-package.yml on Unleash/unleash-client-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file unleashclient-6.2.2-py3-none-any.whl.

File metadata

  • Download URL: unleashclient-6.2.2-py3-none-any.whl
  • Upload date:
  • Size: 30.9 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for unleashclient-6.2.2-py3-none-any.whl
Algorithm Hash digest
SHA256 f6cc587b034a0a30df7d9f2fbc7d4ef7d33c887bf1163a200610f960484682db
MD5 d98d0619b73482d94cf1fdbbfb6a2c5e
BLAKE2b-256 0b678c0a7bc1945fb1d0a9bb28cdeb8222d504bbe2e3662fa647e160378e60f3

See more details on using hashes here.

Provenance

The following attestation bundles were made for unleashclient-6.2.2-py3-none-any.whl:

Publisher: release-package.yml on Unleash/unleash-client-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

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