Integration extras

Every optional pip extra — pydantic, redis, starlette, fastapi, litestar, flask, sqlalchemy, django, drf, channels, agents, observability, cloudevents, celery, the brokers (redis streams, kafka, rabbitmq, nats, sqs) and testing — with its status, issue and the point at which a missing dependency is reported.

The core library has zero runtime dependencies, and that never changes. Everything that talks to a framework — Django models, FastAPI routers, SQLAlchemy types, Celery tasks, Kafka consumers, OpenTelemetry spans — lives in optional packages under xstate_statemachine.contrib, installed one pip extra at a time:

pip install "xstate-statemachine[fastapi]"
pip install "xstate-statemachine[django,sqlalchemy]"
pip install "xstate-statemachine[all]"

import xstate_statemachine still imports nothing third-party. Importing an integration without its extra fails loudly and helpfully:

from xstate_statemachine import MissingExtraError
from xstate_statemachine.contrib._compat import require_extra

try:
    require_extra("fastapi", "a_module_that_is_not_installed")
except MissingExtraError as exc:
    print(exc)
    # `a_module_that_is_not_installed` is not installed. Install the extra: pip install "xstate-statemachine[fastapi]"
    assert isinstance(exc, ImportError)  # existing `except ImportError` fallbacks keep working

When the error is raised. Importing an integration subpackage checks its pinned dependencies at import time (import xstate_statemachine.contrib.fastapi). Three things are checked later, on first use, because they are optional soft dependencies that no extra pins: StructlogPlugin() / LoguruPlugin() (structlog / loguru), SentryPlugin() (sentry-sdk), LangChainCallbackPlugin() (langchain-core — its module still needs langgraph at import, from [agents]), and [testing]’s Hypothesis helpers (model_test, events_strategy, payload_strategy). xstate_statemachine.contrib.brokers itself imports with no extra; each adapter module (brokers.kafka, …) checks its own. The Quart shim (contrib.quart) needs pip install quart on top of [flask] — the error says so.

The extras

The framework versions each shipped extra is tested against (oldest and newest, one CI cell each) are on the Compatibility page. All contrib APIs are provisional under the Deprecation Policy.

What every integration promises — and does not

Each integration page carries two boxes. They are not boilerplate; they are the contract.

Guarantees. What this does: the specific, testable behaviour (for example: “a transition and its audit row are written in one transaction”). What this does not do: the honest limits (for example: “at-least-once — pair with the idempotency inbox; never exactly-once”).

Threat model. Who can call this surface, what it exposes (state only, never raw context, unless you opt in), and what you must configure (an authorize= callable is required on every generated HTTP route).

The rules every integration follows are collected in the programme’s security & operability baseline.

Design rules (for contributors)

• A subpackage’s __init__.py starts with require_extra("<extra>", "<module>"). Core never imports contrib; CI proves it with an import-blocking guard.
• The single table of extras is xstate_statemachine.contrib._registry.EXTRAS; pyproject.toml, the CI matrix and the tests are checked against it.
• Every contrib module type-checks with its dependency absent (TYPE_CHECKING guards) and installed.
• Each extra has its own CI cell that installs only that extra, so an integration can never pass because another one happened to be present.