Python feature management

Python feature management library provides a way to develop and expose application functionality based on feature flags. Once a new feature is developed, many applications have special requirements, such as when the feature should be enabled and under what conditions. This library provides a way to define these relationships, and also integrates into common Python code patterns to make exposing these features possible.

Feature flags provide a way for Python applications to turn features on or off dynamically. Developers can use feature flags in simple use cases like conditional statements.

Here are some of the benefits of using Python feature management library:

• A common convention for feature management

• Low barrier to entry

  • Supports JSON feature flag setup

• Feature flag lifetime management

  • Configuration values can change in real-time; feature flags can be consistent across the entire request

• Simple to complex scenarios covered

  • Toggle on/off features through declarative configuration file
  • Dynamically evaluate state of feature based on call to server

  The Python feature management library is open source. For more information, visit the GitHub repo.

Feature flags

Feature flags are composed of two parts, a name and a list of feature-filters that are used to turn on the feature.

Feature filters

Feature filters define a scenario for when a feature should be enabled. When a feature is evaluated for whether it is on or off, its list of feature filters is traversed until one of the filters decides the feature should be enabled. At this point, the feature is considered enabled and traversal through the feature filters stops. If no feature filter indicates that the feature should be enabled, it's considered disabled.

As an example, a Microsoft Edge browser feature filter could be designed. This feature filter would activate any features attached to it, as long as an HTTP request is coming from Microsoft Edge.

Feature flag configuration

A Python dictionary is used to define feature flags. The dictionary is composed of feature names as keys and feature flag objects as values. The feature flag object is a dictionary that contains a conditions key, which itself contains the client_filters key. The client_filters key is a list of feature filters that are used to determine if the feature should be enabled.

Feature flag declaration

The feature management library supports json as a feature flag source. Below we have an example of the format used to set up feature flags in a JSON file.

{
    "feature_management": {
        "feature_flags": [
            {
                "id": "FeatureT",
                "enabled": "true"
            },
            {
                "id": "FeatureU",
                "enabled": "false"
            },
            {
                "id": "FeatureV",
                "enabled": "true",
                "conditions": {
                    "client_filters": [
                        {
                            "name": "Microsoft.TimeWindow",
                            "parameters": {
                                "Start": "Wed, 01 May 2019 13:59:59 GMT",
                                "End": "Mon, 01 Jul 2019 00:00:00 GMT"
                            }
                        }
                    ]
                }
            }
        ]
    }
}

The feature_management section of the json document is used by convention to load feature flag settings. The feature_flags section is a list of the feature flags that are loaded into the library. In the section above, we see three different features. Features define their feature filters using the client_filters property, inside of conditions. In the feature filters for FeatureT, we see enabled is on with no filters defined, resulting in FeatureT always returning true . FeatureU is the same as FeatureT but with enabled is false resulting in the feature always returning false. FeatureV specifies a feature filter named Microsoft.TimeWindow. FeatureV is an example of a configurable feature filter. We can see in the example that the filter has a parameters property. The parameters property is used to configure the filter. In this case, the start and end times for the feature to be active are configured.

The detailed schema of the feature_management section can be found here.

Advanced: The usage of colon ':' is forbidden in feature flag names.

On/off declaration

The following snippet demonstrates an alternative way to define a feature that can be used for on/off features.

{
    "feature_management": {
        "feature_flags": [
            {
                "id": "FeatureT",
                "enabled": "true"
            },
            {
                "id": "FeatureX",
                "enabled": "false"
            }
        ]
    }
}

Requirement_type

The requirement_type property of a feature flag is used to determine if the filters should use Any or All logic when evaluating the state of a feature. If requirement_type isn't specified, the default value is Any.

• Any means only one filter needs to evaluate to true for the feature to be enabled.
• All means every filter needs to evaluate to true for the feature to be enabled.

A requirement_type of All changes the traversal. First, if there are no filters, the feature is disabled. Then, the feature filters are traversed until one of the filters decides that the feature should be disabled. If no filter indicates that the feature should be disabled, it's considered enabled.

{
    "feature_management": {
        "feature_flags": [
            {
                "id": "FeatureW",
                "enabled": "true",
                "conditions": {
                    "requirement_type": "All",
                    "client_filters": [
                        {
                            "name": "Microsoft.TimeWindow",
                            "parameters": {
                                "Start": "Wed, 01 May 2019 13:59:59 GMT",
                                "End": "Mon, 01 Jul 2019 00:00:00 GMT"
                            }
                        },
                        {
                            "name": "Percentage",
                            "parameters": {
                                "Value": "50"
                            }
                        }
                    ]
                }
            },
        ]
    }
}

