Installation

Installation

The Convert Python SDK is published to PyPI as convert-python-sdk and imports as convert_sdk.

Requirements

Requirement	Version
Python	>=3.9
httpx (default transport)	>=0.28,<0.29
Operating system	Any platform CPython runs on (Linux, macOS, Windows)

The SDK has no Django, Flask, FastAPI, or JavaScript runtime dependency in its core distribution — it works in any standard Python process (script, WSGI/ASGI request handler, Lambda, Celery worker, CLI).

Install with pip

pip install convert-python-sdk

Install with uv

uv add convert-python-sdk

Install with Poetry

poetry add convert-python-sdk

Pinning the version

For reproducible builds, pin to a compatible-release range in your dependency file:

# pyproject.toml
[project]
dependencies = [
    "convert-python-sdk>=0.1,<0.2",
]

The SDK follows Semantic Versioning — 0.x releases may contain breaking changes between minor versions; 1.x and beyond hold backwards-compatibility within each major.

Importing

The public API is exposed at the top-level convert_sdk package:

from convert_sdk import (
    Core,
    SDKConfig,
    TrackingConfig,
    TransportConfig,
    Context,
    # result types
    ExperienceResult,
    FeatureResult,
    FeatureStatus,
    ConversionResult,
    ConversionEvent,
    TrackingFlushResult,
    # diagnostic types
    ExperienceDiagnostic,
    FeatureDiagnostic,
    GoalDiagnostic,
    EntityDiagnostic,
    # lifecycle events
    LifecycleEvent,
    LifecycleEventPayload,
    # ports (Protocols)
    Transport,
    DataStore,
    EventBus,
    # default adapters
    InMemoryDataStore,
    # errors
    ConvertSDKError,
    InitializationError,
    ConfigValidationError,
    ConfigLoadError,
    TrackingError,
    GoalNotFoundError,
    ConversionDataError,
    TrackingDeliveryError,
)

RefreshConfig lives at convert_sdk.config.RefreshConfig and RefresherStatus at convert_sdk.RefresherStatus. See Type Hints for the full type reference.

Verifying the install

python -c "import convert_sdk; print(convert_sdk.__version__)"

Or run the smoke-test example from the python-sdk repository:

python examples/direct_config.py

Optional: pre-release versions

Pre-release builds (alpha, beta, rc) are tagged on PyPI. To install the latest pre-release:

pip install --pre convert-python-sdk

Replacing the default transport

If you cannot use httpx (corporate proxy, mTLS, async runtime), implement the Transport Protocol with your own client and pass it to Core. The SDK has no hard dependency on httpx at evaluation time — the dependency is only used by the bundled HttpxTransport adapter. See Extending — Substituting the transport.

Next Steps

• Quickstart — first experiment in 5 minutes
• Initialization — SDK key vs. direct config
• Configuration — full options reference