--- title: container | CodeWeaver Docs description: API reference for codeweaver.core.di.container url: "https://docs.knitli.com/api/core/di/container" type: static generatedAt: "2026-04-17T17:21:07.986Z" --- # container [Open in ChatGPT](https://chatgpt.com/?q=Read%20https%3A%2F%2Fdocs.knitli.com%2Fcodeweaver%2Fapi%2Fcore%2Fdi%2Fcontainer%2F.%20I%20want%20to%20ask%20questions%20about%20it.)[Open in Claude](https://claude.ai/new?q=Read%20https%3A%2F%2Fdocs.knitli.com%2Fcodeweaver%2Fapi%2Fcore%2Fdi%2Fcontainer%2F.%20I%20want%20to%20ask%20questions%20about%20it.)[View in Markdown](/codeweaver/api/core/di/container.md) [Share on LinkedIn](https://www.linkedin.com/sharing/share-offsite/?url=https%3A%2F%2Fdocs.knitli.com%2Fcodeweaver%2Fapi%2Fcore%2Fdi%2Fcontainer%2F)[Share on X](https://x.com/intent/tweet?url=https%3A%2F%2Fdocs.knitli.com%2Fcodeweaver%2Fapi%2Fcore%2Fdi%2Fcontainer%2F&text=container)[Share on Threads](https://threads.net/intent/post?url=https%3A%2F%2Fdocs.knitli.com%2Fcodeweaver%2Fapi%2Fcore%2Fdi%2Fcontainer%2F&text=container)[Share on Bluesky](https://bsky.app/intent/compose?text=container%20https%3A%2F%2Fdocs.knitli.com%2Fcodeweaver%2Fapi%2Fcore%2Fdi%2Fcontainer%2F)[Share on Facebook](https://www.facebook.com/sharer/sharer.php?u=https%3A%2F%2Fdocs.knitli.com%2Fcodeweaver%2Fapi%2Fcore%2Fdi%2Fcontainer%2F)[Share on Reddit](https://reddit.com/submit?url=https%3A%2F%2Fdocs.knitli.com%2Fcodeweaver%2Fapi%2Fcore%2Fdi%2Fcontainer%2F&title=container)[Share on Hacker News](https://news.ycombinator.com/submitlink?u=https%3A%2F%2Fdocs.knitli.com%2Fcodeweaver%2Fapi%2Fcore%2Fdi%2Fcontainer%2F&t=container)[Share on Email](mailto:?subject=container&body=https%3A%2F%2Fdocs.knitli.com%2Fcodeweaver%2Fapi%2Fcore%2Fdi%2Fcontainer%2F)[Share on WhatsApp](https://wa.me/?text=container%20https%3A%2F%2Fdocs.knitli.com%2Fcodeweaver%2Fapi%2Fcore%2Fdi%2Fcontainer%2F)[Share on Telegram](https://t.me/share/url?url=https%3A%2F%2Fdocs.knitli.com%2Fcodeweaver%2Fapi%2Fcore%2Fdi%2Fcontainer%2F&text=container) # `codeweaver.core.di.container` [Section titled “codeweaver.core.di.container”](#codeweavercoredicontainer) Central dependency container for CodeWeaver. ## Class: `Container` [Section titled “Class: Container”](#class-container) Dependency container for managing component lifecycles and resolution. Supports: - Factory and singleton registration - Recursive dependency resolution via Depends markers - Testing overrides - Async startup/shutdown hooks - Auto-discovery of providers via dependency_provider decorator ### Method: `add_shutdown_hook` [Section titled “Method: add_shutdown_hook”](#method-add_shutdown_hook) ** ``` add_shutdown_hook() ``` Add a shutdown hook. ### Method: `add_startup_hook` [Section titled “Method: add_startup_hook”](#method-add_startup_hook) ** ``` add_startup_hook() ``` Add a startup hook. ### Method: `clear` [Section titled “Method: clear”](#method-clear) ** ``` clear() ``` Clear all registered dependencies and state. ### Method: `clear_overrides` [Section titled “Method: clear_overrides”](#method-clear_overrides) ** ``` clear_overrides() ``` Clear all registered overrides. ### Method: `clear_request_cache` [Section titled “Method: clear_request_cache”](#method-clear_request_cache) ** ``` clear_request_cache() ``` Clear the request-scoped dependency cache. Should be called at the end of each request to clean up request-scoped instances. ### Method: `lifespan` [Section titled “Method: lifespan”](#method-lifespan) ** ``` lifespan() ``` Context manager for container lifecycle with cleanup support. Usage: async with container.lifespan(): # Container ready with cleanup tracking [Section titled “Container ready with cleanup tracking”](#container-ready-with-cleanup-tracking) instance = await container.resolve(SomeType) # All generators cleaned up [Section titled “All generators cleaned up”](#all-generators-cleaned-up) ### Method: `override` [Section titled “Method: override”](#method-override) ** ``` override() ``` Override a dependency, primarily for testing. Args: interface: The type to override. instance: The instance or factory to use instead. ### Method: `register` [Section titled “Method: register”](#method-register) ** ``` register() ``` Register a dependency. Args: interface: The type or interface to register. factory: The factory function or class. If None, the interface itself is used. singleton: Whether to cache the instance. tags: Optional tags to categorize this provider. scope: Optional scope (singleton, request, function). If not provided, inferred from singleton flag. ### Method: `reset_state` [Section titled “Method: reset_state”](#method-reset_state) ** ``` reset_state() ``` Reset container state for testing, keeping auto-discovered providers. Clears singletons, overrides, hooks, and request cache, but preserves the factory registry and the providers_loaded flag to avoid expensive re-discovery cycles in unit tests. ### Method: `resolve` [Section titled “Method: resolve”](#method-resolve) ** ``` resolve() ``` Resolve a dependency with circular dependency detection. Args: interface: The type to resolve. _resolution_stack: Internal parameter for tracking resolution chain. DO NOT pass this manually - it’s managed automatically. tags: Optional tags to filter providers. If provided, resolves the provider that has ALL specified tags. Returns: The resolved instance. Raises: CircularDependencyError: If a circular dependency is detected. ### Method: `use_overrides` [Section titled “Method: use_overrides”](#method-use_overrides) ** ``` use_overrides() ``` Context manager to temporarily apply multiple overrides. Args: overrides: A dictionary mapping interfaces to their override instances/factories. Yields: The container instance with overrides applied. ## Class: `ResolutionResult` [Section titled “Class: ResolutionResult”](#class-resolutionresult) Result of dependency resolution with error tracking. Used when collect_errors=True to aggregate multiple dependency resolution errors instead of failing fast on the first error. Attributes: values: Successfully resolved parameter values by name errors: List of dependency injection errors encountered ## Function: `get_container` [Section titled “Function: get_container”](#function-get_container) ** ``` get_container() ``` Get or create the global default container. On first call, this will: 1. Create a new Container instance 1. Load providers from dependency_provider decorator registry (lazy, on first resolve) Returns: The global container instance. ## Function: `reset_container` [Section titled “Function: reset_container”](#function-reset_container) ** ``` reset_container() ``` Reset the global default container. ## Function: `reset_container_state` [Section titled “Function: reset_container_state”](#function-reset_container_state) ** ``` reset_container_state() ``` Reset the global container state (singletons/overrides) for testing. Unlike `reset_container()`, this does not clear auto-discovered factories, making it much faster for test suites that need clean state but don’t need to reload the entire provider ecosystem.