In the above example, FeatureW specifies a requirement_type of All, meaning all of its filters must evaluate to true for the feature to be enabled. In this case, the feature is enabled for 50% of users during the specified time window.

Consumption

The basic form of feature management is checking if a feature flag is enabled and then performing actions based on the result. Checking the state of a feature flag is done through FeatureManager's is_enabled method.

…
feature_manager = FeatureManager(feature_flags)
…
if feature_manager.is_enabled("FeatureX"):
    # Do something

The feature_flags provided to FeatureManager can either be the AzureAppConfigurationProvider or a dictionary of feature flags.

Implementing a feature filter

Creating a feature filter provides a way to enable features based on criteria that you define. To implement a feature filter, the FeatureFilter interface must be implemented. FeatureFilter has a single method named evaluate. When a feature specifies that it can be enabled for a feature filter, the evaluate method is called. If evaluate returns true, it means the feature should be enabled.

The following snippet demonstrates how to add a customized feature filter MyCustomFilter.

feature_manager = FeatureManager(feature_flags, feature_filters=[MyCustomFilter()])

Feature filters are registered by providing them to the property feature_filters when creating FeatureManager. If a custom feature filter needs any context, they can be passed in when calling is_enabled using kwargs.

Filter alias attribute

When a feature filter is registered for a feature flag, the name of the filter is used as the alias by default.

The identifier for the feature filter can be overridden by using the @FeatureFilter.alias("MyFilter"). A feature filter can be decorated with this attribute to declare the name that should be used in configuration to reference this feature filter within a feature flag.

Missing feature filters

If a feature is configured to be enabled for a specific feature filter and that feature filter isn't registered, a ValueError exception is raised when the feature is evaluated.

Built-in feature filters

There are a two feature filters that come with the FeatureManagement package: TimeWindowFilter, and TargetingFilter.

Each of the built-in feature filters has its own parameters. Here's the list of feature filters along with examples.

Microsoft.TimeWindow

This filter provides the capability to enable a feature based on a time window. If only End is specified, the feature is considered on until that time. If only Start is specified, the feature is considered on at all points after that time.

"client_filters": [
    {
        "name": "Microsoft.TimeWindow",
        "parameters": {
            "Start": "Wed, 01 May 2019 13:59:59 GMT",
            "End": "Mon, 01 Jul 2019 00:00:00 GMT"
        }
    }
]     

Microsoft.Targeting

This filter provides the capability to enable a feature for a target audience. An in-depth explanation of targeting is explained in the targeting section below. The filter parameters include an Audience object that describes users, groups, excluded users/groups, and a default percentage of the user base that should have access to the feature. Each group object that is listed in the Groups section must also specify what percentage of the group's members should have access. If a user is specified in the Exclusion section, either directly or if the user is in an excluded group, the feature is disabled. Otherwise, if a user is specified in the Users section directly, or if the user is in the included percentage of any of the group rollouts, or if the user falls into the default rollout percentage then that user will have the feature enabled.

"client_filters": [
    {
        "name": "Microsoft.Targeting",
        "parameters": {
            "Audience": {
                "Users": [
                    "Jeff",
                    "Alicia"
                ],
                "Groups": [
                    {
                        "Name": "Ring0",
                        "RolloutPercentage": 100
                    },
                    {
                        "Name": "Ring1",
                        "RolloutPercentage": 50
                    }
                ],
                "DefaultRolloutPercentage": 20,
                "Exclusion": {
                    "Users": [
                        "Ross"
                    ],
                    "Groups": [
                        "Ring2"
                    ]
                }
            }
        }
    }
]

Targeting

Targeting is a feature management strategy that enables developers to progressively roll out new features to their user base. The strategy is built on the concept of targeting a set of users known as the target audience. An audience is made up of specific users, groups, excluded users/groups, and a designated percentage of the entire user base. The groups that are included in the audience can be broken down further into percentages of their total members.

The following steps demonstrate an example of a progressive rollout for a new 'Beta' feature:

1. Individual users Jeff and Alicia are granted access to the Beta
2. Another user, Mark, asks to opt in and is included.
3. Twenty percent of a group known as "Ring1" users are included in the Beta.
4. The number of "Ring1" users included in the beta is bumped up to 100 percent.
5. Five percent of the user base is included in the beta.
6. The rollout percentage is bumped up to 100 percent and the feature is completely rolled out.

