Installation

The Convert Python SDK is published to PyPI as convert-python-sdk and imports as convert_sdk. The two names differ by design — the hyphenated name is the PyPI discoverability surface; the snake_case name is the ergonomic import path.

Requirements

httpx is the SDK's only runtime dependency and is only used in sdk_key (remote-config) mode. There is no Django, Flask, FastAPI, pydantic, mmh3, or JavaScript runtime dependency in the core distribution. The SDK works in any standard Python process: WSGI/ASGI handlers, Lambda functions, Celery workers, CLI scripts.

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 to a compatible-release range

For reproducible builds, pin to a compatible-release range rather than an exact version:

# 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.

Verify the install

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

Expected output: 0.1.0 (or the installed version).

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

Import cheat-sheet

Everything in the table below is importable directly from the top-level convert_sdk package. These are the only exports the SDK guarantees as stable public API.

from convert_sdk import (
    # Entry points
    Core,
    Context,

    # Initialization config
    SDKConfig,
    TransportConfig,
    RefreshConfig,          # opt-in automatic config refresh (Phase 2)

    # Typed evaluation results
    ExperienceResult,
    FeatureResult,
    FeatureStatus,
    ConversionResult,
    ConversionStatus,
    CustomSegmentsResult,

    # Diagnostic surface
    DiagnosticReason,
    ExperienceDiagnostic,
    FeatureDiagnostic,
    GoalDiagnostic,
    EntityDiagnostic,

    # Lifecycle events
    LifecycleEvent,

    # Persistence boundary
    DataStore,              # Protocol — type-annotate your own adapter against this
    InMemoryDataStore,      # default adapter (used when SDKConfig.data_store is None)

    # Error hierarchy
    ConvertSDKError,
    ConfigError,
    InvalidConfigError,
    ConfigLoadError,
    TransportError,
    TrackingDeliveryError,

    # SDK version
    __version__,
)

Submodule imports for extension authors

These are stable for direct import by authors implementing custom adapters. They are not re-exported at the top level by design.

# Transport Protocol — implement this to swap in your own HTTP client
from convert_sdk.ports.transport import Transport

# EventBus Protocol and handler type — implement to substitute the event bus
from convert_sdk.ports.event_bus import EventBus, EventHandler

Minimum working import

For most applications, only a handful of names are needed:

from convert_sdk import Core, SDKConfig

Everything else can be imported on demand as your usage expands.

Replacing the default transport

If you cannot use httpx (corporate proxy, mTLS, custom retry policy), implement the Transport Protocol with your own HTTP client and inject it into Core:

from convert_sdk import Core, SDKConfig
from convert_sdk.ports.transport import Transport

class MyTransport:          # structural — no subclassing needed
    def fetch_config(self, config: SDKConfig) -> dict: ...
    def send_tracking(self, config: SDKConfig, payload: dict) -> None: ...
    def close(self) -> None: ...

core = Core(SDKConfig(sdk_key="..."), transport=MyTransport()).initialize()

The SDK has no hard dependency on httpx at evaluation time — httpx is only used by the bundled adapter. See Extending for the full protocol contract and injection patterns.

Next steps

• Quickstart — first variation in 5 minutes
• Initialization — sdk_key vs. direct config, RefreshConfig
• Configuration — full SDKConfig options reference
• Extending — custom transport, storage, and event-bus adapters