Feature flags for Django projects

Common errors

• ModuleNotFoundError: No module named 'flags'

  cause The 'flags' app is not registered in Django's INSTALLED_APPS.
  fix Add `'flags'` to your `INSTALLED_APPS` list in `settings.py`.

• TypeError: 'dict' object is not iterable

  cause In `settings.FLAGS`, a flag's conditions are defined as a single dictionary instead of a list containing dictionaries, which was removed in Django-Flags 5.0.
  fix Change the flag definition in `settings.py` from `{'FLAG_NAME': {'condition': '...', 'value': ...}}` to `{'FLAG_NAME': [{'condition': '...', 'value': ...}]}` (a list of dictionaries).

• django.core.exceptions.ImproperlyConfigured: The 'request' context processor is required

  cause The `django.template.context_processors.request` is missing from your `TEMPLATES` context processors, which is necessary for many flag conditions and template tags.
  fix Add `'django.template.context_processors.request'` to the `'context_processors'` list within your `TEMPLATES` configuration in `settings.py`.

• 404 Not Found (for a URL managed by flagged_path)

  cause A `flagged_path` URL pattern was accessed, but the associated flag's conditions were not met and no `fallback` view was specified to handle this state.
  fix Either ensure the flag conditions are met, or provide a `fallback` view to `flagged_path` (e.g., `flagged_path('MY_FLAG', 'my-url/', my_view, fallback=fallback_view)`).

Warnings

• breaking As of Django-Flags 5.1.0, support for Python versions older than 3.10 has been removed. Projects using Python 3.9 or earlier must upgrade their Python environment before upgrading `django-flags`.
  Fix: Upgrade your Python environment to 3.10 or newer.
• breaking In Django-Flags 4.0, the `flags.template_functions.flag_enabled` and `flags.template_functions.flag_disabled` for Jinja2 templates were removed. Jinja2 integration now requires using the `flags.jinja2tags.flags` Jinja2 extension.
  Fix: If using Jinja2, remove old `flags.template_functions` and use `flags.jinja2tags.flags` as a Jinja2 extension.
• breaking Django-Flags 5.0 removed support for defining settings-based flag conditions using a single dictionary. Conditions for a flag must now always be a list of dictionaries or tuples, even for a single condition.
  Fix: Update `FLAGS` definitions in `settings.py` to use a list of dictionaries/tuples for conditions, e.g., `{'MY_FLAG': [{'condition': 'boolean', 'value': True}]}` instead of `{'MY_FLAG': {'condition': 'boolean', 'value': True}}`.
• gotcha Without `django.template.context_processors.request` in your `TEMPLATES` options, the `request` object will not be available in templates or for certain conditions (like `user` or `parameter`) when checking flags, leading to unexpected behavior or errors.
  Fix: Ensure `django.template.context_processors.request` is listed in your `TEMPLATES` `context_processors` setting.
• gotcha When using `flagged_path` or `FlaggedViewMixin` without providing a `fallback` view, accessing the URL when the flag condition is not met will result in a 404 Not Found error instead of a graceful redirect or alternative content.
  Fix: Provide a `fallback` view argument to `flagged_path` or set the `fallback` attribute in `FlaggedViewMixin` to specify a view to render when the flag condition is not met.

Install

• pip install django-flags Install stable version

Imports

• flag_enabled

  from flags.state import flag_enabled

  Used to check the state of a flag in Python code (e.g., in views or management commands).
• feature_flags (template tag)

  {% load feature_flags %}

  Required to use flag checking in Django templates via `{% flag_enabled 'MY_FLAG' as my_flag %}`.
• flagged_path

  from flags.urls import flagged_path

  Used in `urlpatterns` to conditionally include URL patterns based on a flag's state.
• flag_required

  from flags.decorators import flag_required

  Decorator to protect an entire view based on a feature flag's state.
• conditions (module)

  from flags import conditions

  Used for registering custom flag conditions.
• FlaggedViewMixin, FlaggedTemplateView

  from flags.views import FlaggedViewMixin, FlaggedTemplateView

  Mixins and views for integrating flags into class-based views.

Quickstart

To get started, add 'flags' to your `INSTALLED_APPS` and ensure `django.template.context_processors.request` is in your `TEMPLATES` context processors for request-aware conditions. Define your flags and their conditions in `settings.py` within the `FLAGS` dictionary. Then, use `flag_enabled` in your Python code, `{% load feature_flags %}` in templates, or `flagged_path` in `urls.py` to gate functionality. Finally, run `python manage.py migrate`.

import os

# settings.py
INSTALLED_APPS = [
    # ...
    'flags',
    # ...
]

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'OPTIONS': {
            'context_processors': [
                # ...
                'django.template.context_processors.request',
                # ...
            ],
        },
    },
]

FLAGS = {
    'MY_NEW_FEATURE': [
        {'condition': 'boolean', 'value': os.environ.get('ENABLE_MY_NEW_FEATURE', 'False').lower() == 'true'}
    ],
    'BETA_ACCESS': [
        {'condition': 'user', 'value': 'admin'},
        {'condition': 'parameter', 'value': 'beta', 'required': False} # Can be overridden by URL param `?beta=true`
    ]
}

# views.py
from django.http import HttpResponse
from flags.state import flag_enabled

def my_feature_view(request):
    if flag_enabled('MY_NEW_FEATURE', request=request):
        return HttpResponse("Welcome to the new feature!")
    return HttpResponse("Feature coming soon.")

# urls.py
from django.urls import path
from flags.urls import flagged_path
from . import views

urlpatterns = [
    path('home/', views.my_feature_view, name='home'),
    flagged_path('BETA_ACCESS', 'beta-page/', views.my_beta_view, name='beta_page')
]

# After adding to INSTALLED_APPS and settings, run migrations:
# python manage.py migrate