Compatibility & Dependencies

The golden rule

Every extension package depends only on quadkit and quadkit-contracts. No extension ever depends on another extension.

This rule keeps the dependency graph acyclic and ensures packages can be adopted independently. The core (quadkit) provides the DI container, Application, configuration, and logging. quadkit-contracts defines the protocols extensions implement.

An import linter enforces this. A cross-extension import that type-checks will still fail CI.

Documented exceptions

Tooling may list other QuadKit distributions in pyproject.toml. Application extensions still must not import each other.

Package	May depend on	Why
`quadkit-cli`	`quadkit`, `quadkit-contracts`	Scaffolds and runs projects; never imports your app’s code
`quadkit-testing`	any extension (optional extras)	Test harnesses, fakes, and compliance suites

Verified against the published pyproject.toml files:

quadkit-web depends on quadkit, quadkit-contracts, Starlette, Jinja2, aiofiles, and markupsafe — plus orjson and typing-extensions. It has no dependency on any other QuadKit extension.
quadkit-testing declares quadkit and quadkit-contracts as its only hard requirements. auth, cache, db, storage, web, and integration are extras, so the optional integrations are opt-in.
quadkit-cli depends on quadkit and quadkit-contracts alongside Click/Typer, Rich, watchfiles, and YAML tooling.

Adding a new cross-extension hard dependency requires a design review. Prefer a protocol in quadkit-contracts.

Python & runtime

Python version: 3.11+ required
Run the app: quadkit run / quadkit dev (auto-picks granian → uvicorn → hypercorn)
ASGI servers: uvicorn, granian, and hypercorn are all valid when you already operate one — see Deployment
Package manager: uv (recommended), pip, poetry

The published line is 0.0.42 (alpha 0.0.x). Pin the range:

uv add "quadkit>=0.0.42,<0.1"
uv add "quadkit-cli>=0.0.42,<0.1"

Optional extras

Install backend-specific and server-specific dependencies via extras:

Package	Extras
`quadkit`	`[codegen]`, `[dev]`, `[docs]`, `[security]`, `[test]`
`quadkit-contracts`	`[dev]`, `[test]`
`quadkit-web`	`[granian]`, `[uvicorn]`, `[hypercorn]`, `[websocket]`, `[templates]`, `[uploads]`, `[client]`, `[security]`, `[all]`
`quadkit-testing`	`[web]`, `[db]`, `[cache]`, `[auth]`, `[storage]`, `[integration]`, `[all]`
`quadkit-cli`	`[all]`, `[dev]`, `[test]`

uv add "quadkit-web[granian,websocket]"
uv add --dev "quadkit-testing[web,db]"

quadkit-testing[all] pulls every optional integration; the narrower extras keep a test environment light.

Maturity

All published packages are alpha (0.0.x), currently 0.0.42. Breaking changes may occur before 1.0. Below 1.0, SemVer treats a minor bump as the breaking signal — which is why the pin ranges stop at <0.1. Product notes: Changelog.

See Adoption Paths for a staged guide, and Architecture for the boundary rules behind these tables.