quadkit

Async-first application framework for Python: dependency-injection container, application lifecycle, typed configuration, and the Result error model. This is the core package; everything else published from this repository builds on it.

For application developers — write providers and modules, bind contracts, and let one container boot them in order.

Installation

uv add quadkit
# batteries-included web stack:
uv add "quadkit[web]"

Requires Python >= 3.11.

Minimal working example

import asyncio

from quadkit import Application
from quadkit.contracts.core.di import ContainerRegistrarProtocol
from quadkit.di.provider import Provider


class Settings:
    greeting = "hello, quadkit"


class SettingsProvider(Provider):
    async def register(self, container: ContainerRegistrarProtocol) -> None:
        container.singleton(Settings, instance=Settings())


async def main() -> None:
    app = Application()
    app.add_provider(SettingsProvider())
    await app.start()
    try:
        settings = await app.container.resolve(Settings)
        print(settings.greeting)
    finally:
        await app.stop()


asyncio.run(main())

For the web quickstart (a real endpoint in minutes), see the docs.

Optional extras

Public API entry points

from quadkit import Application, Result, Ok, Err
from quadkit.di.provider import Provider
from quadkit.di.container import Container
from quadkit.logging import get_logger
from quadkit.contracts.core.di import (
    ContainerRegistrarProtocol,
    ContainerResolverProtocol,
)

Concepts: contracts · dependency injection · modules · lifecycle · async model.

Configuration

application.yaml at the working directory, validated against typed config models at boot (unknown keys fail fast); application metadata lives at the root (name, version, description); every typed key overrides from the environment with QK_<SECTION>__<KEY>. Use QK_PROFILE to select a profile. See configuration.

Error handling

Result[T, E] for expected domain failures; the quadkit-contracts exception hierarchy (QuadkitError → DomainError → NotFoundError, ValidationError, ConflictError, ...) for everything else. The web layer renders both as problem responses — see error handling.

Testing

Pair with quadkit-testing: AppTestBed.from_factory(create_app) boots your application in-process (with overrides={Contract: fake} for test doubles), no server required. See testing.

Security

Never put secrets in application.yaml — pass them through QK_* environment variables or a secret store. Unexpected exceptions never leak internals to clients. See secure configuration and report vulnerabilities privately per SECURITY.md.

Stability

Version 0.0.3 in the 0.x series, released in lockstep with the other four distributions; APIs may change between minor versions until 1.0 — pin an exact version (quadkit==0.0.3) or a tight range (>=0.0.3,<0.1.0). Full policy: stability and compatibility.

Changelog: CHANGELOG.md · Issues: https://github.com/dbtinoy-/quadkit/issues