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,<1.0
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,
    Context,
    SDKConfig,
    TransportConfig,
    RefreshConfig,
    # result types
    ExperienceResult,
    FeatureResult,
    FeatureStatus,
    ConversionResult,
    ConversionStatus,
    CustomSegmentsResult,
    # diagnostic types
    DiagnosticReason,
    ExperienceDiagnostic,
    FeatureDiagnostic,
    GoalDiagnostic,
    EntityDiagnostic,
    # lifecycle events
    LifecycleEvent,
    # ports (Protocols)
    DataStore,
    # default adapters
    InMemoryDataStore,
    # errors
    ConvertSDKError,
    ConfigError,
    InvalidConfigError,
    ConfigLoadError,
    TransportError,
    TrackingDeliveryError,
)

Types that are not top-level exports but are stable for direct import:

# Lifecycle event payloads (distinct frozen dataclasses, not a single generic payload)
from convert_sdk.events import ConversionEventPayload, QueueReleasedPayload

# Tracking programmer-misuse errors (not top-level exports)
from convert_sdk.errors import TrackingError, ConversionDataError

# Transport and EventBus ports (not top-level exports)
from convert_sdk.ports.transport import Transport
from convert_sdk.ports.event_bus import EventBus, EventHandler

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 httpx-backed transport adapter. See Extending — Substituting the transport.

Next Steps

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