Python SDK

The FlagBox Python SDK provides a simple and powerful way to integrate feature flags into your Python applications. Control your application's features in real-time with a clean and intuitive API.

Installation

pip install flagboxsdk

Quick Start

from flagbox import FlagBoxClient

# Initialize the client
flagbox = FlagBoxClient(
    api_url="https://api.flagbox.io",
    api_key="your-api-key"
)

# Get a feature flag value
value = flagbox.get_flag("my-feature", "default-value")
print(f"Feature value: {value}")
          

Configuration

The FlagBox client can be configured with the following options:

• api_url (required): The base URL for the FlagBox API
• api_key (required): Your FlagBox API key
• global_context (optional): A dictionary of key-value pairs that will be used for all flag evaluations

Using Context

FlagBox supports two types of context: global context and per-flag context. Context values are used to evaluate flag rules and can include information like user ID, tenant ID, or any other attributes relevant to your feature flags.

Global Context

Global context is set when initializing the client and applies to all flag evaluations. This is useful for setting context that doesn't change frequently, like application version or deployment region.

# Initialize with global context
flagbox = FlagBoxClient(
    api_url="https://api.flagbox.io",
    api_key="your-api-key",
    global_context={
        "region": "us-west",
        "app_version": "1.0.0",
        "tenant_id": "acme-corp"
    }
)

Per-Flag Context

Per-flag context can be provided for individual flag evaluations. This is useful for dynamic values like user ID or request-specific attributes. Per-flag context is merged with global context, with per-flag values taking precedence.

# Get flag with per-flag context
value = flagbox.get_flag(
    "my-feature",
    "default-value",
    context={
        "user_id": "123",
        "user_role": "admin"
    }
)

# Async version
value = await flagbox.get_flag_async(
    "my-feature",
    "default-value",
    context={
        "user_id": "123",
        "user_role": "admin"
    }
)
          

API Reference

get_flag

Synchronously get a feature flag value. Returns the flag's value if available, or the default value if not.

# Get string value
value = flagbox.get_flag("my-feature", "default-value")

# Get number value
value = flagbox.get_flag("my-feature", 42)

# Get dictionary value
value = flagbox.get_flag("my-feature", {"enabled": False})
          

get_flag_async

Asynchronously get a feature flag value. Returns the flag's value if available, or the default value if not.

import asyncio

async def main():
    # Get string value
    value = await flagbox.get_flag_async("my-feature", "default-value")
    print(f"Feature value: {value}")

asyncio.run(main())
          

Error Handling

The SDK handles errors gracefully by returning the default value when:

• The API request fails
• The API returns a non-200 status code
• Network errors occur

All errors are logged to the console for debugging purposes.

Best Practices

• Initialize the FlagBox client once and reuse it throughout your application
• Use meaningful flag keys that describe the feature's purpose
• Always provide a default value when using get_flag()
• Use get_flag_async() when working with asyncio-based applications

Framework Integration

The SDK can be easily integrated with popular Python web frameworks:

# Flask integration
from flask import Flask, request
from flagbox import FlagBoxClient

app = Flask(__name__)
flagbox = FlagBoxClient(
    api_url="https://api.flagbox.io",
    api_key="your-api-key"
)

@app.route("/feature")
def feature():
    value = flagbox.get_flag("my-feature", "default-value")
    return {"value": value}

# FastAPI integration
from fastapi import FastAPI
from flagbox import FlagBoxClient

app = FastAPI()
flagbox = FlagBoxClient(
    api_url="https://api.flagbox.io",
    api_key="your-api-key"
)

@app.get("/feature")
async def feature():
    value = await flagbox.get_flag_async("my-feature", "default-value")
    return {"value": value}