wagtail-flags 2.0.4

Defining flags

Flags are defined in Django settings with the conditions in which they are enabled.

FLAGS = {
  'FLAG_WITH_EMPTY_CONDITIONS': {}
  'MY_FLAG': {
    'condition name': 'value flag is expected to match to be enabled',
    'user': 'lady.liberty'
  }
}

The set of conditions can be none (flag will never be enabled), one (only condition that has to be met for the flag to be enabled), or many (all have to be met for the flag to be enabled).

Additional conditions can be added in the Django or Wagtail admin for any defined flag (illustrated in Usage). Conditions added in the Django or Wagtail admin can be changed without restarting Django, conditions defined in settings.py cannot.

Built-in conditions

Wagtail-Flags comes with the following conditions built-in:

FLAGS = {'MY_FLAG': {'boolean': True}}

FLAGS = {'MY_FLAG': {'user': 'jane.doe'}}

FLAGS = {'MY_FLAG': {'anonymous: False}}

FLAGS = {'MY_FLAG': {'parameter': 'my_flag_param'}}

FLAGS = {'MY_FLAG': {'path': '/flagged/path'}}

FLAGS = {'MY_FLAG': {'site': 'staging.mysite.com'}}

flag_state(flag_name, **kwargs)

Return the value for the flag (True or False) by passing kwargs to its conditions.

flag_enabled(flag_name, **kwargs)

Returns True if a flag is enabled by passing kwargs to its conditions, otherwise returns False.

if flag_enabled('MY_FLAG', request=a_request):
    print("My feature flag is enabled")

flag_disabled(flag_name, **kwargs)

Returns True if a flag is disabled by passing kwargs to its conditions, otherwise returns False.

if flag_disabled('MY_FLAG', request=a_request):
    print(“My feature flag is disabled”)

flag_check(flag_name, state, fallback=None, **kwargs)

Check that a given flag has the given state. If the state does not match, perform the fallback.

Note, because flags that do not exist are taken to be False by default, @flag_check('MY_FLAG', False) and @flag_check('MY_FLAG', None) will both succeed if MY_FLAG does not exist.

from flags.decorators import flag_check

@flag_check('MY_FLAG', True)
def view_requiring_flag(request):
    return HttpResponse('flag was set')

@flag_check('MY_OTHER_FLAG', False)
def view_when_flag_is_not_set(request):
    return HttpResponse('flag was set')

def other_view(request):
    return HttpResponse('flag was not set')

@flag_check('MY_FLAG_WITH_FALLBACK', True, fallback=other_view)
def view_with_fallback(request):
    return HttpResponse('flag was set')

flag_required(flag_name, fallback_view=None, pass_if_set=True)

Require the given flag to be enabled.

from flags.decorators import flag_required

@flag_required('MY_FLAG')
def view_requiring_flag(request):
    return HttpResponse('flag was set')

def other_view(request):
    return HttpResponse('flag was not set')

@flag_required('MY_FLAG_WITH_FALLBACK', fallback_view=other_view)
def view_with_fallback(request):
    return HttpResponse('flag was set')

flagged_url(flag_name, regex, view, kwargs=None, name=None, state=True, fallback=None)

Make a URL depend on the state of a feature flag. flagged_url() can be used in place of Django’s url().

fallback can be a a set of include()ed patterns, but the regular expressions in the fallback includes must match the regular expression for the URL or includes exactly.

urlpatterns = [
    flagged_url('MY_FLAG', r'^an-url$', view_requiring_flag, state=True),
    flagged_url('MY_FLAG_WITH_FALLBACK', r'^another-url$', view_with_fallback,
                state=True, fallback=other_view)
    flagged_url('MY_FLAGGED_INCLUDE', r'^myapp$', include('myapp.urls'),
                state=True, fallback=other_view)
    flagged_url('MY_NEW_APP_FLAG', r'^mynewapp$', include('mynewapp.urls'),
                state=True, fallback=include('myoldapp.urls'))
]

flagged_urls(flag_name, state=True, fallback=None)

Flag multiple URLs in the same context. Returns function that can be used in place of Django’s url() that wraps flagged_url(). Can take an optional fallback view that will apply to all urls.

with flagged_urls('MY_FLAG') as url:
    flagged_url_patterns = [
        url(r'^an-url$', view_requiring_flag),
    ]

urlpatterns = urlpatterns + flagged_url_patterns

flag_enabled

Returns True if a flag is enabled by passing the current request to its conditions, otherwise returns False.

{% flag_enabled 'MY_FLAG' as my_flag %}
{% if my_flag %}
  <div class="m-global-banner">
    I’m the result of a feature flag.
  </div>
{% endif %}

flag_disabled

Returns True if a flag is disabled by passing the current request to its conditions, otherwise returns False.

{% flag_disabled 'MY_FLAG' as my_flag %}
{% if my_flag %}
  <div class="m-global-banner">
    I’m the result of a feature flag that is not enabled.
  </div>
{% endif %}

flag_enabled

Returns True if a flag is enabled by for the given request, otherwise returns False.

{% if flag_enabled('MY_FLAG', request) %}
  <div class="m-global-banner">
    I’m the result of a feature flag.
  </div>
{% endif %}

flag_disabled

Returns True if a flag is disabled by passing the current request to its conditions, otherwise returns False. Returns True if a flag is disabled by for the given request, otherwise returns False.

{% if flag_disabled('MY_FLAG', request) %}
  <div class="m-global-banner">
    I’m the result of a feature flag that is not enabled.
  </div>
{% endif %}

conditions.register(condition_name, fn=None)

Register a new condition, either as a decorator:

from flags import conditions

@conditions.register('path')
def path_condition(path, request=None, **kwargs):
    return request.path.startswith(path)

Or as a function call:

def path_condition(path, request=None, **kwargs):
    return request.path.startswith(path)

conditions.register('path', fn=path_condition)

conditions.RequiredForCondition

Exception intended to be raised when a condition is not given a keyword argument it requires for evaluation.

@conditions.register('path')
def path_condition(path, request=None, **kwargs):
    if request is None:
        raise conditions.RequiredForCondition(
            "request is required for condition 'path'")

    return request.path.startswith(path)