Lagom Dependency Injection

By default, every time a dependency is referenced within a ContextContainer invocation, a new instance is created and a separate cleanup is scheduled.

If you need multiple dependencies to share the same instance during a single invocation (for example, a single database transaction shared by multiple classes), define that type as a context_singleton when initializing the ContextContainer.

Use the context_singletons argument in ContextContainer to ensure only one instance is created per invocation and cleanup happens only once.

# Define a transaction that needs to be shared
@context_dependency_definition(container)
def _get_a_transaction() -> Iterator[Transaction]:
    transaction = Transaction()
    try:
        yield transaction
    finally:
        transaction.commit()

# Configure the ContextContainer with context_singletons
context_container = ContextContainer(
    container, 
    context_types=[], 
    context_singletons=[Transaction]
)

# Both 'a' and 'b' will receive the same Transaction instance
@bind_to_container(context_container)
def do_something(a: A = injectable, b: B = injectable):
    print("do something")

When you need multiple instances of a single type (e.g., a primary database and a read replica), you can control which instance is injected using either Explicit Definitions or Subtyping.

Approach 1: Explicit Definitions

This is the simplest method and requires minimal changes to your existing codebase. You manually tell the Container how to construct each class by providing a lambda or factory function that specifies the correct arguments.

Approach 2: Subtyping

This approach involves creating subclasses for each specific instance type (e.g., PrimaryDb and ReadReplica inheriting from Database). You then update your domain code to type hint the specific subclass instead of the base class. This method is more explicit, follows standard Python patterns, and allows IDEs and static analysis tools to correctly identify dependencies.

# Approach 1: Explicit Definitions
from lagom import Container
container = Container()
container[QueryService] = lambda: QueryService(Database("read-replica-connection-string"))
container[DataWriter] = lambda: DataWriter(Database("primary-connection-string"))

# Approach 2: Subtyping
class PrimaryDb(Database):
    pass

class ReadReplica(Database):
    pass

container[ReadReplica] = lambda: ReadReplica("read-replica-connection-string")
container[PrimaryDb] = lambda: PrimaryDb("primary-connection-string")

class QueryService:
    def __init__(self, db: ReadReplica):
        pass

Lagom uses Python type hints to automatically resolve and inject dependencies. By registering types (or classes) into a Container, you can request high-level objects, and Lagom will recursively instantiate all required dependencies based on their type annotations.

To use Lagom:

1. Define your application classes and their dependencies using type hints.
2. Create a Container instance.
3. Register specific values (like configuration strings or URLs) using their type as the key.
4. Register implementation classes for abstract interfaces.
5. Retrieve the top-level object from the container.

from typing import NewType
from abc import ABC
from lagom import Container

# 1. Define types and classes
DiceApiUrl = NewType("DiceApiUrl", str)

class DiceClient(ABC):
    pass

class HttpDiceClient(DiceClient):
    def __init__(self, url: DiceApiUrl, limiting: RateLimitingConfig):
        ...

class Game:
    def __init__(self, dice_roller: DiceClient):
        ...

# 2. Setup Container
container = Container()

# 3. Register specific values/types
container[DiceApiUrl] = DiceApiUrl("https://roll.diceapi.com")

# 4. Register implementations for interfaces
container[DiceClient] = HttpDiceClient

# 5. Resolve the target object
game = container[Game]

To define dependencies that are singletons for the lifetime of a request and require cleanup (using Python context managers), pass a list of types to the request_context_singletons argument in FastApiIntegration.

Lagom looks for a ContextManager[T] in the container to satisfy a dependency of type T. You can define these in the container in two ways:

1. Using a generator with @context_dependency_definition
2. Using an existing Python Context Manager class

# Option 1: Generator with decorator
@context_dependency_definition(container)
def my_constructor() -> Iterator[SomeResource]:
    try:
        yield SomeResource()
    finally
        # Cleanup logic here
        pass

# Option 2: Existing Context Manager class
class SomeResourceManager:
    def __enter__(self):
        return SomeResource()
    def __exit__(self, exc_type, exc_val, exc_tb):
        # Cleanup logic here
        pass

container[ContextManager[SomeResource]] = SomeResourceManager

# Setup integration
deps = FastApiIntegration(container, request_context_singletons=[SomeClass])