This was originally published on rollgate.io/blog/feature-flags-python.
Why Feature Flags in Python?
Python powers everything from web applications and REST APIs to data pipelines and machine learning systems. Across all of these, you face the same challenge: how do you ship new features safely without risky deployments?
Feature flags solve this by decoupling deployment from release. You deploy code with the feature wrapped in a conditional, then control who sees it — without touching your codebase.
Here is where feature flags shine in Python projects:
- Web applications — Roll out new UI components or API endpoints to a subset of users in Django, FastAPI, or Flask.
- REST APIs — Version API behavior dynamically without maintaining separate endpoints.
- Data pipelines — Toggle new ETL logic or processing steps without redeploying Airflow DAGs.
- ML model rollouts — A/B test model versions in production, compare accuracy, and roll back instantly if metrics degrade.
If you have ever been burned by a production deploy that broke something for all users at once, feature flags are the safety net you need.
Quick Start: Feature Flags with the Rollgate Python SDK
The fastest way to add feature flags to any Python application is with the Rollgate Python SDK. Install it with pip:
pip install rollgate-python
Initialize the client and start evaluating flags:
from rollgate import RollgateClient
# Initialize once at application startup
client = RollgateClient(
sdk_key="your-sdk-key",
options={
"poll_interval": 30, # refresh flags every 30 seconds
}
)
# Evaluate a boolean flag
if client.is_enabled("new-dashboard", default=False):
show_new_dashboard()
else:
show_legacy_dashboard()
# Evaluate with user context for targeting
user_context = {
"key": "user-123",
"email": "alice@example.com",
"plan": "pro",
"country": "IT",
}
if client.is_enabled("beta-feature", context=user_context):
enable_beta(user_context["key"])
The client fetches flag configurations from Rollgate and caches them locally. Evaluations happen in-memory with no network calls, so they add virtually zero latency to your application.
You can get your SDK key by creating a free Rollgate account.
The Simple Approach: Environment Variables
Before reaching for a feature flag service, many teams start with environment variables:
import os
NEW_CHECKOUT = os.getenv("FF_NEW_CHECKOUT", "false").lower() == "true"
def process_order(order):
if NEW_CHECKOUT:
return new_checkout_flow(order)
return legacy_checkout_flow(order)
This works for simple on/off switches, but it hits limitations fast:
- Requires a redeploy to change a flag value.
- No gradual rollouts — it is all-or-nothing for every user.
- No user targeting — you cannot enable a feature for specific users or segments.
- No audit trail — who changed what and when?
- No instant rollback — reverting means changing the env var and redeploying.
Environment variables are fine for infrastructure configuration (DATABASE_URL, LOG_LEVEL). For feature releases, you need something more flexible.
Feature Flags in Django
Django applications benefit from feature flags at multiple layers: middleware, views, templates, and Django REST Framework serializers.
Middleware
Apply feature flags globally across all requests:
# myapp/middleware.py
from rollgate import RollgateClient
client = RollgateClient(sdk_key="your-sdk-key")
class FeatureFlagMiddleware:
def __init__(self, get_response):
self.get_response = get_response
def __call__(self, request):
context = {}
if request.user.is_authenticated:
context = {
"key": str(request.user.id),
"email": request.user.email,
"plan": getattr(request.user, "plan", "free"),
}
request.feature_flags = {
"new_nav": client.is_enabled("new-nav", context=context),
"dark_mode": client.is_enabled("dark-mode", context=context),
}
return self.get_response(request)
View Decorator
Create a reusable decorator for protecting views behind flags:
# myapp/decorators.py
from functools import wraps
from django.http import Http404
def feature_required(flag_name: str):
def decorator(view_func):
@wraps(view_func)
def wrapper(request, *args, **kwargs):
context = {"key": str(request.user.id)} if request.user.is_authenticated else {}
if not client.is_enabled(flag_name, context=context):
raise Http404
return view_func(request, *args, **kwargs)
return wrapper
return decorator
# Usage
@feature_required("new-analytics")
def analytics_view(request):
return render(request, "analytics/new.html")
Template Tags
Expose flags directly in Django templates:
# myapp/templatetags/feature_flags.py
from django import template
register = template.Library()
@register.simple_tag(takes_context=True)
def feature_enabled(context, flag_name: str) -> bool:
request = context.get("request")
if request and hasattr(request, "feature_flags"):
return request.feature_flags.get(flag_name, False)
return False
{% load feature_flags %}
{% feature_enabled "new-nav" as show_new_nav %}
{% if show_new_nav %}
{% include "nav/new_nav.html" %}
{% else %}
{% include "nav/legacy_nav.html" %}
{% endif %}
Django REST Framework
Use flags in DRF views and serializers to control API behavior:
# myapp/views.py
from rest_framework.views import APIView
from rest_framework.response import Response
class ProductListView(APIView):
def get(self, request):
context = {"key": str(request.user.id), "plan": request.user.plan}
if client.is_enabled("v2-product-response", context=context):
serializer = ProductV2Serializer(products, many=True)
else:
serializer = ProductV1Serializer(products, many=True)
return Response(serializer.data)
Feature Flags in FastAPI
FastAPI's dependency injection system makes feature flags clean and testable.
Dependency Injection Pattern
# app/dependencies.py
from fastapi import Depends, HTTPException, Request
from rollgate import RollgateClient
client = RollgateClient(sdk_key="your-sdk-key")
def get_flag_context(request: Request) -> dict:
user = request.state.user if hasattr(request.state, "user") else None
if user:
return {"key": user.id, "email": user.email, "plan": user.plan}
return {}
def require_feature(flag_name: str):
def dependency(context: dict = Depends(get_flag_context)):
if not client.is_enabled(flag_name, context=context):
raise HTTPException(status_code=404, detail="Not found")
return True
return dependency
# app/routes/search.py
from fastapi import APIRouter, Depends
from app.dependencies import require_feature, get_flag_context, client
router = APIRouter()
@router.get("/search")
async def search(
query: str,
context: dict = Depends(get_flag_context),
):
if client.is_enabled("ai-search", context=context):
results = await ai_powered_search(query)
else:
results = await keyword_search(query)
return {"results": results}
@router.get(
"/search/semantic",
dependencies=[Depends(require_feature("semantic-search"))],
)
async def semantic_search(query: str):
"""This entire endpoint is gated behind a feature flag."""
return {"results": await run_semantic_search(query)}
Middleware
# app/middleware.py
from starlette.middleware.base import BaseHTTPMiddleware
class FeatureFlagMiddleware(BaseHTTPMiddleware):
async def dispatch(self, request, call_next):
context = {}
if hasattr(request.state, "user"):
context = {"key": request.state.user.id}
request.state.flags = {
"maintenance_mode": client.is_enabled("maintenance-mode", context=context),
}
if request.state.flags.get("maintenance_mode"):
return JSONResponse(
status_code=503,
content={"message": "We are performing scheduled maintenance."},
)
return await call_next(request)
Feature Flags in Flask
Flask's simplicity pairs well with decorator-based feature flags.
Decorator Pattern
# app/flags.py
from functools import wraps
from flask import abort, g
from rollgate import RollgateClient
client = RollgateClient(sdk_key="your-sdk-key")
def feature_required(flag_name: str):
def decorator(f):
@wraps(f)
def wrapped(*args, **kwargs):
context = {"key": str(g.user.id)} if hasattr(g, "user") else {}
if not client.is_enabled(flag_name, context=context):
abort(404)
return f(*args, **kwargs)
return wrapped
return decorator
# Usage
@app.route("/experiments")
@feature_required("experiments-page")
def experiments():
return render_template("experiments.html")
before_request Hook
Evaluate flags once per request and make them available globally:
# app/__init__.py
from flask import Flask, g
app = Flask(__name__)
@app.before_request
def load_feature_flags():
context = {}
if hasattr(g, "user") and g.user:
context = {
"key": str(g.user.id),
"email": g.user.email,
}
g.flags = {
"new_pricing": client.is_enabled("new-pricing", context=context),
"export_csv": client.is_enabled("export-csv", context=context),
}
<!-- templates/pricing.html -->
{% if g.flags.new_pricing %}
{% include "pricing/new.html" %}
{% else %}
{% include "pricing/legacy.html" %}
{% endif %}
Gradual Rollouts
Instead of flipping a feature on for everyone, gradual rollouts let you increase exposure incrementally.
Percentage-Based Rollouts
Configure a rollout percentage in the Rollgate dashboard (for example, 10%), and the SDK handles consistent user assignment:
# The SDK uses consistent hashing on the user key.
# The same user always gets the same result for a given percentage.
context = {"key": f"user-{user_id}"}
if client.is_enabled("new-checkout", context=context):
# This user is in the rollout group
return new_checkout(cart)
else:
return legacy_checkout(cart)
A typical rollout schedule:
Day 1: 5% → internal team + early adopters
Day 3: 25% → monitor error rates and latency
Day 5: 50% → check support tickets
Day 7: 100% → full release
If error rates spike at any stage, set the rollout back to 0% instantly from the dashboard.
User Targeting with Attributes
Target specific users or segments by passing attributes in the context:
context = {
"key": str(user.id),
"email": user.email,
"plan": user.subscription.plan, # "free", "starter", "pro"
"country": user.profile.country, # "US", "IT", "DE"
"created_at": user.created_at.isoformat(),
}
# In the Rollgate dashboard, you can create rules like:
# - Enable for plan = "pro"
# - Enable for country IN ["US", "DE"]
# - Enable for 20% of free plan users
if client.is_enabled("advanced-analytics", context=context):
return full_analytics(user)
else:
return basic_analytics(user)
Feature Flags for ML Model Rollouts
Machine learning models in production need careful rollout strategies. A new model might have better accuracy on your test set but degrade on edge cases in production. Feature flags let you A/B test model versions safely.
A/B Test Model Versions
from rollgate import RollgateClient
client = RollgateClient(sdk_key="your-sdk-key")
def predict(user_id: str, input_data: dict) -> dict:
context = {"key": user_id}
if client.is_enabled("recommendation-model-v2", context=context):
model = load_model("recommendation_v2")
prediction = model.predict(input_data)
log_prediction(user_id, model="v2", prediction=prediction)
else:
model = load_model("recommendation_v1")
prediction = model.predict(input_data)
log_prediction(user_id, model="v1", prediction=prediction)
return prediction
Start the recommendation-model-v2 flag at 5%, monitor prediction quality metrics, and increase gradually.
Shadow Mode
Run both models simultaneously, serve the old one, and log the new one for comparison:
def predict_with_shadow(user_id: str, input_data: dict) -> dict:
context = {"key": user_id}
# Always run the current production model
v1_model = load_model("recommendation_v1")
v1_result = v1_model.predict(input_data)
# Shadow mode: run v2 in parallel, log results, but don't serve them
if client.is_enabled("shadow-model-v2", context=context):
v2_model = load_model("recommendation_v2")
v2_result = v2_model.predict(input_data)
log_shadow_comparison(
user_id=user_id,
v1=v1_result,
v2=v2_result,
match=v1_result == v2_result,
)
return v1_result # always serve v1 during shadow mode
Once shadow mode data confirms v2 performs well, switch to the A/B test approach to serve v2 to real users.
Testing with Feature Flags
Feature flags should not make your test suite unpredictable. Use fixtures and mocks to control flag state in tests.
Pytest Fixtures
# conftest.py
import pytest
from unittest.mock import MagicMock
@pytest.fixture
def mock_rollgate():
client = MagicMock()
client.is_enabled.return_value = False
return client
@pytest.fixture
def mock_rollgate_all_enabled():
client = MagicMock()
client.is_enabled.return_value = True
return client
Testing Both Code Paths
# test_checkout.py
from unittest.mock import patch
def test_legacy_checkout(mock_rollgate):
mock_rollgate.is_enabled.return_value = False
with patch("myapp.checkout.client", mock_rollgate):
result = process_checkout(cart)
assert result.flow == "legacy"
def test_new_checkout(mock_rollgate):
mock_rollgate.is_enabled.return_value = True
with patch("myapp.checkout.client", mock_rollgate):
result = process_checkout(cart)
assert result.flow == "new"
Flag-Specific Mocking
def test_partial_flags(mock_rollgate):
def side_effect(flag_name, **kwargs):
enabled_flags = {"new-checkout": True, "dark-mode": False}
return enabled_flags.get(flag_name, False)
mock_rollgate.is_enabled.side_effect = side_effect
with patch("myapp.views.client", mock_rollgate):
response = app_client.get("/checkout")
assert response.status_code == 200
Async Support
Modern Python applications often use asyncio. The Rollgate Python SDK supports async evaluation for non-blocking flag checks:
import asyncio
from rollgate import RollgateClient
client = RollgateClient(sdk_key="your-sdk-key")
async def handle_request(user_id: str):
context = {"key": user_id}
# Flag evaluation is local (cached), so it's fast even in sync mode.
# For async initialization and polling:
if client.is_enabled("async-feature", context=context):
result = await async_new_logic()
else:
result = await async_legacy_logic()
return result
Since flag evaluations happen against locally cached data, they are inherently fast. The async support is primarily useful for the initial flag fetch and background polling, ensuring they do not block your event loop.
# FastAPI example with async
from fastapi import FastAPI
app = FastAPI()
@app.on_event("startup")
async def startup():
# Initialize the client at startup
global client
client = RollgateClient(sdk_key="your-sdk-key")
@app.get("/api/recommendations")
async def recommendations(user_id: str):
context = {"key": user_id}
if client.is_enabled("ml-recommendations-v2", context=context):
return await get_ml_recommendations_v2(user_id)
return await get_ml_recommendations_v1(user_id)
Frequently Asked Questions
Do feature flags add latency to my Python app?
No. The Rollgate SDK fetches flag configurations on startup and polls for updates in the background. All flag evaluations happen locally in memory, adding microseconds of overhead — not milliseconds.
Can I use feature flags with Celery tasks?
Yes. Initialize the Rollgate client once in your Celery worker startup, and evaluate flags inside tasks just like you would in a view:
from celery import Celery
from rollgate import RollgateClient
app = Celery("tasks")
client = RollgateClient(sdk_key="your-sdk-key")
@app.task
def process_report(user_id: str):
context = {"key": user_id}
if client.is_enabled("new-report-format", context=context):
generate_new_report(user_id)
else:
generate_legacy_report(user_id)
How do I handle flags in database migrations?
Do not use feature flags in migrations. Migrations should be deterministic and repeatable. Instead, use flags in application code to control which schema or logic path is active.
What happens if the Rollgate service is unreachable?
The SDK caches the last known flag state locally. If it cannot reach Rollgate to poll for updates, it continues using cached values. You can also set default values that apply when a flag has never been fetched.
Can I use feature flags with Django's test client?
Yes. Mock the Rollgate client in your Django test setup, or use the middleware approach and override request.feature_flags directly in tests.
Start Using Feature Flags in Python
Feature flags transform how you ship Python applications. Whether you are building a Django web app, a FastAPI microservice, or a Flask API, the pattern is the same: wrap new code in a flag check, deploy safely, and control the rollout from your dashboard.
Ready to get started?
- Create a free Rollgate account
- Install the SDK:
pip install rollgate-python - Read the Python SDK documentation for the full API reference
No credit card required. Free tier includes 500K requests/month and unlimited flags.