This strategy for rolling out a feature is built in to the library through the included Microsoft.Targeting feature filter.

Targeting a user

Either a user can be specified directly in the is_enabled call or a TargetingContxt can be used to specify the user and optional group.

# Directly specifying the user
result = is_enabled(feature_flags, "test_user")

# Using a TargetingContext
result = is_enabled(feature_flags, TargetingContext(user_id="test_user", groups=["Ring1"]))

Targeting exclusion

When defining an audience, users and groups can be excluded from the audience. Exclusions are useful for when a feature is being rolled out to a group of users, but a few users or groups need to be excluded from the rollout. Exclusion is defined by adding a list of users and groups to the Exclusion property of the audience.

"Audience": {
    "Users": [
        "Jeff",
        "Alicia"
    ],
    "Groups": [
        {
            "Name": "Ring0",
            "RolloutPercentage": 100
        }
    ],
    "DefaultRolloutPercentage": 0
    "Exclusion": {
        "Users": [
            "Mark"
        ]
    }
}

In the above example, the feature is enabled for users named Jeff and Alicia. It's also enabled for users in the group named Ring0. However, if the user is named Mark, the feature is disabled, regardless of if they are in the group Ring0 or not. Exclusions take priority over the rest of the targeting filter.

class Variant:
    def __init__(self, name: str, configuration: Any):
        self._name = name
        self._configuration = configuration

    @property
    def name(self) -> str:
        """
        The name of the variant.
        :rtype: str
        """
        return self._name

    @property
    def configuration(self) -> Any:
        """
        The configuration of the variant.
        :rtype: Any
        """
        return self._configuration

…
variant = print(feature_manager.get_variant("TestVariants", TargetingContext(user_id="Adam"))

variantConfiguration = variant.configuration;

// Do something with the resulting variant and its configuration

{
    "feature_management": {
        "feature_flags": [
            {
                "id": "MyVariantFeatureFlag",
                "enabled": true,
                "allocation": {
                    "default_when_enabled": "Small",
                    "group": [
                        {
                            "variant": "Big",
                            "groups": [
                                "Ring1"
                            ]
                        }
                    ]
                },
                "variants": [
                    { 
                        "name": "Big"
                    },  
                    { 
                        "name": "Small"
                    } 
                ]
            }
        ]
    }
}

{
    "feature_management": {
        "feature_flags": [
            {
                "id": "MyVariantFeatureFlag",
                "variants": [
                    { 
                        "name": "Big", 
                        "configuration_value": {
                            "Size": 500
                        }
                    },  
                    { 
                        "name": "Small", 
                        "configuration_value": {
                            "Size": 300
                        }
                    } 
                ]
            }
        ]
    }
}

"allocation": { 
    "default_when_enabled": "Small", 
    "default_when_disabled": "Small",  
    "user": [ 
        { 
            "variant": "Big", 
            "users": [ 
                "Marsha" 
            ] 
        } 
    ], 
    "group": [ 
        { 
            "variant": "Big", 
            "groups": [ 
                "Ring1" 
            ] 
        } 
    ],
    "percentile": [ 
        { 
            "variant": "Big", 
            "from": 0, 
            "to": 10 
        } 
    ], 
    "seed": "13973240" 
},
"variants": [
    { 
        "name": "Big", 
        "configuration_value": "500px"
    },  
    { 
        "name": "Small", 
        "configuration_value": "300px"
    } 
]

{
    "id": "MyVariantFeatureFlag",
    "enabled": true,
    "allocation": {
        "percentile": [
            {
                "variant": "On",
                "from": 10,
                "to": 20
            }
        ],
        "default_when_enabled":  "Off",
        "seed": "Enhanced-Feature-Group"
    },
    "variants": [
        {
            "name": "On"
        },
        {
            "name": "Off",
            "status_override": "Disabled"
        }
    ]
}

{
    "feature_management": {
        "feature_flags": [
            {
                "id": "MyFeatureFlag",
                "enabled": true,
                "telemetry": {
                    "enabled": true
                }
            }
        ]
    }
}

feature_manager = FeatureManager(feature_flags, on_feature_evaluated=publish_telemetry)

from azure.monitor.opentelemetry import configure_azure_monitor

configure_azure_monitor(
        connection_string="InstrumentationKey=00000000-0000-0000-0000-000000000000"
    )

Next steps

To learn how to use feature flags in your applications, continue to the following quickstarts.

To learn how to use feature filters, continue to the following tutorials.

To learn how to run experiments with variant feature flags, continue to the following tutorial.