quadkit 0.0.44__tar.gz → 0.0.46__tar.gz

{quadkit-0.0.44 → quadkit-0.0.46}/PKG-INFO

@@ -1,14 +1,14 @@
 Metadata-Version: 2.5
 Name: quadkit
-Version: 0.0.44
+Version: 0.0.46
 Summary: Async-first DI/IoC framework for Python — core package
-Project-URL: Homepage, https://dbtinoy-.github.io/quadkit/
+Project-URL: Homepage, https://oridecon.dev
 Project-URL: Repository, https://github.com/dbtinoy-/quadkit
-Project-URL: Documentation, https://dbtinoy-.github.io/quadkit/
+Project-URL: Documentation, https://oridecon.dev/quadkit/
 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>
+Author-email: Quadkit Framework Team <hello@oridecon.dev>
+Maintainer-email: Quadkit Framework Team <hello@oridecon.dev>
 License: Apache-2.0
 License-File: LICENSE
 License-File: NOTICE
@@ -140,7 +140,7 @@ asyncio.run(main())
 ```
 
 For the web quickstart (a real endpoint in minutes), see
-[the docs](https://dbtinoy-.github.io/quadkit/getting-started/first-app/).
+[the docs](https://oridecon.dev/quadkit/getting-started/first-app/).
 
 ## Expected failures are values
 
@@ -172,7 +172,7 @@ result = (
 
 In controllers, returning an `Err` renders as an RFC 7807 problem
 response automatically — see the
-[error-handling guide](https://dbtinoy-.github.io/quadkit/guides/error-handling/).
+[error-handling guide](https://oridecon.dev/quadkit/fundamentals/result-pattern/).
 
 ## Optional extras
 
@@ -203,11 +203,11 @@ Providers can also define an async `boot()` (acquire resources) and
 `shutdown()` (release them, in reverse registration order) — the
 container drives the whole lifecycle.
 
-Concepts: [contracts](https://dbtinoy-.github.io/quadkit/concepts/contracts/) ·
-[dependency injection](https://dbtinoy-.github.io/quadkit/concepts/dependency-injection/) ·
-[modules](https://dbtinoy-.github.io/quadkit/concepts/modules/) ·
-[lifecycle](https://dbtinoy-.github.io/quadkit/concepts/lifecycle/) ·
-[async model](https://dbtinoy-.github.io/quadkit/concepts/async-model/).
+Concepts: [contracts](https://oridecon.dev/quadkit/fundamentals/container-protocols/) ·
+[dependency injection](https://oridecon.dev/quadkit/fundamentals/dependency-injection/) ·
+[modules](https://oridecon.dev/quadkit/fundamentals/modules/) ·
+[lifecycle](https://oridecon.dev/quadkit/fundamentals/application-lifecycle/) ·
+[async model](https://oridecon.dev/quadkit/fundamentals/architecture/).
 
 ## Configuration
 
@@ -223,7 +223,7 @@ QK_PROFILE=production              # select a profile block
 ```
 
 See
-[configuration](https://dbtinoy-.github.io/quadkit/getting-started/configuration/).
+[configuration](https://oridecon.dev/quadkit/getting-started/configuration/).
 
 ## Error handling
 
@@ -231,36 +231,36 @@ See
 `quadkit-contracts` exception hierarchy (`QuadkitError → DomainError →
 NotFoundError`, `ValidationError`, `ConflictError`, ...) for everything
 else. The web layer renders both as problem responses — see
-[error handling](https://dbtinoy-.github.io/quadkit/guides/error-handling/).
+[error handling](https://oridecon.dev/quadkit/fundamentals/result-pattern/).
 
 ## 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](https://dbtinoy-.github.io/quadkit/getting-started/testing/).
+[testing](https://oridecon.dev/quadkit/guides/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](https://dbtinoy-.github.io/quadkit/security/secure-configuration/) and
+[secure configuration](https://oridecon.dev/quadkit/getting-started/configuration/) and
 report vulnerabilities privately per
 [SECURITY.md](https://github.com/dbtinoy-/quadkit/blob/main/SECURITY.md).
 
 ## Stability
 
-Version `0.0.44` in the `0.x` series, released in lockstep with the
-other four distributions; APIs may change between minor versions until
+Version `0.0.46` in the `0.x` series, released in lockstep with the
+other twelve distributions; APIs may change between minor versions until
 1.0 — pin an exact version
-(`quadkit==0.0.44`) or a tight range (`>=0.0.44,<0.1.0`). Full policy:
-[stability and compatibility](https://dbtinoy-.github.io/quadkit/reference/stability/).
+(`quadkit==0.0.46`) or a tight range (`>=0.0.46,<0.1.0`). Full policy:
+[stability and compatibility](https://oridecon.dev/quadkit/ecosystem/compatibility/).
 
 ## Links
 
-- **Documentation** — <https://dbtinoy-.github.io/quadkit/>
-- **Getting started** — <https://dbtinoy-.github.io/quadkit/getting-started/installation/>
+- **Documentation** — <https://oridecon.dev/quadkit/>
+- **Getting started** — <https://oridecon.dev/quadkit/getting-started/installation/>
 - **Changelog** — <https://github.com/dbtinoy-/quadkit/blob/main/CHANGELOG.md>
 - **Issues** — <https://github.com/dbtinoy-/quadkit/issues>
 - **Security** — report privately per [SECURITY.md](https://github.com/dbtinoy-/quadkit/blob/main/SECURITY.md)

{quadkit-0.0.44 → quadkit-0.0.46}/README.md

@@ -88,7 +88,7 @@ asyncio.run(main())
 ```
 
 For the web quickstart (a real endpoint in minutes), see
-[the docs](https://dbtinoy-.github.io/quadkit/getting-started/first-app/).
+[the docs](https://oridecon.dev/quadkit/getting-started/first-app/).
 
 ## Expected failures are values
 
@@ -120,7 +120,7 @@ result = (
 
 In controllers, returning an `Err` renders as an RFC 7807 problem
 response automatically — see the
-[error-handling guide](https://dbtinoy-.github.io/quadkit/guides/error-handling/).
+[error-handling guide](https://oridecon.dev/quadkit/fundamentals/result-pattern/).
 
 ## Optional extras
 
@@ -151,11 +151,11 @@ Providers can also define an async `boot()` (acquire resources) and
 `shutdown()` (release them, in reverse registration order) — the
 container drives the whole lifecycle.
 
-Concepts: [contracts](https://dbtinoy-.github.io/quadkit/concepts/contracts/) ·
-[dependency injection](https://dbtinoy-.github.io/quadkit/concepts/dependency-injection/) ·
-[modules](https://dbtinoy-.github.io/quadkit/concepts/modules/) ·
-[lifecycle](https://dbtinoy-.github.io/quadkit/concepts/lifecycle/) ·
-[async model](https://dbtinoy-.github.io/quadkit/concepts/async-model/).
+Concepts: [contracts](https://oridecon.dev/quadkit/fundamentals/container-protocols/) ·
+[dependency injection](https://oridecon.dev/quadkit/fundamentals/dependency-injection/) ·
+[modules](https://oridecon.dev/quadkit/fundamentals/modules/) ·
+[lifecycle](https://oridecon.dev/quadkit/fundamentals/application-lifecycle/) ·
+[async model](https://oridecon.dev/quadkit/fundamentals/architecture/).
 
 ## Configuration
 
@@ -171,7 +171,7 @@ QK_PROFILE=production              # select a profile block
 ```
 
 See
-[configuration](https://dbtinoy-.github.io/quadkit/getting-started/configuration/).
+[configuration](https://oridecon.dev/quadkit/getting-started/configuration/).
 
 ## Error handling
 
@@ -179,36 +179,36 @@ See
 `quadkit-contracts` exception hierarchy (`QuadkitError → DomainError →
 NotFoundError`, `ValidationError`, `ConflictError`, ...) for everything
 else. The web layer renders both as problem responses — see
-[error handling](https://dbtinoy-.github.io/quadkit/guides/error-handling/).
+[error handling](https://oridecon.dev/quadkit/fundamentals/result-pattern/).
 
 ## 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](https://dbtinoy-.github.io/quadkit/getting-started/testing/).
+[testing](https://oridecon.dev/quadkit/guides/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](https://dbtinoy-.github.io/quadkit/security/secure-configuration/) and
+[secure configuration](https://oridecon.dev/quadkit/getting-started/configuration/) and
 report vulnerabilities privately per
 [SECURITY.md](https://github.com/dbtinoy-/quadkit/blob/main/SECURITY.md).
 
 ## Stability
 
-Version `0.0.44` in the `0.x` series, released in lockstep with the
-other four distributions; APIs may change between minor versions until
+Version `0.0.46` in the `0.x` series, released in lockstep with the
+other twelve distributions; APIs may change between minor versions until
 1.0 — pin an exact version
-(`quadkit==0.0.44`) or a tight range (`>=0.0.44,<0.1.0`). Full policy:
-[stability and compatibility](https://dbtinoy-.github.io/quadkit/reference/stability/).
+(`quadkit==0.0.46`) or a tight range (`>=0.0.46,<0.1.0`). Full policy:
+[stability and compatibility](https://oridecon.dev/quadkit/ecosystem/compatibility/).
 
 ## Links
 
-- **Documentation** — <https://dbtinoy-.github.io/quadkit/>
-- **Getting started** — <https://dbtinoy-.github.io/quadkit/getting-started/installation/>
+- **Documentation** — <https://oridecon.dev/quadkit/>
+- **Getting started** — <https://oridecon.dev/quadkit/getting-started/installation/>
 - **Changelog** — <https://github.com/dbtinoy-/quadkit/blob/main/CHANGELOG.md>
 - **Issues** — <https://github.com/dbtinoy-/quadkit/issues>
 - **Security** — report privately per [SECURITY.md](https://github.com/dbtinoy-/quadkit/blob/main/SECURITY.md)

{quadkit-0.0.44 → quadkit-0.0.46}/pyproject.toml

@@ -29,7 +29,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "quadkit"
-version = "0.0.44"
+version = "0.0.46"
 description = "Async-first DI/IoC framework for Python — core package"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -55,10 +55,10 @@ classifiers = [
     "Typing :: Typed",
 ]
 authors = [
-    { name = "Quadkit Framework Team", email = "team@quadkit.dev" },
+    { name = "Quadkit Framework Team", email = "hello@oridecon.dev" },
 ]
 maintainers = [
-    { name = "Quadkit Framework Team", email = "team@quadkit.dev" },
+    { name = "Quadkit Framework Team", email = "hello@oridecon.dev" },
 ]
 
 # =============================================================================
@@ -138,9 +138,9 @@ web = [
 # =============================================================================
 
 [project.urls]
-Homepage = "https://dbtinoy-.github.io/quadkit/"
+Homepage = "https://oridecon.dev"
 Repository = "https://github.com/dbtinoy-/quadkit"
-Documentation = "https://dbtinoy-.github.io/quadkit/"
+Documentation = "https://oridecon.dev/quadkit/"
 Issues = "https://github.com/dbtinoy-/quadkit/issues"
 Changelog = "https://github.com/dbtinoy-/quadkit/blob/main/CHANGELOG.md"
 

{quadkit-0.0.44 → quadkit-0.0.46}/src/quadkit/app/base.py

@@ -29,6 +29,7 @@ if TYPE_CHECKING:
     from collections.abc import AsyncIterator
 
     from quadkit.di.module.dynamic import DynamicModule
+    from quadkit.di.module.graph import CompiledModuleGraph
     from quadkit.di.provider import Provider
     from quadkit.logging import LoggerProtocol
 
@@ -73,7 +74,7 @@ class Application(SecretsMixin, HealthProbeMixin):
         self._state = AppState.CREATED
         self._container = Container()
         self._container.singleton(type(self), self)
-        self._orchestrator = ProviderOrchestrator(self._container)
+        self._orchestrator: ProviderOrchestrator = ProviderOrchestrator(self._container)
 
         self._config = config or QuadkitConfig.from_env_profile()
         self._container.singleton(QuadkitConfig, self._config)
@@ -136,6 +137,23 @@ class Application(SecretsMixin, HealthProbeMixin):
         """DI container."""
         return self._container
 
+    @property
+    def module_graph(self) -> CompiledModuleGraph | None:
+        """The compiled module graph, or ``None`` before compilation.
+
+        Read-only view of what the boot sequence compiled: every module with
+        its providers, imports, and fully expanded exports. It exists so
+        boot-time guards can assert that what a module *declares* it exports is
+        what the container can actually resolve — the failure this graph is
+        otherwise blind to, because an export that nothing resolves during
+        boot only fails later, at ``QK_ERR_DI_004`` on first use, or never.
+
+        Returns:
+            The compiled graph, or ``None`` when the application has not been
+            compiled yet.
+        """
+        return self._orchestrator.compiled_graph
+
     @property
     def providers(self) -> list[Provider]:
         """Get all registered providers."""

{quadkit-0.0.44 → quadkit-0.0.46}/src/quadkit/concurrency/channels/channel.py

@@ -65,6 +65,12 @@ class BoundedChannel(Generic[T]):
         )
         self._closed = False
         self._lock = asyncio.Lock()
+        #: Set whenever something a waiting receiver cares about happened:
+        #: an item arrived or the channel closed. Receivers clear it before
+        #: they wait. They never dequeue from a helper task, so an item is
+        #: either in the queue or in the consumer's hands — there is no tick
+        #: in between where ``is_empty`` lies.
+        self._wakeup = asyncio.Event()
 
     async def send(self, item: T) -> None:
         """Send an item, blocking if the channel is full.
@@ -91,6 +97,7 @@ class BoundedChannel(Generic[T]):
             # full, but that means the item was never actually enqueued.
             with suppress(asyncio.QueueFull):
                 self._queue.put_nowait(wrapped)
+                self._wakeup.set()
             raise
         except asyncio.QueueFull:
             msg = "Channel is full"
@@ -98,6 +105,7 @@ class BoundedChannel(Generic[T]):
                 msg,
                 capacity=self.capacity,
             ) from None
+        self._wakeup.set()
 
     def send_nowait(self, item: T) -> None:
         """Send an item without blocking.
@@ -128,6 +136,7 @@ class BoundedChannel(Generic[T]):
         except asyncio.QueueFull:
             msg = "Channel is full"
             raise ChannelFullError(msg, capacity=self.capacity) from None
+        self._wakeup.set()
 
     async def receive(self) -> T:
         """Receive an item, blocking if the channel is empty.
@@ -138,29 +147,40 @@ class BoundedChannel(Generic[T]):
         Raises:
             ChannelClosedError: If the channel is closed and empty.
         """
-        try:
-            wrapped: _ContextualItem[T] = await self._queue.get()
-        except asyncio.CancelledError:
-            # If cancelled after the queue internally dequeued an item,
-            # put it back so it is not lost.  get_nowait will raise
-            # QueueEmpty if nothing was actually dequeued yet.
-            try:
-                item_back = self._queue.get_nowait()
-                self._queue.put_nowait(item_back)
-            except asyncio.QueueEmpty:
-                pass
-            raise
-        except asyncio.QueueEmpty:
-            if self._closed:
-                msg = "Channel is closed"
-                raise ChannelClosedError(msg) from None
-            raise
+        wrapped = await self._next_item()
         # Restore sender's context variables so OTel trace spans and other
         # context state are propagated to the consumer.
         for var, value in wrapped.ctx.items():
             var.set(value)
         return wrapped.item
 
+    async def _next_item(self) -> _ContextualItem[T]:
+        """Dequeue the next wrapped item, or raise once closed and drained.
+
+        The hot path — an item is already queued — is a plain
+        ``get_nowait``. Only an empty channel waits, and it waits on one
+        wake-up that both :meth:`send` and :meth:`close` raise. Without the
+        close half, ``close()`` could not end an ``async for`` over an empty
+        channel, and every consumer loop would outlive the thing it consumed.
+
+        The dequeue itself is always synchronous in the consumer's own task.
+        Pulling the item inside a helper task would open a window where the
+        queue is already empty but the consumer has not resumed yet — a
+        caller polling ``is_empty`` (the event bus's ``flush``) would
+        conclude the work was done one tick before it started.
+        """
+        while True:
+            try:
+                return self._queue.get_nowait()
+            except asyncio.QueueEmpty:
+                if self._closed:
+                    msg = "Channel is closed"
+                    raise ChannelClosedError(msg) from None
+            # Nothing queued and not closed: both facts were read without an
+            # intervening await, so clearing here cannot swallow a wake-up.
+            self._wakeup.clear()
+            await self._wakeup.wait()
+
     def receive_nowait(self) -> T:
         """Receive an item without blocking.
 
@@ -183,9 +203,15 @@ class BoundedChannel(Generic[T]):
         return wrapped.item
 
     async def close(self) -> None:
-        """Close the channel. Remaining items can still be received."""
+        """Close the channel. Remaining items can still be received.
+
+        Receivers blocked on an empty channel are woken and get
+        :class:`ChannelClosedError` (``StopAsyncIteration`` under
+        ``async for``), so a consumer loop ends when its producer does.
+        """
         async with self._lock:
             self._closed = True
+            self._wakeup.set()
 
     @property
     def is_closed(self) -> bool:

{quadkit-0.0.44 → quadkit-0.0.46}/src/quadkit/di/module/compiler/phases/collect.py

@@ -95,7 +95,7 @@ class CollectPhase:
             raise ModuleError(
                 f"'{cls.__name__}' is not decorated with @module.\n"
                 f"\n"
-                f"Reference: {DOCS_BASE_URL}/modules#declaration",
+                f"Reference: {DOCS_BASE_URL}/fundamentals/modules/",
                 hint=(
                     f"Add @module() to {cls.__name__}, or import "
                     f"{cls.__name__}.configure() instead."

{quadkit-0.0.44 → quadkit-0.0.46}/src/quadkit/di/module/errors.py

@@ -47,7 +47,7 @@ def format_cycle_error(cycle: list[str]) -> str:
         f"  1. Extract shared types into a separate module\n"
         f"  2. Remove the circular import from one side\n"
         f"\n"
-        f"Reference: {DOCS_BASE_URL}/modules#cycles"
+        f"Reference: {DOCS_BASE_URL}/fundamentals/modules/"
     )
 
 
@@ -88,7 +88,7 @@ def format_missing_import_error(
         f"  1. Add {missing_name} to your create_app() via app.add_module()\n"
         f"  2. Or remove {missing_name} from {module_name}.imports\n"
         f"\n"
-        f"Reference: {DOCS_BASE_URL}/modules#imports"
+        f"Reference: {DOCS_BASE_URL}/fundamentals/modules/"
     )
 
 
@@ -192,7 +192,7 @@ def format_visibility_error(
         f"    2. Make the exporting module global with @module(is_global=True)\n"
         f"    3. Depend on a service that is already exported\n"
         f"\n"
-        f"  Reference: {DOCS_BASE_URL}/modules#visibility"
+        f"  Reference: {DOCS_BASE_URL}/fundamentals/modules/"
     )
 
 
@@ -232,7 +232,7 @@ def format_duplicate_module_error(
         f"  1. Remove one of the add_module() calls\n"
         f"  2. Or merge the configurations into a single configure() call\n"
         f"\n"
-        f"Reference: {DOCS_BASE_URL}/modules#configuration"
+        f"Reference: {DOCS_BASE_URL}/fundamentals/modules/"
     )
 
 

{quadkit-0.0.44 → quadkit-0.0.46}/src/quadkit/di/orchestrator/orchestrator.py

@@ -110,6 +110,24 @@ class ProviderOrchestrator:
         """
         self._registry._compiled_graph = graph
 
+    @property
+    def compiled_graph(self) -> CompiledModuleGraph | None:
+        """The compiled module graph, or ``None`` before compilation.
+
+        The public companion to :meth:`set_compiled_graph`. The graph is what
+        knows which module declares which export, and the code that needs to
+        answer that question lives outside this class: health probes, boot-time
+        assertions, and test guards. Without a reader the only way to ask was
+        the private ``_compiled_graph``, so every such caller reached into the
+        orchestrator's internals — and a rename would have broken them without
+        a test to notice.
+
+        Returns:
+            The graph produced by :class:`ModuleCompiler`, or ``None`` when the
+            application has not been compiled yet.
+        """
+        return self._registry._compiled_graph
+
     def add(self, provider: Provider) -> None:
         """Add a provider to be orchestrated.
 

{quadkit-0.0.44 → quadkit-0.0.46}/src/quadkit/di/resolution/resolver.py

@@ -187,6 +187,26 @@ class ServiceResolver:
 
             return instance
 
+    async def resolve_optional(self, service_type: Any) -> Any | None:
+        """Resolve a service, returning ``None`` when it is not registered.
+
+        ``ContainerResolverProtocol`` has declared this method all along, and
+        the container implements it, but the resolver handed to provider
+        factories did not: a provider asking for an optional dependency had to
+        pair ``has()`` with ``resolve()`` and hope nothing moved in between.
+        Absent means absent — a registered service whose construction raises
+        still raises.
+
+        Args:
+            service_type: The type to resolve.
+
+        Returns:
+            The resolved instance, or ``None`` when nothing is registered for it.
+        """
+        if not self.can_resolve(service_type):
+            return None
+        return await self.resolve(service_type)
+
     async def _create_instance(self, descriptor: ServiceDescriptor) -> Any:
         """Create a service instance from its descriptor."""
         impl = descriptor.implementation