Quickstart

Python SDK — Quickstart

A copy-paste-ready guide to get the Convert Python SDK running in under 5 minutes.

1. Install

pip install convert-python-sdk

Or with uv:

uv add convert-python-sdk

The install includes httpx as the default HTTP client — no extra install is needed. Python 3.9 or newer is required. To swap the default transport, see Extending.

2. Full Working Example

import os

from convert_sdk import (
    Core,
    SDKConfig,
    TransportConfig,
    FeatureStatus,
)

# 1. Initialize the SDK (sync, blocking)
core = Core(
    SDKConfig(
        sdk_key=os.environ["CONVERT_SDK_KEY"],
        environment="production",
        transport=TransportConfig(
            config_endpoint="https://cdn-4.convertexperiments.com/api/v1",
        ),
    )
)

# 2. Verify the SDK is ready
assert core.is_ready, "SDK failed to initialize"

# 3. Create a visitor context
context = core.create_context(
    "visitor-123",
    {"country": "US", "plan": "premium"},
)

# 4. Run an experience
result = context.run_experience(
    "homepage-redesign",
    location_attributes={"path": "/"},
)

if result is not None:
    print(f"Experience: {result.experience_key}")
    print(f"Variation:  {result.variation_key}")

# 5. Resolve a feature flag
feature = context.run_feature("dark-mode")

if feature is not None and feature.status == FeatureStatus.ENABLED:
    theme = feature.variables.get("theme", "dark")
    print(f"Dark mode theme: {theme}")

# 6. Track a conversion with revenue
context.track_conversion(
    "purchase-completed",
    conversion_data={
        "revenue": 49.99,
        "transaction_id": "txn-abc-123",
    },
)

# 7. Flush queued tracking events before the process exits or the request ends
flush = context.release_queues(reason="end_of_request")
print(f"Delivered {flush.delivered_event_count} events")

Key Points

• Synchronous: The Python SDK is fully synchronous. There is no on_ready() coroutine. Core(SDKConfig(...)) blocks while the config is fetched and returns when the SDK is ready.
• is_ready: Read core.is_ready after construction; it is True once the snapshot is loaded. A failed config fetch raises ConfigLoadError from __init__, so reaching core.is_ready already implies success.
• No auto-flush: Tracking events are queued in-process. Call context.release_queues() explicitly at end-of-request, before exit, or in a finally block. See Code Examples — Queue Control.
• Config refresh is opt-in: Long-running services that want background config refresh must pass SDKConfig(refresh=RefreshConfig(...)). See Initialization § automatic config refresh.
• None is a normal outcome: run_experience() and run_feature() return None when the visitor doesn't qualify — no exception is raised.

Direct config (no network)

For tests, CI, or local development, pass an inline config dict:

core = Core(SDKConfig(config_data={
    "account_id": "1001",
    "project": {"id": "2002", "name": "Demo"},
    "experiences": [],
    "features": [],
    "goals": [],
}))

Next Steps

• Installation — Python version, optional dependencies, virtualenv setup
• Initialization — SDK Key vs. direct config, RefreshConfig
• Configuration — Full config options reference
• Code Examples — All SDK methods with examples
• Type Hints — Dataclasses, Protocols, and enums reference