TypeHints

Type Hints

Reference for the dataclasses, Protocols, and enums the Python SDK exposes. All symbols listed here are importable from convert_sdk unless noted.

This page is the Python analogue of the JavaScript SDK's ConfigTypes and the PHP SDK's ReturnTypes — same role, different idioms.

Public surface (top-level imports)

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

RefreshConfig lives at convert_sdk.config.RefreshConfig. ContextState and ConfigSnapshot live under convert_sdk.domain.* — they are stable internal types for DataStore implementations and support tooling.

Result dataclasses

All result types are frozen dataclasses (@dataclass(frozen=True)) — fields cannot be reassigned after construction.

ExperienceResult

Returned by Context.run_experience() (or as elements of Context.run_experiences()).

Field	Type	Description
experience_id	str	Internal config id
experience_key	str	Human-readable key from the dashboard
experience_name	str | None	Display name
variation_id	str	Internal variation id
variation_key	str	Human-readable variation key
variation_name	str | None	Display name
bucket_value	int	The 0–9999 bucket value that selected this variation

FeatureResult

Returned by Context.run_feature() (or elements of Context.run_features()).

Field	Type	Description
feature_id	str	Internal config id
feature_key	str	Human-readable key
feature_name	str | None	Display name
status	FeatureStatus	ENABLED or DISABLED
variables	Mapping[str, Any]	Type-cast feature variables
experience_id	str | None	Backing experience id, if any
experience_key	str | None	Backing experience key
variation_key	str | None	Backing variation key

FeatureStatus (enum)

from convert_sdk import FeatureStatus

FeatureStatus.ENABLED   # value: "enabled"
FeatureStatus.DISABLED  # value: "disabled"

Compare against the enum members for type safety:

if feature.status == FeatureStatus.ENABLED:
    ...

ConversionResult

Returned by Context.track_conversion().

Field	Type	Description
events	tuple[ConversionEvent, ...]	Typed events queued for delivery
duplicate_prevented	bool	True when deduplication suppressed the event
queued_event_count	int	Number of events added to the queue
event	ConversionEvent | None (property)	The most-useful single event

ConversionEvent

Element of ConversionResult.events and the underlying queue-payload row.

Field	Type	Description
visitor_id	str	Visitor identifier
goal_id	str	Internal config id of the goal
goal_key	str	Human-readable goal key
goal_name	str | None	Display name
account_id	str | None	Sourced from the config snapshot
project_id	str | None	Sourced from the config snapshot
conversion_data	Mapping[str, Any]	Revenue / metadata payload
bucketing_data	Mapping[str, str]	{experience_id: variation_id} attribution
event_type	str	"conversion"

TrackingFlushResult

Returned by Context.release_queues().

Field	Type	Description
attempted	bool	False if the queue was empty, no POST was made
delivered_event_count	int	Total events delivered
delivered_batch_count	int	Number of HTTP POST requests made
remaining_event_count	int	Events still in queue (non-zero on partial failure)
reason	str | None	The string passed to release_queues()

Diagnostic dataclasses

Returned by Context.diagnose_*() methods. They never raise; they describe the outcome and the reason.

ExperienceDiagnostic

Field	Type	Description
experience_key	str	The key requested
resolved	bool	Whether the visitor was bucketed
reason	str	Machine-readable reason code
message	str	Human-readable description
result	ExperienceResult | None	Populated when resolved=True
details	Mapping[str, Any]	bucket_value, audience_key, etc.

Reason codes are listed in Diagnostics § experience reason codes.

FeatureDiagnostic

Same shape as ExperienceDiagnostic, with feature_key instead of experience_key. The details map additionally exposes experience_key and variation_key of the backing experience when bucketing succeeded.

GoalDiagnostic

Field	Type	Description
goal_key	str	The key requested
resolved	bool	Whether the goal exists in the snapshot
reason	str	"resolved" or "goal_not_found"
message	str	Human-readable description
details	Mapping[str, Any]	entity_key, available_goal_count

EntityDiagnostic

Returned by Context.diagnose_config_entity() and Context.diagnose_config_entity_by_id().

Field	Type	Description
entity_type	str	e.g. "experience", "feature"
lookup	str	"key" or "id"
value	str	The key or id that was looked up
resolved	bool	Whether the entity was found
reason	str	"resolved" or "entity_not_found"
message	str	Human-readable description
details	Mapping[str, Any]	entity_type, lookup, value

Lifecycle event types

LifecycleEvent (enum)

from convert_sdk import LifecycleEvent

LifecycleEvent.TRACKING_EVENT_QUEUED        # value: "tracking_event_queued"
LifecycleEvent.QUEUE_RELEASE_STARTED        # value: "queue_release_started"
LifecycleEvent.QUEUE_RELEASED               # value: "queue_released"
LifecycleEvent.TRACKING_DELIVERY_FAILED     # value: "tracking_delivery_failed"
LifecycleEvent.CONVERSION_CREATED           # value: "conversion_created"
LifecycleEvent.CONVERSION_DEDUPLICATED      # value: "conversion_deduplicated"
LifecycleEvent.CONFIG_UPDATED               # value: "config_updated"

