Quickstart

This guide will help you get started with the Replane Python SDK in minutes.

Prerequisites

  1. A Replane server running (self-hosted or cloud)

  2. An SDK key from your Replane dashboard

  3. Python 3.10+

Basic Usage

Synchronous Client

The sync client is the simplest way to get started:

from replane import Replane

# Using context manager (recommended)
with Replane(
    base_url="https://cloud.replane.dev",
    sdk_key="rp_...",
) as replane:
    # Get a simple config value
    rate_limit = replane.configs["rate_limit"]
    print(f"Rate limit: {rate_limit}")

    # Get with context for override evaluation
    user_client = replane.with_context({"user_id": "user-123", "plan": "premium"})
    feature_enabled = user_client.configs["new_feature"]
    print(f"Feature enabled: {feature_enabled}")

    # Get with fallback default
    timeout = replane.configs.get("request_timeout", 30)
    print(f"Timeout: {timeout}")

Asynchronous Client

For async applications (FastAPI, aiohttp, etc.), use the async client:

from replane import AsyncReplane

async def main():
    async with AsyncReplane(
        base_url="https://cloud.replane.dev",
        sdk_key="rp_...",
    ) as replane:
        # configs access is sync - it reads from local cache
        rate_limit = replane.configs["rate_limit"]

        # With context
        premium_client = replane.with_context({"plan": "premium"})
        enabled = premium_client.configs["feature"]

# Run with asyncio
import asyncio
asyncio.run(main())

Note

The async client requires the async extra: pip install replane[async]

Without Context Manager

If you prefer manual lifecycle management:

from replane import Replane

# Option 1: Provide credentials in constructor
replane = Replane(
    base_url="https://cloud.replane.dev",
    sdk_key="rp_...",
)
replane.connect()

# Option 2: Provide credentials in connect()
replane = Replane()
replane.connect(
    base_url="https://cloud.replane.dev",
    sdk_key="rp_...",
)

try:
    rate_limit = replane.configs["rate_limit"]
    user_client = replane.with_context({"user_id": "123"})
    feature = user_client.configs["feature_flag"]
finally:
    replane.close()

Understanding Config Values

Configs in Replane can be any JSON-serializable value:

# Boolean (feature flags)
dark_mode = replane.configs["dark_mode_enabled"]  # True/False

# Number (limits, thresholds)
max_items = replane.configs["max_items_per_page"]  # 50

# String
api_version = replane.configs["api_version"]  # "v2"

# Object
settings = replane.configs["app_settings"]  # {"theme": "dark", "lang": "en"}

# Array
allowed_origins = replane.configs["cors_origins"]  # ["localhost", "example.com"]

Using Context for Overrides

Context allows you to get different values based on runtime conditions:

# Create a scoped client for the user
user_client = replane.with_context({"plan": user.subscription_plan})

# Different rate limits per plan
rate_limit = user_client.configs["rate_limit"]
# Returns 100 for "free", 1000 for "pro", 10000 for "enterprise"

# Feature flags per user
beta_client = replane.with_context({
    "user_id": user.id,
    "is_beta_tester": user.is_beta,
})
show_beta = beta_client.configs["show_beta_features"]

Context is evaluated locally - your data never leaves your application.

Subscribing to Changes

React to config changes in real-time:

def on_config_change(name: str, config):
    print(f"Config '{name}' changed to: {config.value}")
    # Invalidate caches, update UI, etc.

# Subscribe to all changes
unsubscribe = replane.subscribe(on_config_change)

# Or subscribe to specific config
def on_rate_limit_change(config):
    update_rate_limiter(config.value)

unsubscribe_rate = replane.subscribe_config("rate_limit", on_rate_limit_change)

# Later, stop receiving updates
unsubscribe()
unsubscribe_rate()

Error Handling

Handle errors gracefully:

from replane import (
    Replane,
    TimeoutError,
    AuthenticationError,
    ReplaneError,
)

try:
    with Replane(
        base_url="https://cloud.replane.dev",
        sdk_key="rp_...",
    ) as replane:
        value = replane.configs["my_config"]
except KeyError as e:
    print(f"Config not found: {e}")
except TimeoutError as e:
    print(f"Connection timed out: {e.timeout_ms}ms")
except AuthenticationError:
    print("Invalid SDK key")
except ReplaneError as e:
    print(f"Error [{e.code}]: {e.message}")

Next Steps