Evaluate feature flags from Python using the Flaggr REST API or OFREP with the OpenFeature Python SDK

Python SDK

Evaluate Flaggr feature flags from Python applications using either the REST API directly or through the OpenFeature Python SDK with OFREP.

Installation

pip install flaggr

Or with your preferred package manager:

# Poetry
poetry add flaggr
 
# uv
uv add flaggr

Quick Start

from flaggr import FlaggrClient
 
client = FlaggrClient(
    api_url="https://flaggr.dev",
    api_key="flg_your_token",
    service_id="web-app",
    environment="production",
)
 
# Evaluate a boolean flag
is_enabled = client.get_boolean("checkout-v2", default=False, context={
    "targeting_key": "user-123",
    "plan": "enterprise",
})
 
if is_enabled:
    show_new_checkout()
else:
    show_old_checkout()

Client API

Initialization

from flaggr import FlaggrClient
 
client = FlaggrClient(
    api_url="https://flaggr.dev",    # Your Flaggr instance URL
    api_key="flg_your_token",         # API token (opaque or JWT)
    service_id="web-app",             # Service to evaluate against
    environment="production",          # Target environment
    timeout=5.0,                       # Request timeout in seconds (default: 5)
)

Boolean Evaluation

is_enabled = client.get_boolean("dark-mode", default=False)
 
# With evaluation context
is_enabled = client.get_boolean("checkout-v2", default=False, context={
    "targeting_key": "user-456",
    "plan": "enterprise",
    "country": "AU",
})

String Evaluation

theme = client.get_string("app-theme", default="light", context={
    "targeting_key": "user-456",
})
# Returns: "light", "dark", or "system"

Number Evaluation

max_retries = client.get_number("max-retries", default=3, context={
    "targeting_key": "user-456",
})

Object Evaluation

banner_config = client.get_object("promo-banner", default={
    "text": "",
    "color": "blue",
    "dismissible": True,
}, context={
    "targeting_key": "user-456",
})
 
print(banner_config["text"])

Full Resolution Details

For detailed evaluation information including reason, variant, and metadata:

details = client.resolve_boolean("checkout-v2", default=False, context={
    "targeting_key": "user-456",
})
 
print(f"Value: {details.value}")
print(f"Reason: {details.reason}")      # TARGETING_MATCH, DEFAULT, DISABLED, etc.
print(f"Variant: {details.variant}")
print(f"Error: {details.error_code}")

REST API Direct Usage

If you prefer to use the REST API directly without the SDK:

import requests
 
response = requests.post(
    "https://flaggr.dev/api/flags/evaluate",
    headers={
        "Authorization": "Bearer flg_your_token",
        "Content-Type": "application/json",
    },
    json={
        "flagKey": "checkout-v2",
        "serviceId": "web-app",
        "environment": "production",
        "defaultValue": False,
        "context": {
            "targetingKey": "user-123",
            "plan": "enterprise",
        },
    },
)
 
result = response.json()
print(f"Value: {result['value']}, Reason: {result['reason']}")

Async with httpx

import httpx
 
async def evaluate_flag():
    async with httpx.AsyncClient() as client:
        response = await client.post(
            "https://flaggr.dev/api/flags/evaluate",
            headers={
                "Authorization": "Bearer flg_your_token",
                "Content-Type": "application/json",
            },
            json={
                "flagKey": "checkout-v2",
                "serviceId": "web-app",
                "environment": "production",
                "defaultValue": False,
                "context": {"targetingKey": "user-123"},
            },
        )
        return response.json()

OpenFeature Integration (OFREP)

Use the OpenFeature Python SDK with Flaggr's OFREP (OpenFeature Remote Evaluation Protocol) endpoint for a vendor-neutral integration.

Installation

pip install openfeature-sdk openfeature-provider-ofrep

Setup

from openfeature import api
from openfeature.contrib.provider.ofrep import OFREPProvider
 
# Configure the OFREP provider
provider = OFREPProvider(
    base_url="https://flaggr.dev/api/ofrep",
    headers={
        "Authorization": "Bearer flg_your_token",
        "X-Service-Id": "web-app",
        "X-Environment": "production",
    },
)
 
# Register the provider
api.set_provider(provider)
 
# Get a client
client = api.get_client()

Evaluate Flags

from openfeature.evaluation_context import EvaluationContext
 
ctx = EvaluationContext(
    targeting_key="user-123",
    attributes={
        "plan": "enterprise",
        "country": "AU",
    },
)
 
# Boolean
is_enabled = client.get_boolean_value("checkout-v2", default_value=False, evaluation_context=ctx)
 
# String
theme = client.get_string_value("app-theme", default_value="light", evaluation_context=ctx)
 
# Number
max_retries = client.get_integer_value("max-retries", default_value=3, evaluation_context=ctx)
 
# Object
config = client.get_object_value("banner-config", default_value={}, evaluation_context=ctx)

Full Details

details = client.get_boolean_details("checkout-v2", default_value=False, evaluation_context=ctx)
 
print(f"Value: {details.value}")
print(f"Reason: {details.reason}")
print(f"Variant: {details.variant}")
print(f"Error code: {details.error_code}")
print(f"Error message: {details.error_message}")

Evaluation Context

The evaluation context provides attributes about the current user or request that targeting rules evaluate against.

Field	Type	Description
`targeting_key`	string	Primary identifier (usually user ID)
`plan`	string	User's plan or tier
`country`	string	User's country code
`email`	string	User's email
`device`	string	Device type (mobile, desktop, tablet)
any custom field	string/number/boolean	Custom attributes for your targeting rules

context = {
    "targeting_key": "user-123",
    "plan": "enterprise",
    "country": "AU",
    "beta_tester": True,
    "signup_date": "2025-01-15",
}

Error Handling

from flaggr import FlaggrClient, FlaggrError, FlaggrTimeoutError
 
client = FlaggrClient(
    api_url="https://flaggr.dev",
    api_key="flg_your_token",
    service_id="web-app",
    timeout=5.0,
)
 
try:
    is_enabled = client.get_boolean("checkout-v2", default=False)
except FlaggrTimeoutError:
    # Request timed out — use default value
    is_enabled = False
except FlaggrError as e:
    # API error — log and use default value
    print(f"Flag evaluation failed: {e}")
    is_enabled = False

Info

All evaluation methods return the default value if the flag is not found, disabled, or if an error occurs. Exceptions are only raised for network-level failures.

Framework Integration

Django

# settings.py
FLAGGR_CLIENT = FlaggrClient(
    api_url="https://flaggr.dev",
    api_key=os.environ["FLAGGR_API_KEY"],
    service_id="django-app",
    environment=os.environ.get("FLAGGR_ENV", "development"),
)
 
# views.py
from django.conf import settings
 
def checkout_view(request):
    client = settings.FLAGGR_CLIENT
    use_v2 = client.get_boolean("checkout-v2", default=False, context={
        "targeting_key": str(request.user.id),
        "plan": request.user.profile.plan,
    })
 
    if use_v2:
        return render(request, "checkout_v2.html")
    return render(request, "checkout.html")

FastAPI

from fastapi import FastAPI, Depends
from flaggr import FlaggrClient
 
app = FastAPI()
flaggr = FlaggrClient(
    api_url="https://flaggr.dev",
    api_key=os.environ["FLAGGR_API_KEY"],
    service_id="api",
    environment="production",
)
 
@app.get("/checkout")
async def checkout(user_id: str):
    use_v2 = flaggr.get_boolean("checkout-v2", default=False, context={
        "targeting_key": user_id,
    })
    return {"version": "v2" if use_v2 else "v1"}