quadkit 0.0.2__tar.gz → 0.0.3__tar.gz

quadkit-0.0.3/.gitignore

@@ -0,0 +1,24 @@
+# Generated public-repository ignore rules.
+# Private monorepo paths are intentionally not referenced here.
+
+__pycache__/
+*.py[cod]
+*.so
+*.egg-info/
+.venv/
+venv/
+.env
+.env.*
+!.env.example
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+coverage.xml
+htmlcov/
+build/
+dist/
+*.log
+.DS_Store
+.idea/
+.vscode/

quadkit-0.0.3/PKG-INFO

@@ -0,0 +1,179 @@
+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>

quadkit-0.0.3/README.md

@@ -0,0 +1,128 @@
+# 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>

{quadkit-0.0.2 → quadkit-0.0.3}/example.yaml

@@ -5,7 +5,7 @@
 # Top-level env var prefix: QK_  (nested delimiter: __)
 #
 # Core fields are declared at the top level of this file.
-# Extension packages (quadkit-cache, quadkit-sql, etc.) each add their own
+# Extension packages (the optional provider, the optional provider, etc.) each add their own
 # top-level section (e.g. cache:, sql:, ai:) read by their own Config class.
 
 # -- Application Identity --------------------------------------------------
@@ -243,7 +243,7 @@ security:
     pbkdf2_iterations: 600000
 
 # -- Observability ---------------------------------------------------------
-# NEW -- Core observability hooks. Full OTLP/Prometheus config is in quadkit-monitor.
+# NEW -- Core observability hooks. Full OTLP/Prometheus config is in the optional provider.
 
 observability:
   # Master switch. When false, no-op implementations are used unconditionally.

{quadkit-0.0.2 → quadkit-0.0.3}/pyproject.toml

@@ -10,10 +10,7 @@
 #   - Structured logging foundation
 #
 # It does NOT contain:
-#   - Database code          → quadkit-sql
-#   - Auth/JWT/crypto        → quadkit-auth
 #   - HTTP/ASGI/routing      → quadkit-web
-#   - Message queue / email  → quadkit-queue / quadkit-mailer / quadkit-notification
 #   - Any domain-specific feature
 #
 # Core should be lightweight. `pip install quadkit` should take seconds,
@@ -30,7 +27,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "quadkit"
-version = "0.0.2"
+version = "0.0.3"
 description = "Async-first DI/IoC framework for Python — core package"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -130,7 +127,7 @@ web = [
 # events, tasks, monitor, graphql) were removed. Those packages are not
 # published, so the extras resolved against name-reservation placeholders
 # that contain no code: `pip install quadkit[cache]` succeeded and then
-# `import quadkit.cache` raised ModuleNotFoundError. Install extension
+# `import the optional provider module` raised ModuleNotFoundError. Install extension
 # packages directly once they are published.
 
 # =============================================================================
@@ -287,3 +284,4 @@ show_missing = true
 [tool.uv.sources]
 quadkit-contracts = { workspace = true }
 
+

{quadkit-0.0.2 → quadkit-0.0.3}/src/quadkit/app/base.py

@@ -439,7 +439,9 @@ class Application(SecretsMixin, HealthProbeMixin):
             return self._apply_details_policy(
                 self._probe_unavailable_result(HealthCheckCategory.STARTUP)
             )
-        return self._apply_details_policy(await self._orchestrator.run_startup(timeout))
+        started = await self._orchestrator.run_startup(timeout)
+        started = self._baseline_component(started, HealthCheckCategory.STARTUP)
+        return self._apply_details_policy(started)
 
     # -- Convenience -------------------------------------------------------
 

{quadkit-0.0.2 → quadkit-0.0.3}/src/quadkit/app/health_probes.py

@@ -97,6 +97,32 @@ class HealthProbeMixin:
             AggregateHealthResult(components=list(raw.values()))
         )
 
