dishka

dishka is a dependency injection (DI) framework designed to manage object lifespans through a flexible scoping system. It provides an Inversion of Control (IoC) container that focuses exclusively on DI without requiring custom markers or decorators in your business logic.

Key capabilities include:

• Custom Scopes: Define object lifespans for the entire application, specific requests, or any arbitrary level in between.
• Finalization: Built-in support for releasing dependencies (e.g., closing database connections) when their scope ends.
• Modular Providers: Organize factories into small, reusable classes rather than large monolithic functions.
• Clean Code: Dependencies are resolved without cluttering code with global variables or library-specific specifiers.
• Performance: Optimized for speed, often outperforming other DI alternatives.

A Provider is an object used to define how dependencies are constructed. It contains factories and other entities that are then used to create a Container. Providers allow for modularity, as you can combine multiple providers in a single application.

To use a Provider, you can either:

1. Create an instance and use its .provide() method.
2. Inherit from Provider and use decorators or class attributes.

Once a Provider is configured, pass it to make_container() to create the dependency container.

from dishka import make_container, Provider, Scope

# Instance-based configuration
provider = Provider(scope=Scope.APP)
provider.provide(some_factory_function)
container = make_container(provider)

An Inversion of Control (IoC) container is a specialized object or framework that automates the creation of dependencies following specific rules and manages their lifetime (scopes).

While you can perform DI manually (e.g., by writing a custom Container class), an IoC-container is a useful helper for large-scale applications to:

• Automate complex factory logic.
• Ensure thread-safety in concurrent applications.
• Enforce lifetime rules (e.g., ensuring a database connection is unique per request but shared within that request).

dishka is an implementation of an IoC-container designed to handle these requirements.

Dishka supports modular dependency injection through several mechanisms:

• Reusable Parts: Containers can be assembled from reusable parts at runtime within a local scope.
• Isolation: Different parts of a container can be isolated so they do not affect each other, while still providing an explicit API to interact if required.
• Multiple Containers: It is possible to maintain multiple containers within the same codebase for different purposes.

Dishka is designed to work with both multithreading and asyncio environments.

• Async Support: If the container is configured to run in an asyncio environment, dependency creation using async functions is supported.
• Concurrency Models: The type of concurrency model can be configured during container creation. This ensures that concurrent entrance of scopes does not violate the requirement of providing a single instance of a dependency.
• Performance Tuning: Users can switch synchronization on or off to tune performance based on their specific concurrency needs.

While you can use standard scopes, two specific scopes are often used for advanced patterns:

• RUNTIME scope: Useful for dependencies that need to persist between tests that recreate applications. You can enter this scope explicitly by passing start_scope=Scope.RUNTIME to make_container.
• SESSION scope: Useful for managing connection-related objects in long-lived connections like WebSockets, where the HTTP-request handler would otherwise go straight into the shorter-lived REQUEST scope.

# Explicitly starting at RUNTIME
container = make_container(provider, start_scope=Scope.RUNTIME)
with container() as app_container:
    # RUNTIME -> APP
    pass

Providers are collections of factories used to set up your objects. You can define dependencies in several ways:

1. Using the Provider class: You can use .provide() to register classes or specific implementations.
2. Using the @provide decorator: You can decorate methods within a Provider subclass. The method's type hints determine what it creates and what dependencies it requires. All method parameters are treated as dependencies.
3. Custom Factory with Finalization: Using a generator (yield) within a @provide method allows you to perform cleanup (e.g., closing a database connection) when the scope is exited.

Example of overriding a provider's default scope:

service_provider = Provider(scope=Scope.REQUEST)
service_provider.provide(Service)
service_provider.provide(APIClient, scope=Scope.APP)  # APIClient will live for the APP lifetime instead

Components are isolated groups of providers within a single container, identified by a string name. This allows you to provide the same type with different meanings (e.g., two different database connections) without needing to create unique types like NewType for each.

Key characteristics:

• There is always a default component (represented by an empty string "").
• Providers are isolated: a provider cannot implicitly request an object from a different component.
• To retrieve an object from a specific component, you must explicitly specify the component name when calling container.get().

If a type is provided in multiple components, dishka searches only within the same component as the dependent, unless a cross-component link is explicitly declared.