wireup 2.9.0__tar.gz → 2.10.0__tar.gz

{wireup-2.9.0 → wireup-2.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wireup
-Version: 2.9.0
+Version: 2.10.0
 Summary: Python Dependency Injection Library
 Project-URL: Homepage, https://github.com/maldoinc/wireup
 Project-URL: Repository, https://github.com/maldoinc/wireup
@@ -67,7 +67,7 @@ Reuse the same application code in APIs, CLIs, workers, and scripts without rewr
 </td>
 <td align="center" valign="top" width="33%">
 <h3>✅ Correct by Default</h3>
-If the container starts, your dependency graph is valid. Wireup checks for missing or misconfigured dependencies to avoid surprises at runtime.
+If the container starts, your dependency graph is valid. Wireup checks for missing or misconfigured dependencies to avoid surprises at runtime. See <a href="https://maldoinc.github.io/wireup/latest/what_wireup_validates/">What Wireup Validates</a>
 </td>
 <td align="center" valign="top" width="33%">
 <h3>🌐 Framework-Ready</h3>
@@ -311,7 +311,7 @@ class OrderProcessor:
 
 ### 🛡️ Startup Validation
 
-Wireup validates the dependency graph when the container is created.
+Wireup validates the dependency graph when the container is created. See <a href="https://maldoinc.github.io/wireup/latest/what_wireup_validates/">What Wireup Validates</a> for the full rules and limits.
 
 ```python
 # Missing dependencies: caught at startup, not at runtime

{wireup-2.9.0 → wireup-2.10.0}/docs/mkdocs.yml

@@ -20,7 +20,9 @@ nav:
       - Conditional Registration: conditional_registration.md
       - Generic Dependencies: generic_dependencies.md
     - Guides:
+      - Packaging Injectables: packaging_injectables.md
       - Testing: testing.md
+      - What Wireup Validates: what_wireup_validates.md
       - Upgrading: upgrading.md
       - Versioning: versioning.md
 

wireup-2.10.0/docs/pages/class/fastapi_integration.md

@@ -0,0 +1,8 @@
+## wireup.integration.fastapi
+
+::: wireup.integration.fastapi
+
+!!! note
+    For best performance with `WireupTask`, prefer regular top-level functions for background task callbacks.
+    Wireup creates cached injection wrappers for top-level functions, but callable objects and nested
+    functions/closures do not benefit from that caching.

wireup-2.10.0/docs/pages/class/starlette_integration.md

@@ -0,0 +1,8 @@
+## wireup.integration.flask
+
+::: wireup.integration.starlette
+
+!!! note
+    For best performance with `WireupTask`, prefer regular top-level functions for background task callbacks.
+    Wireup creates cached injection wrappers for top-level functions, but callable objects and nested
+    functions/closures do not benefit from that caching.

{wireup-2.9.0 → wireup-2.10.0}/docs/pages/container.md

@@ -129,41 +129,62 @@ db_url = container.config.get("database_url")
 
     Prefer `Inject(config="key")` in dependency constructors over accessing `container.config` directly.
 
+
+### `override`
+
+Substitute dependencies for testing. Access via `container.override`.
+
+```python
+with container.override.injectable(target=Database, new=mock_db):
+    ...  # All injections of Database use mock_db
+```
+
+See [Testing](testing.md) for details.
+
+
 ## Injecting The Container
 
-Wireup registers the root container itself as an injectable during container creation. This means other injectables can
-depend on `SyncContainer` or `AsyncContainer` directly depending on the container type.
+The container can inject itself just like any other dependency. This is an advanced feature for infrastructure code that needs runtime container access. This pattern is generally not recommended for regular injectables when you know the required dependencies ahead of time.
+
+Depend on the root container by type:
+
+- `SyncContainer`, `ScopedSyncContainer` when using a synchronous container created via `wireup.create_sync_container`
+- `AsyncContainer`, `ScopedAsyncContainer` when using an asynchronous container created via `wireup.create_async_container`
+
+Typical examples include:
+
+- Selecting a handler or implementation at runtime based on a qualifier or runtime data
+- Wrapping background tasks or callbacks so they run with Wireup injection
+- Coordinating fan-out work across child scopes while letting services inside each child scope access that child scope
+- Loading optional integrations only when a feature is enabled
 
 ```python
-from wireup import injectable
-from wireup.ioc.container.sync_container import SyncContainer
+from wireup import SyncContainer, injectable
 
 
 @injectable
-class NeedsContainer:
+class BackgroundTaskScheduler:
     def __init__(self, container: SyncContainer) -> None:
         self.container = container
 ```
 
-This is mainly useful for advanced use cases where you need runtime
-access to the container. For a full example of wrapping callables dynamically, see
-[Function Injection: Dynamic Function Injection](function_injection.md#dynamic-function-injection).
+If you need the active scope rather than the root container, depend on the scoped container type:
 
-!!! important
-
-    Prefer regular constructor injection for application services. Inject the container only for advanced scenarios
-    where you truly need runtime access to it.
-
-### `override`
+```python
+from wireup import ScopedSyncContainer, injectable
 
-Substitute dependencies for testing. Access via `container.override`.
 
-```python
-with container.override.injectable(target=Database, new=mock_db):
-    ...  # All injections of Database use mock_db
+@injectable(lifetime="scoped")
+class JobDispatcher:
+    def __init__(self, scope: ScopedSyncContainer) -> None:
+        self.scope = scope
 ```
 
-See [Testing](testing.md) for details.
+For a full example of wrapping callables dynamically, see
+[Function Injection: Dynamic Function Injection](function_injection.md#dynamic-function-injection). For examples of
+passing selected dependencies into child scopes, see
+[Lifetimes & Scopes: Sharing Context Across Scopes](lifetimes_and_scopes.md#sharing-context-across-scopes).
+
 
 ## Eager Initialization
 

{wireup-2.9.0 → wireup-2.10.0}/docs/pages/index.md

@@ -21,7 +21,7 @@ and designed to fail fast: **if the container starts, it works**.
     Wireup catches missing dependencies, circular references, lifetime mismatches, duplicate registrations, and missing
     config keys at startup. Shared dependencies are created in a thread-safe way.
 
-    [:octicons-arrow-right-24: Validation checks](#validation-checks)
+    [:octicons-arrow-right-24: What Wireup Validates](what_wireup_validates.md)
 
 - :material-share-variant:{ .lg .middle } __Define Once, Inject Anywhere__
 
@@ -237,50 +237,11 @@ pip install wireup
 
 ## Validation checks
 
-Wireup validates dependencies and configuration at startup.
+Wireup validates the dependency graph up front and applies the same checks to injection targets it can inspect during
+setup. That includes missing dependencies, missing config keys, circular dependencies, lifetime mismatches, and
+duplicate registrations.
 
-=== "Container creation"
-
-    ```python
-    @injectable
-    class Foo:
-        def __init__(self, oops: UnknownDep) -> None: ...
-
-
-    container = wireup.create_sync_container(injectables=[Foo])
-    # ❌ Parameter 'oops' of 'Foo' depends on an unknown injectable 'UnknownDep'.
-    ```
-
-=== "Function injection"
-
-    ```python
-    container = wireup.create_sync_container(injectables=[])
-
-
-    @inject_from_container(container)
-    def my_function(oops: Injected[UnknownDep]) -> None: ...
-
-
-    # ❌ Parameter 'oops' of 'my_function' depends on an unknown injectable 'UnknownDep'.
-    ```
-
-=== "Configuration"
-
-    ```python
-    @injectable
-    class Database:
-        def __init__(
-            self, url: Annotated[str, Inject(config="db_url")]
-        ) -> None: ...
-
-
-    container = wireup.create_sync_container(injectables=[Database], config={})
-    # ❌ Parameter 'url' of Type 'Database' depends on an unknown Wireup config key 'db_url'.
-    ```
-
-Additional checks include circular dependencies, lifetime mismatches, and duplicate registrations. See
-[Container](container.md), [Configuration](configuration.md), and [Function Injection](function_injection.md) for
-details.
+See [What Wireup Validates](what_wireup_validates.md) for a detailed explanation.
 
 ## Next Steps
 

{wireup-2.9.0 → wireup-2.10.0}/docs/pages/integrations/aiohttp/index.md

@@ -186,6 +186,13 @@ async def users_list(
     pass
 ```
 
+### Dependency Validation
+
+The aiohttp integration validates handlers during app startup.
+Missing dependencies and config values fail before requests are served.
+
+See [What Wireup Validates](../../what_wireup_validates.md) for the full rules.
+
 ### API Reference
 
 - [aiohttp_integration](../../class/aiohttp_integration.md)

{wireup-2.9.0 → wireup-2.10.0}/docs/pages/integrations/click/index.md

@@ -100,6 +100,13 @@ def test_random_number_command():
         assert "Your lucky number is:" in result.output
 ```
 
+### Dependency Validation
+
+`wireup.integration.click.setup(...)` validates command callbacks during setup.
+Missing dependencies and config values fail before commands are invoked.
+
+See [What Wireup Validates](../../what_wireup_validates.md) for the full rules.
+
 ### API Reference
 
 Visit [API Reference](../../class/click_integration.md) for detailed information about the Click integration module.

{wireup-2.9.0 → wireup-2.10.0}/docs/pages/integrations/django/index.md

@@ -2,7 +2,7 @@
 description: Django dependency injection with Wireup: a type-safe DI container for Django, DRF, and Ninja with setup, request/app injection patterns, testing, and troubleshooting.
 ---
 
-# :simple-django: Django Integration
+# :simple-django:{.color-django} Django Integration 
 
 <div class="grid cards annotate" markdown>
 
@@ -106,6 +106,16 @@ urlpatterns = [
 
 Run the app with `python manage.py runserver`, then open `http://127.0.0.1:8000/greet/?name=World`.
 
+## Dependency Validation
+
+When `auto_inject_views=True`, Wireup validates Django views during app setup.
+Missing dependencies and config values fail before requests are served.
+
+When you use `@inject` or `@inject_app` explicitly, validation happens when those callables are invoked,
+not as part of the root Django startup guarantee.
+
+See [What Wireup Validates](../../what_wireup_validates.md) for the full rules.
+
 ## Detailed Guides
 
 - [Django Setup and Installation](setup.md): installation, middleware placement, and settings/config integration.

{wireup-2.9.0 → wireup-2.10.0}/docs/pages/integrations/fastapi/background_tasks.md

@@ -4,6 +4,7 @@ Use `WireupTask` when you want Wireup to resolve dependencies inside a FastAPI b
 
 ## Usage
 
+1. Add `wireup.integration.fastapi` to your Wireup injectables.
 1. Define your task function with `Injected[...]` parameters for any Wireup dependencies
 1. Inject `WireupTask` in your route handler: `wireup_task: Injected[WireupTask]`
 1. Wrap the task function before scheduling: `wireup_task(write_greeting)`

{wireup-2.9.0 → wireup-2.10.0}/docs/pages/integrations/fastapi/index.md

@@ -2,7 +2,7 @@
 description: FastAPI dependency injection with Wireup: type-safe DI for routes, WebSockets, request-time injection, class-based handlers, and background tasks.
 ---
 
-# :simple-fastapi: FastAPI Integration
+# :simple-fastapi:{.color-fastapi} FastAPI Integration
 
 <div class="grid cards annotate" markdown>
 
@@ -86,6 +86,13 @@ Run the server with:
 fastapi dev main.py
 ```
 
+## Dependency Validation
+
+`wireup.integration.fastapi.setup(...)` validates route handlers up front.
+For regular route handlers, missing dependencies and config values fail during setup. For Class-based handlers, they fail during app startup.
+
+See [What Wireup Validates](../../what_wireup_validates.md) for the full rules.
+
 ## Detailed Guides
 
 - [Inject in Routes](inject_in_routes.md): HTTP/WebSocket handler injection and config value injection in route signatures.

{wireup-2.9.0 → wireup-2.10.0}/docs/pages/integrations/flask/index.md

@@ -104,6 +104,13 @@ See
 [Flask integration tests](https://github.com/maldoinc/wireup/blob/master/test/integration/flask/test_flask_integration.py)
 for more examples.
 
+### Dependency Validation
+
+`wireup.integration.flask.setup(...)` validates the views it wraps up front.
+Missing dependencies and config values fail during setup.
+
+See [What Wireup Validates](../../what_wireup_validates.md) for the full rules.
+
 ### API Reference
 
 - [flask_integration](../../class/flask_integration.md)

{wireup-2.9.0 → wireup-2.10.0}/docs/pages/integrations/starlette/background_tasks.md

@@ -4,6 +4,7 @@ Use `WireupTask` when you want Wireup to resolve dependencies inside a Starlette
 
 ## Usage
 
+1. Add `wireup.integration.starlette` to your Wireup injectables.
 1. Define your task function with `Injected[...]` parameters for any Wireup dependencies
 1. Inject `WireupTask` in your route handler: `wireup_task: Injected[WireupTask]`
 1. Wrap the task function before scheduling: `wireup_task(write_greeting)`

{wireup-2.9.0 → wireup-2.10.0}/docs/pages/integrations/typer/index.md

@@ -54,6 +54,13 @@ from wireup.integration.typer import get_app_container
 container = get_app_container(app)
 ```
 
+### Dependency Validation
+
+`wireup.integration.typer.setup(...)` validates command callbacks during setup.
+Missing dependencies and config values fail during setup.
+
+See [What Wireup Validates](../../what_wireup_validates.md) for the full rules.
+
 ### API Reference
 
 Visit [API Reference](../../class/typer_integration.md) for detailed information about the Typer integration module.

{wireup-2.9.0 → wireup-2.10.0}/docs/pages/lifetimes_and_scopes.md

@@ -261,7 +261,53 @@ async def main():
         await asyncio.gather(*tasks)
 ```
 
-Guidelines for what to share:
+Services resolved inside a child scope can also depend on the active scoped container directly:
+
+```python
+from wireup import ScopedAsyncContainer, injectable
+
+
+@injectable(lifetime="scoped")
+class WorkerService:
+    def __init__(
+        self, scope: ScopedAsyncContainer, request_ctx: RequestContext
+    ) -> None:
+        self.scope = scope
+        self.request_ctx = request_ctx
+```
+
+### Abstractions and Qualifiers
+
+When using abstractions via `as_type` or qualifiers, the provided keys must match the registered dependency keys. For example, if you have:
+
+```python
+@injectable(as_type=Cache)
+class RedisCache(Cache): ...
+```
+
+Then you must provide the instance using the `Cache` key, not `RedisCache`:
+
+```python
+provided = {
+    Cache: RedisCache(...),  # Use the abstraction key, not the concrete class
+}
+```
+
+With qualifiers, you must also include the qualifier in the key:
+
+```python
+@injectable(as_type=Cache, qualifier="in_memory")
+class InMemoryCache(Cache): ...
+```
+Then the provided key must include the qualifier:
+
+```python
+provided = {
+    wireup.qualified(Cache, "in_memory"): InMemoryCache(...),
+}
+```
+
+### Guidelines for what to share
 
 - Good candidates: `RequestContext`, tenant/account context, auth claims, correlation/tracing metadata, immutable per-request flags.
 - Usually avoid sharing: DB transactions, unit-of-work objects.

wireup-2.10.0/docs/pages/packaging_injectables.md

@@ -0,0 +1,108 @@
+Use this guide when you want to package and distribute injectables across applications, teams, or internal
+libraries. Wireup always receives a list of injectables, so the main choice is how your package exposes that
+list.
+
+## 1. Export A Module Or Package
+
+Use this when the injectables are fixed and the application does not need to choose between variants. 
+Wireup's own integrations use the same idea. For example, `wireup.integration.fastapi` is a module with injectables that can be passed directly in `injectables=[...]` and exposes FastAPI `Request`, `WebSocket`, and `WireupTask`.
+
+Example:
+
+```python title="team_name_sqlalchemy/__init__.py"
+@injectable
+def database_session() -> DatabaseSession: ...
+
+
+@injectable
+class UserRepository: ...
+```
+
+```python title="app.py"
+import wireup
+import team_name_sqlalchemy
+
+
+container = wireup.create_sync_container(
+    injectables=[team_name_sqlalchemy],
+)
+```
+
+This is the simplest option. It works well for internal packages and libraries with a single default setup.
+
+## 2. Export A List Of Injectables
+
+Use this when you want the package to export an explicit list of injectables instead of relying on module
+scanning.
+
+```python title="team_name_sqlalchemy/__init__.py"
+@injectable
+def database_session() -> DatabaseSession: ...
+
+
+@injectable
+class UserRepository: ...
+
+
+INJECTABLES = [database_session, UserRepository]
+```
+
+```python title="app.py"
+import wireup
+import team_name_sqlalchemy
+
+
+container = wireup.create_sync_container(
+    injectables=[*team_name_sqlalchemy.INJECTABLES],
+)
+```
+
+## 3. Export A Function That Returns Injectables
+
+Use this when the package exposes parameters of its own, such as backend choices or feature flags.
+
+```python title="team_name_sqlalchemy/__init__.py"
+from typing import Literal, Protocol
+
+from wireup import injectable
+
+
+class Cache(Protocol): ...
+
+
+@injectable(as_type=Cache)
+class RedisCache: ...
+
+
+@injectable(as_type=Cache)
+class MemcachedCache: ...
+
+
+def make_injectables(
+    *,
+    backend: Literal["redis", "memcached"],
+) -> list[object]:
+    if backend == "redis":
+        return [RedisCache]
+
+    return [MemcachedCache]
+```
+
+```python title="app.py"
+import wireup
+from team_name_sqlalchemy import make_injectables
+
+
+container = wireup.create_sync_container(
+    injectables=[*make_injectables(backend=settings.cache_backend)],
+)
+```
+
+For reusable provider-style bundles or registering the same subgraph more than once, see
+[Reusable Bundles](reusable_bundles.md).
+
+## Which One Should You Pick?
+
+- Use a module when the package has one setup and consumers do not need to choose between variants.
+- Use a list when you want explicit control over what gets registered without module scanning.
+- Use a function when the package exposes parameters that consumers must provide when building the injectables.

wireup-2.10.0/docs/pages/stylesheets/extra.css

@@ -0,0 +1,32 @@
+.md-header,
+.md-tabs {
+    background-color: #242b3f;
+}
+
+.md-typeset {
+    font-size: .7rem;
+}
+
+.highlight {
+    font-size: .75rem;
+}
+
+body[data-md-color-scheme="default"] .grid.cards>ul>li {
+    border: 1px solid #ddd !important;
+}
+
+body[data-md-color-scheme="slate"] .grid.cards>ul>li {
+    border: 1px solid var(--md-default-fg-color--lightest) !important;
+}
+
+.grid.cards>ul>li span.twemoji {
+    vertical-align: top !important;
+}
+
+.color-fastapi {
+    color: rgb(0, 148, 133) !important
+}
+
+.color-django {
+    color: #0C4B33 !important;
+}