+    def _baseline_component(
+        self,
+        result: AggregateHealthResult,
+        category: HealthCheckCategory,
+    ) -> AggregateHealthResult:
+        """Ensure a running application always reports a baseline component.
+
+        Probe categories aggregate whatever checks register against them,
+        and an empty pool would otherwise surface as ``UNKNOWN``.  The
+        running application itself is the truthful baseline signal: live,
+        started, and able to serve.  Registered checks still gate the
+        aggregate — seeding only applies when nothing else reported.
+        """
+        if result.components:
+            return result
+        return AggregateHealthResult(
+            components=[
+                HealthCheckResult(
+                    component=self.name,
+                    status=HealthStatus.HEALTHY,
+                    message="application running",
+                    category=category,
+                )
+            ]
+        )
+
     def _probe_unavailable_result(
         self,
         category: HealthCheckCategory,
@@ -122,9 +148,9 @@ class HealthProbeMixin:
             return self._apply_details_policy(
                 self._probe_unavailable_result(HealthCheckCategory.LIVENESS)
             )
-        return self._apply_details_policy(
-            await self._orchestrator.run_liveness(timeout)
-        )
+        live = await self._orchestrator.run_liveness(timeout)
+        live = self._baseline_component(live, HealthCheckCategory.LIVENESS)
+        return self._apply_details_policy(live)
 
     async def readiness(self, timeout: float | None = None) -> AggregateHealthResult:
         """Run readiness checks for the application."""
@@ -135,9 +161,9 @@ class HealthProbeMixin:
             return self._apply_details_policy(
                 self._probe_unavailable_result(HealthCheckCategory.READINESS)
             )
-        return self._apply_details_policy(
-            await self._orchestrator.run_readiness(timeout)
-        )
+        ready = await self._orchestrator.run_readiness(timeout)
+        ready = self._baseline_component(ready, HealthCheckCategory.READINESS)
+        return self._apply_details_policy(ready)
 
 
 __all__ = ["HealthProbeMixin"]

{quadkit-0.0.2 → quadkit-0.0.3}/src/quadkit/app/module.py

@@ -15,7 +15,7 @@ Kernel providers (boot order governed by provider ``priority`` and ``dependencie
 For a batteries-included bundle that also provides serialization and
 concurrency, use :class:`~quadkit.app.standard.StandardModule` instead.
 
-Extension packages (``quadkit-cache``, ``quadkit-auth``, ``quadkit-web``,
+Extension packages (``the optional provider``, ``the optional provider``, ``quadkit-web``,
 etc.) register their own providers via ``app.add_provider()`` or
 ``app.add_module()``.  ``CoreModule`` intentionally imports **only** from
 ``quadkit-contracts`` and the ``quadkit`` core package — zero cross-package

{quadkit-0.0.2 → quadkit-0.0.3}/src/quadkit/config/base.py

@@ -329,11 +329,13 @@ def _unknown_config_keys(
     """
     import typing
 
-    fields = getattr(model_cls, "__dataclass_fields__", {})
+    fields = dict(getattr(model_cls, "__dataclass_fields__", {}) or {})
     try:
         hints = typing.get_type_hints(model_cls)
     except Exception:  # noqa: BLE001 — unresolvable refs degrade to flat check
         hints = {}
+    for hinted_name in hints:
+        fields.setdefault(hinted_name, None)
 
     unknown: list[str] = []
     for key, value in data.items():

{quadkit-0.0.2 → quadkit-0.0.3}/src/quadkit/di/container/container.py

@@ -4,9 +4,12 @@ from __future__ import annotations
 
 from typing import (
     TYPE_CHECKING,
+    Annotated,
     Any,
     TypeVar,
     cast,
+    get_args,
+    get_origin,
     overload,
 )
 
@@ -403,6 +406,17 @@ class Container(
                 consumer_name = module.__name__ if module else "unknown"
                 graph = _module_graph.get()
 
+                if get_origin(service_type) is Annotated:
+                    annotated_args = get_args(service_type)
+                    if annotated_args:
+                        service_type = annotated_args[0]
+
+                providing_module = self._registry.providing_module(service_type)
+                if providing_module is module and module is not None:
+                    # Private to the consuming module itself — no
+                    # cross-module surface is involved.
+                    return await self.__service_resolver.resolve(service_type)
+
                 if (
                     graph is not None
                     and module is not None
@@ -421,27 +435,44 @@ class Container(
                     exporting_names = [node.name for node in exporting_nodes]
 
                     if not exporting_names:
-                        return await self.__service_resolver.resolve(service_type)
-
-                    exported_types = sorted(
-                        {
-                            export.__name__
-                            for node in exporting_nodes
-                            for export in getattr(node, "exports", [])
-                        }
-                    )
-                    message = format_visibility_error(
-                        consumer_module=consumer_name,
-                        consumer_provider=consumer_name,
-                        provider_module=exporting_names,
-                        service_type=service_type.__name__,
-                        exported_types=exported_types,
-                        consumer_imports=consumer_imports,
-                    )
-                    hint = (
-                        f"Import one of {exporting_names or ['the exporting module']} "
-                        f"into {consumer_name}, or make it global."
-                    )
+                        if providing_module is None:
+                            # Not registered through any module and not
+                            # exported anywhere — a standalone or framework
+                            # service, outside the module surface.
+                            return await self.__service_resolver.resolve(service_type)
+                        providing_name = getattr(
+                            providing_module, "__name__", "its provider module"
+                        )
+                        message = (
+                            f"Module '{consumer_name}' cannot resolve "
+                            f"'{service_type.__name__}': provided by "
+                            f"'{providing_name}' but not exported by it"
+                        )
+                        hint = (
+                            f"Export {service_type.__name__} from "
+                            f"'{providing_name}', or provide it from a "
+                            "global module."
+                        )
+                    else:
+                        exported_types = sorted(
+                            {
+                                export.__name__
+                                for node in exporting_nodes
+                                for export in getattr(node, "exports", [])
+                            }
+                        )
+                        message = format_visibility_error(
+                            consumer_module=consumer_name,
+                            consumer_provider=consumer_name,
+                            provider_module=exporting_names,
+                            service_type=service_type.__name__,
+                            exported_types=exported_types,
+                            consumer_imports=consumer_imports,
+                        )
+                        hint = (
+                            f"Import one of {exporting_names} "
+                            f"into {consumer_name}, or make it global."
+                        )
                 else:
                     message = (
                         f"Module '{consumer_name}' cannot resolve "

{quadkit-0.0.2 → quadkit-0.0.3}/src/quadkit/di/container/registrar.py

@@ -2,12 +2,17 @@
 
 from __future__ import annotations
 
+import contextlib
 from typing import TYPE_CHECKING, TypeVar
 
 from quadkit.contracts.exceptions import ContainerError
+from quadkit.di.context import get_current_module
 from quadkit.di.resolution.registry import ServiceRegistry
 from quadkit.logging import get_logger
 
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
 if TYPE_CHECKING:
     from quadkit.di.types import ServiceFactory
 
@@ -40,6 +45,24 @@ class ContainerRegistrarImpl:
         """Prevent any further service registrations."""
         self._frozen = True
 
+    @contextlib.contextmanager
+    def _registration_window(self) -> Iterator[None]:
+        """Framework-managed window that reopens registration for the boot phase.
+
+        ``freeze()`` closes registration to user code permanently. Providers
+        that materialize services during boot (e.g. ``@provide`` factories)
+        bind their products after the container has frozen, which the
+        lifecycle manager performs inside this window. The window restores
+        the frozen state on exit — including on error — so the freeze
+        guarantee outside the boot phase is unchanged.
+        """
+        was_frozen = self._frozen
+        self._frozen = False
+        try:
+            yield
+        finally:
+            self._frozen = was_frozen
+
     def clear(self) -> None:
         """Clear all registered services.
 
@@ -71,6 +94,7 @@ class ContainerRegistrarImpl:
                 "Cannot register transient service after container is frozen",
             )
         self._registry.transient(service_type, factory, validate=validate)
+        self._registry.attribute(service_type, get_current_module())
 
     def singleton(
         self,
@@ -104,6 +128,7 @@ class ContainerRegistrarImpl:
             factory=factory,
             validate=validate,
         )
+        self._registry.attribute(service_type, get_current_module())
 
     def scoped(
         self,
@@ -129,6 +154,7 @@ class ContainerRegistrarImpl:
                 "Cannot register scoped service after container is frozen",
             )
         self._registry.scoped(service_type, factory, validate=validate, name=name)
+        self._registry.attribute(service_type, get_current_module())
 
     def override(self, service_type: type[T], instance: T) -> None:
         """Replace a service registration for testing purposes.

{quadkit-0.0.2 → quadkit-0.0.3}/src/quadkit/di/decorators.py

@@ -97,6 +97,13 @@ def injectable(
 ) -> Callable[[type[T]], type[T]] | type[T]:
     """Decorator to mark a class as injectable.
 
+    The ``scope`` metadata is honored where a descriptor is created for the
+    class: by ``discover_injectables()`` (module scanning) and by explicit
+    Provider registration. Resolving the class directly from a bare
+    ``Container`` without either step is not supported — the container only
+    auto-wires classes carrying ``@inject``-style constructor markers and
+    raises ``QK_ERR_DI_004`` otherwise.
+
     Args:
         scope_or_cls: The service scope or the class if used without parens.
         name: Optional name for the service registration.

{quadkit-0.0.2 → quadkit-0.0.3}/src/quadkit/di/extensions/discovery.py

@@ -127,7 +127,7 @@ class ProviderScanner:
 def import_string(dotted_path: str) -> Any:
     """Import a dotted module path and return the attribute at the end.
 
-    E.g. 'quadkit.sql.DatabaseService' imports 'quadkit.sql' and returns
+    E.g. 'the optional provider module' imports 'the optional provider module' and returns
     the 'DatabaseService' attribute.
     """
     try: