Metadata-Version: 2.5
Name: quadkit
Version: 0.0.3
Summary: Async-first DI/IoC framework for Python — core package
Project-URL: Homepage, https://quadkit.dev
Project-URL: Repository, https://github.com/dbtinoy-/quadkit
Project-URL: Documentation, https://quadkit.dev
Project-URL: Issues, https://github.com/dbtinoy-/quadkit/issues
Project-URL: Changelog, https://github.com/dbtinoy-/quadkit/blob/main/CHANGELOG.md
Author-email: Quadkit Framework Team <team@quadkit.dev>
Maintainer-email: Quadkit Framework Team <team@quadkit.dev>
License: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: async,dependency-injection,framework,ioc,provider-pattern
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: orjson>=3.0.0
Requires-Dist: pydantic>=2.10.0
Requires-Dist: quadkit-contracts>=0.0.2
Requires-Dist: structlog<27,>=25.1.0
Provides-Extra: codegen
Requires-Dist: jinja2>=3.1.0; extra == 'codegen'
Provides-Extra: dev
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pre-commit>=3.0.0; extra == 'dev'
Requires-Dist: ruff>=0.16.4; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.0.0; extra == 'docs'
Requires-Dist: mkdocs>=1.4.0; extra == 'docs'
Provides-Extra: security
Requires-Dist: cryptography>=41.0.0; extra == 'security'
Provides-Extra: test
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'test'
Requires-Dist: pytest-cov>=4.0.0; extra == 'test'
Requires-Dist: pytest-mock>=3.10.0; extra == 'test'
Requires-Dist: pytest>=8.0.0; extra == 'test'
Provides-Extra: web
Requires-Dist: quadkit-web[granian]>=0.0.2; extra == 'web'
Description-Content-Type: text/markdown

# 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

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

Requires **Python >= 3.11**.

## Minimal working example

```python
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](../../docs/getting-started/first-app.md).

## Optional extras

| Extra | Contents |
| --- | --- |
| `quadkit[web]` | `quadkit-web[granian]` — the full web stack |
| `quadkit[test]` | `pytest`, `pytest-asyncio`, `pytest-cov`, `pytest-mock` |
| `quadkit[security]` | `cryptography` (signing/token helpers) |
| `quadkit[codegen]` | code generation toolchain |
| `quadkit[docs]` / `[dev]` | documentation / development tooling |

## Public API entry points

```python
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](../../docs/concepts/contracts.md) ·
[dependency injection](../../docs/concepts/dependency-injection.md) ·
[modules](../../docs/concepts/modules.md) ·
[lifecycle](../../docs/concepts/lifecycle.md) ·
[async model](../../docs/concepts/async-model.md).

## 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](../../docs/getting-started/configuration.md).

## 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](../../docs/guides/error-handling.md).

## 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](../../docs/getting-started/testing.md).

## 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](../../docs/security/secure-configuration.md) and
report vulnerabilities privately per
[SECURITY.md](../../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](../../docs/reference/stability.md).

Changelog: [`CHANGELOG.md`](./CHANGELOG.md) ·
Issues: <https://github.com/dbtinoy-/quadkit/issues>
