--- title: utils | CodeWeaver Docs description: API reference for codeweaver.core.di.utils url: "https://docs.knitli.com/api/core/di/utils" type: static generatedAt: "2026-04-17T17:21:08.003Z" --- # utils [Open in ChatGPT](https://chatgpt.com/?q=Read%20https%3A%2F%2Fdocs.knitli.com%2Fcodeweaver%2Fapi%2Fcore%2Fdi%2Futils%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%2Futils%2F.%20I%20want%20to%20ask%20questions%20about%20it.)[View in Markdown](/codeweaver/api/core/di/utils.md) [Share on LinkedIn](https://www.linkedin.com/sharing/share-offsite/?url=https%3A%2F%2Fdocs.knitli.com%2Fcodeweaver%2Fapi%2Fcore%2Fdi%2Futils%2F)[Share on X](https://x.com/intent/tweet?url=https%3A%2F%2Fdocs.knitli.com%2Fcodeweaver%2Fapi%2Fcore%2Fdi%2Futils%2F&text=utils)[Share on Threads](https://threads.net/intent/post?url=https%3A%2F%2Fdocs.knitli.com%2Fcodeweaver%2Fapi%2Fcore%2Fdi%2Futils%2F&text=utils)[Share on Bluesky](https://bsky.app/intent/compose?text=utils%20https%3A%2F%2Fdocs.knitli.com%2Fcodeweaver%2Fapi%2Fcore%2Fdi%2Futils%2F)[Share on Facebook](https://www.facebook.com/sharer/sharer.php?u=https%3A%2F%2Fdocs.knitli.com%2Fcodeweaver%2Fapi%2Fcore%2Fdi%2Futils%2F)[Share on Reddit](https://reddit.com/submit?url=https%3A%2F%2Fdocs.knitli.com%2Fcodeweaver%2Fapi%2Fcore%2Fdi%2Futils%2F&title=utils)[Share on Hacker News](https://news.ycombinator.com/submitlink?u=https%3A%2F%2Fdocs.knitli.com%2Fcodeweaver%2Fapi%2Fcore%2Fdi%2Futils%2F&t=utils)[Share on Email](mailto:?subject=utils&body=https%3A%2F%2Fdocs.knitli.com%2Fcodeweaver%2Fapi%2Fcore%2Fdi%2Futils%2F)[Share on WhatsApp](https://wa.me/?text=utils%20https%3A%2F%2Fdocs.knitli.com%2Fcodeweaver%2Fapi%2Fcore%2Fdi%2Futils%2F)[Share on Telegram](https://t.me/share/url?url=https%3A%2F%2Fdocs.knitli.com%2Fcodeweaver%2Fapi%2Fcore%2Fdi%2Futils%2F&text=utils) # `codeweaver.core.di.utils` [Section titled “codeweaver.core.di.utils”](#codeweavercorediutils) Utility functions for CodeWeaver’s dependency injection (DI) system. This module provides a lightweight registry for dependency providers. It allows registering factory functions or classes that provide instances of specific types, and retrieving them later. This is a fundamental building block for the application’s dependency injection architecture. ## Class: `ProviderMetadata` [Section titled “Class: ProviderMetadata”](#class-providermetadata) Metadata about a registered provider. Attributes: scope: The lifecycle scope (singleton, request, or function) is_generator: Whether the provider is a generator function (for cleanup) is_async_generator: Whether the provider is an async generator (for cleanup) module: Optional module name for scoped registration tags: Optional tags for categorizing providers (e.g. “backup”) ### Method: `from_provider` [Section titled “Method: from_provider”](#method-from_provider) ** ``` from_provider() ``` Create ProviderMetadata from a factory function. Args: scope: The lifecycle scope. factory: The provider function or class. module: Optional module name. tags: Optional tags. Returns: An instance of ProviderMetadata. ## Function: `dependency_provider` [Section titled “Function: dependency_provider”](#function-dependency_provider) ** ``` dependency_provider() ``` Decorator that registers a function or class as the provider for a specific type. This decorator binds a factory function (or class) to the type it produces. When the DI system needs an instance of `cls`, it will use the decorated function or class to create it. Supports three usage patterns in sync and async contexts: 1. Function registration (explicit type): ** ``` dependency_provider(MyService, scope="singleton") async def create_my_service() -> MyService: return MyService() ``` 1. Class registration (self-registration): Note: In this case, the class *must* implement **call**. ** ``` dependency_provider(scope="request") class MyService: def __init__(self, config: Config): self.config = config ``` 1. Collection registration (returns multiple instances): ** ``` dependency_provider(MyCapability, scope="singleton", collection=True) def get_capabilities() -> Sequence[MyCapability]: return (MyCapability(...), MyCapability(...)) ``` Args: cls: The type (class) that the decorated function provides. scope: The lifecycle scope - “singleton” (app lifetime, default), “request” (per request), or “function” (per call, no caching). module: Optional module name for scoped registration. tags: Optional tags for categorizing providers. collection: If True, the factory returns a Sequence[T] instead of T. Use this when registering a provider that returns multiple instances. Returns: When used as `dependency_provider(SomeType)`: Returns a decorator function. When used as `dependency_provider` on a class: Returns the class unchanged. Example: ** ``` # Singleton factory functiondependency_provider(DatabaseConnection, scope="singleton") async def get_db() -> DatabaseConnection: return DatabaseConnection() # Request-scoped servicedependency_provider(RequestContext, scope="request") async def get_context() -> RequestContext: return RequestContext() # Function-scoped (no caching)dependency_provider(TempFile, scope="function") async def create_temp() -> TempFile: return TempFile() # Generator with cleanupdependency_provider(ResourcePool, scope="singleton") async def get_pool() -> AsyncIterator[ResourcePool]: pool = ResourcePool() await pool.connect() yield pool await pool.disconnect() # Class self-registration (no cls argument)dependency_provider(scope="singleton") class SimpleService: def __init__(self): self.value = 42 # Collection provider (returns multiple instances)dependency_provider(Capability, scope="singleton", collection=True) def get_all_capabilities() -> Sequence[Capability]: return ( Capability(name="feature1"), Capability(name="feature2"), Capability(name="feature3"), ) ``` ## Function: `get_all_provider_metadata` [Section titled “Function: get_all_provider_metadata”](#function-get_all_provider_metadata) ** ``` get_all_provider_metadata() ``` Retrieve metadata for all registered providers. Returns: A dictionary mapping types to lists of ProviderMetadata. Each type may have multiple providers registered with different tags. ## Function: `get_all_providers` [Section titled “Function: get_all_providers”](#function-get_all_providers) ** ``` get_all_providers() ``` Retrieve all registered providers with their metadata. Returns: A dictionary mapping types to lists of (factory, metadata) tuples. Each type may have multiple providers registered with different tags. ## Function: `get_provider` [Section titled “Function: get_provider”](#function-get_provider) ** ``` get_provider() ``` Retrieve a registered provider function for a specific type, optionally filtered by tags. Args: cls: The type for which to retrieve the provider. tags: Optional set of tags to filter providers. If provided, only returns providers that have ALL specified tags. Returns: The callable (factory function or class) registered to provide instances of `cls`. If multiple providers match the tags, returns the last registered one. Raises: KeyError: If no provider has been registered for the given type, or no provider matches the specified tags. ## Function: `get_provider_metadata` [Section titled “Function: get_provider_metadata”](#function-get_provider_metadata) ** ``` get_provider_metadata() ``` Retrieve metadata for a registered provider, optionally filtered by tags. Args: cls: The type for which to retrieve metadata. tags: Optional set of tags to filter providers. If provided, returns metadata for the provider that has ALL specified tags. Returns: The ProviderMetadata for the given type, or None if not registered. If multiple providers match the tags, returns the last registered one. ## Function: `is_provider_registered` [Section titled “Function: is_provider_registered”](#function-is_provider_registered) ** ``` is_provider_registered() ``` Check if a provider is registered for a specific type, optionally filtered by tags. Args: cls: The type to check for a registered provider. tags: Optional set of tags to filter providers. If provided, checks if any provider has ALL specified tags. Returns: True if a provider is registered for the given type (and matches tags if specified), False otherwise.