LifecycleEventPayload

Frozen dataclass passed to every event handler.

Field	Type	Description
event	LifecycleEvent	The event enum value
details	Mapping[str, Any]	Privacy-safe event-specific details
occurred_at	datetime	UTC timestamp

Details are always privacy-safe: visitor ids are replaced with a 16-character SHA-256 prefix (visitor_ref), and sensitive keys are redacted.

Extension Protocols

The SDK uses structural typing (Protocol) for extension points — implementing the methods is enough; no inheritance is required.

Transport

from convert_sdk.ports.transport import (
    Transport,
    ConfigRequest,
    TrackingRequest,
)

class MyTransport:
    def fetch_config(self, request: ConfigRequest) -> Mapping[str, Any]: ...
    def send_tracking(self, request: TrackingRequest) -> Mapping[str, Any]: ...

See Extending — Substituting the transport.

DataStore

from convert_sdk import DataStore
from convert_sdk.domain.context_state import ContextState

class MyDataStore:
    def load_context_state(self, visitor_id: str) -> ContextState | None: ...
    def save_context_state(self, state: ContextState) -> None: ...
    def has_tracked_goal(self, visitor_id: str, goal_id: str) -> bool: ...
    def mark_tracked_goal(self, visitor_id: str, goal_id: str) -> None: ...

The bundled InMemoryDataStore implementation is exported from convert_sdk.InMemoryDataStore.

EventBus

from convert_sdk import EventBus, LifecycleEvent, LifecycleEventPayload

EventHandler = Callable[[LifecycleEventPayload], None]

class MyEventBus:
    def subscribe(self, event: LifecycleEvent, handler: EventHandler) -> None: ...
    def unsubscribe(self, event: LifecycleEvent, handler: EventHandler) -> None: ...
    def emit(self, payload: LifecycleEventPayload) -> None: ...

Error hierarchy

ConvertSDKError                            (base)
├── InitializationError
│   ├── ConfigValidationError              (code: "config.validation_error")
│   └── ConfigLoadError                    (code: "config.load_error")
└── TrackingError
    ├── GoalNotFoundError                  (code: "goal.not_found")
    ├── ConversionDataError                (code: "conversion.data_error")
    └── TrackingDeliveryError              (code: "tracking.delivery_error")

Every error carries:

Attribute	Type	Description
code	str | None	Machine-readable error code
context	Mapping[str, Any]	Structured metadata, immutable

from convert_sdk import GoalNotFoundError

try:
    context.track_conversion("unknown-goal")
except GoalNotFoundError as exc:
    handle(exc.code, dict(exc.context))

Refresher introspection

RefresherStatus

Returned by core.refresher_status (frozen dataclass).

Field	Type	Description
enabled	bool	False when SDKConfig.refresh is None
is_running	bool	False after stop, fork, terminal failure, or worker crash
consecutive_failures	int	0 on success/skip; resets on success
last_refresh_at	float | None	POSIX time of the last attempt
last_success_at	float | None	POSIX time of the last refresh that produced or matched a snapshot
last_error_type	str | None	Exception class name of the last failure
last_error_at	float | None	POSIX time of the last failure
forked_in_child	bool	True after the SDK detects an os.fork() in this process
terminal_failure	bool	True after a terminal-failure shutdown

Internal types you'll occasionally need

These are not in the top-level export but are stable enough to import directly:

ContextState (frozen dataclass)

convert_sdk.domain.context_state.ContextState — used by custom DataStore implementations.

Field	Type	Description
visitor_id	str	Visitor identifier
visitor_attributes	Mapping[str, Any]	Frozen mapping of attributes
visitor_properties	Mapping[str, Any]	Frozen mapping of properties
default_segments	tuple[str, ...]	Frozen tuple of segment keys

Use ContextState.create(...) to construct from external storage; the bare constructor does not enforce frozen-mapping invariants.

ConfigSnapshot

convert_sdk.domain.config_snapshot.ConfigSnapshot — returned by core.snapshot. Not re-exported because most callers should treat the snapshot as opaque, but indexed accessors are stable for support tooling:

Field	Type	Description
experiences_by_key	Mapping[str, …]	Lookup by experience key
features_by_key	Mapping[str, …]	Lookup by feature key
goals_by_key	Mapping[str, …]	Lookup by goal key
account_id	str | None	From the project payload
project_id	str | None	From the project payload

What to read next

• Configuration — SDKConfig / TransportConfig / TrackingConfig field reference
• Code Examples — practical use of each type
• Diagnostics — reason codes and the diagnose_* workflow
• Extending — Protocol-based extension points