Home

Convert Python SDK

The Convert Python SDK allows developers to integrate A/B testing, feature flags, and personalization into their Python applications. It manages different user experiences and features based on visitor data and defined rules, while tracking visitor interactions and conversions.

Source Repository: python-sdk

flowchart TD
    A0["Core (ConvertSDK entry point)"]
    A1["Context"]
    A2["DataStore (visitor + dedup state)"]
    A3["evaluation.rules"]
    A4["evaluation.bucketing"]
    A5["Transport (config + tracking I/O)"]
    A6["evaluation.experiences"]
    A7["evaluation.features"]
    A8["TrackingQueue"]
    A9["EventBus / LifecycleEvent"]
    A10["ConfigSnapshot / SDKConfig"]
    A11["ConfigRefresher (opt-in daemon)"]
    A0 -- "Creates" --> A1
    A0 -- "Fetches config via" --> A5
    A0 -- "Owns" --> A8
    A0 -- "Fires events via" --> A9
    A0 -- "Spawns (opt-in)" --> A11
    A11 -- "Refreshes via" --> A5
    A11 -- "Swaps" --> A10
    A1 -- "Runs experiments via" --> A6
    A1 -- "Runs features via" --> A7
    A1 -- "Reads/writes via" --> A2
    A1 -- "Releases via" --> A8
    A6 -- "Buckets via" --> A4
    A6 -- "Matches rules via" --> A3
    A7 -- "Buckets via" --> A4
    A7 -- "Matches rules via" --> A3
    A8 -- "Delivers via" --> A5
    A8 -- "Fires events via" --> A9
    A0 -- "Holds" --> A10

Loading

Key Differences from the JavaScript SDK

The Python SDK shares the same architecture and bucketing algorithm as the JavaScript SDK and PHP SDK, ensuring cross-SDK deterministic variation assignment. However, it is adapted for Python's idioms and the dominant Python backend shape (Django/Flask/FastAPI request handlers, scripts, batch jobs):

• Synchronous execution — No Promises or async/await. Core(SDKConfig(...)) blocks until the SDK is ready and returns. An AsyncCore surface is planned for Phase 3 (see Async and Framework Integrations).
• Typed dataclasses — ExperienceResult, FeatureResult, and every *Diagnostic are frozen dataclasses with field-level type hints. Errors carry structured .code and .context.
• SDKConfig instead of dicts — initialization options are a typed dataclass (SDKConfig, TransportConfig, TrackingConfig, RefreshConfig).
• Protocol-based extension — Transport, DataStore, and EventBus use structural typing (PEP 544). No subclassing needed.
• Opt-in background refresh — Long-running services pass SDKConfig(refresh=RefreshConfig(...)). By default no daemon thread runs.
• Sync conversion queue — release_queues() is synchronous. Call it at end-of-request, in a finally block, or via middleware. There is no auto-flush on a timer.

Getting Started

• How Convert Works
• Architecture Overview
• Data Model Reference
• Quickstart Overview
• Requirements & Constraints

Python SDK

• Quickstart
• Installation
• Initialization
• Configuration Options
• Code Examples
• Type Hints
• Diagnostics & Support
• Extending
• Testing
• Async and Framework Integrations

Migration Guides

• Migrating from the JavaScript SDK
• Migrating from Raw REST

Core Concepts

• Experiences & Variations
• Feature Flags
• Bucketing Algorithm
• Rule Evaluation & Targeting
• Segments
• Data Management
• Event System
• API Communication & Tracking

How-To Guides

• Running Experiences
• Running Features
• Tracking Conversions
• Visitor Context & Properties
• Persistent DataStore
• Troubleshooting

Edge & Integrations

• LLM / AI Testing (llms.txt)

Maintainers

• Roadmap
• Release Process