That Depends

https://github.com/modern-python/that-depends
Admin
That Depends is a production-ready, async-first dependency injection framework for Python 3.10+ with...
Tokens:57,108
Snippets:546
Trust Score:9
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### Full example with lifecycle events

Source: https://github.com/modern-python/that-depends/blob/main/docs/integrations/faststream.md

Complete example showing a FastStream app with a RabbitBroker, a DIContainer with a resource and factory, a lifespan manager that tears down the container, and a subscriber that uses the dependency. The after_startup handler publishes a message to trigger the subscriber.

```python
import contextlib
import dataclasses
import datetime
import typing

from faststream import FastStream, Depends, Logger
from faststream.rabbit import RabbitBroker

from that_depends import BaseContainer, providers


async def create_async_resource() -> typing.AsyncIterator[datetime.datetime]:
    yield datetime.datetime.now(tz=datetime.timezone.utc)


@dataclasses.dataclass(kw_only=True, slots=True)
class DependentFactory:
    async_resource: datetime.datetime


class DIContainer(BaseContainer):
    async_resource = providers.Resource(create_async_resource)
    dependent_factory = providers.Factory(DependentFactory, async_resource=async_resource.cast)


@contextlib.asynccontextmanager
async def lifespan_manager() -> typing.AsyncIterator[None]:
    try:
        yield
    finally:
        await DIContainer.tear_down()


broker = RabbitBroker()
app = FastStream(broker, lifespan=lifespan_manager)


@broker.subscriber("in")
async def read_root(
    logger: Logger,
    some_dependency: typing.Annotated[
        DependentFactory,
        Depends(DIContainer.dependent_factory)
    ],
) -> datetime.datetime:
    startup_time = some_dependency.async_resource
    logger.info(startup_time)
    return startup_time


@app.after_startup
async def t() -> None:
    await broker.publish(None, "in")
```

--------------------------------

### Install that-depends with FastStream extra

Source: https://github.com/modern-python/that-depends/blob/main/docs/integrations/faststream.md

Installation command to get the FastStream integration for that-depends.

```shell
pip install that-depends[faststream]
```

--------------------------------

### Install that-depends with uv

Source: https://github.com/modern-python/that-depends/blob/main/docs/index.md

Add that-depends as a dependency using uv.

```bash
uv add that-depends
```

--------------------------------

### Resolve the provider

Source: https://github.com/modern-python/that-depends/blob/main/docs/introduction/tear-down.md

Resolves the Singleton provider by awaiting it. This is part of the quick-start example.

```python
await MyContainer.config()
```

--------------------------------

### Resolve asynchronously with .provider

Source: https://github.com/modern-python/that-depends/blob/main/docs/providers/factories.md

Shows how to use the .provider property to get a no-argument async function that can be awaited to resolve the resource. The example uses asyncio.run(main()) to execute the async main function.

```python
import asyncio

async def main():
    # Acquire the async resource by awaiting the provider property
    msg = await MyContainer.async_message.provider()
    print(msg)

asyncio.run(main())
```

--------------------------------

### Install that-depends with pip

Source: https://github.com/modern-python/that-depends/blob/main/README.md

Install the that-depends package using pip. This is the standard installation command for the framework.

```bash
pip install that-depends
```

--------------------------------

### List provider example

Source: https://github.com/modern-python/that-depends/blob/main/docs/providers/collections.md

Defines a container with a List provider that contains two Factory providers. Resolves to an immutable sequence of dependencies.

```python
import random
from that_depends import BaseContainer, providers


class DIContainer(BaseContainer):
    random_number = providers.Factory(random.random)
    numbers_sequence = providers.List(random_number, random_number)


DIContainer.numbers_sequence.resolve_sync()
# (0.3035656170071561, 0.8280498192037787)
```

--------------------------------

### Dict provider example

Source: https://github.com/modern-python/that-depends/blob/main/docs/providers/collections.md

Defines a container with a Dict provider that maps named keys to Factory providers. Resolves to a read-only mapping of dependencies.

```python
import random
from that_depends import BaseContainer, providers


class DIContainer(BaseContainer):
    random_number = providers.Factory(random.random)
    numbers_map = providers.Dict(key1=random_number, key2=random_number)


DIContainer.numbers_map.resolve_sync()
# mappingproxy({'key1': 0.6851384528299208, 'key2': 0.41044920948045294})
```

--------------------------------

### Define container and Singleton provider

Source: https://github.com/modern-python/that-depends/blob/main/docs/introduction/tear-down.md

Defines a container with a Singleton provider that returns a random value. This is the first step in the quick-start example.

```python
from that_depends import BaseContainer, providers
import random

class MyContainer(BaseContainer):
    config = providers.Singleton(lambda: random.random())
```

--------------------------------

### Install that-depends with FastAPI extra

Source: https://github.com/modern-python/that-depends/blob/main/docs/integrations/fastapi.md

Install the package with the fastapi extra using pip.

```bash
pip install that-depends[fastapi]
```

--------------------------------

### Force enter context with @Container.context(force=True)

Source: https://github.com/modern-python/that-depends/blob/main/docs/introduction/scopes.md

Use the context wrapper with force=True to force-enter a context for a container. The example shows a container with a ContextResource provider and an injected function that resolves the provider.

```python
class Container(BaseContainer):
    p = providers.ContextResource(my_resource).with_config(scope=ContextScopes.APP)
    
@Container.context(force=True)
@inject
async def injected(val = Provide[Container.p]):
   return val

await injected() # will resolve
```

--------------------------------

### Run FastAPI app with uvicorn

Source: https://github.com/modern-python/that-depends/blob/main/docs/integrations/fastapi.md

Starts the FastAPI application using uvicorn with the main:app module path and reload enabled. Run this from the directory containing main.py.

```bash
uvicorn main:app --reload
```

--------------------------------

### ThreadLocalSingleton provider example

Source: https://github.com/modern-python/that-depends/blob/main/docs/providers/singleton.md

Demonstrates using ThreadLocalSingleton to cache a separate instance per thread. The example shows that within a single thread, resolve_sync() returns the same cached value, while different threads get different values.

```python
import random
import threading
from that_depends.providers import ThreadLocalSingleton


def factory() -> int:
   """Return a random int between 1 and 100."""
   return random.randint(1, 100)


# ThreadLocalSingleton caches an instance per thread
singleton = ThreadLocalSingleton(factory)

# In a single thread:
instance1 = singleton.resolve_sync()  # e.g. 56
instance2 = singleton.resolve_sync()  # 56 (cached in the same thread)


# In multiple threads:
def thread_task():
   return singleton.resolve_sync()


thread1 = threading.Thread(target=thread_task)
thread2 = threading.Thread(target=thread_task)
thread1.start()
thread2.start()

# thread1 and thread2 each get a different cached value
```

--------------------------------

### Singleton concurrency safety example

Source: https://github.com/modern-python/that-depends/blob/main/docs/providers/singleton.md

Shows how Singleton ensures the factory is called only once when resolve() is used concurrently in async code and resolve_sync() in threaded code. Both async and threaded usage are demonstrated in one example.

```python
import threading
import asyncio


# In async code:
async def main():
   # calling resolve concurrently in different coroutines
   results = await asyncio.gather(
      MyContainer.singleton.resolve(),
      MyContainer.singleton.resolve(),
   )
   # Both results point to the same instance


# In threaded code:
def thread_task():
   instance = MyContainer.singleton.resolve_sync()
   ...


threads = [threading.Thread(target=thread_task) for _ in range(5)]
for t in threads:
   t.start()
```

--------------------------------

### Initialize State synchronously

Source: https://github.com/modern-python/that-depends/blob/main/docs/providers/state.md

Initialize the State provider with a value using the sync context manager. Resolve with resolve_sync() to get the value. If resolved without initialization, StateNotInitializedError is raised.

```python
with Container.my_state.init(42):
    print(Container.my_state.resolve_sync()) # 42

```

--------------------------------

### Use LazyProvider to reference a provider from another container

Source: https://github.com/modern-python/that-depends/blob/main/docs/experimental/lazy.md

Shows how to use LazyProvider to reference a provider from another container without importing it directly. The example resolves the lazy provider and gets the value 42.

```python
# second_container.py
from that_depends.experimental import LazyProvider
from that_depends import BaseContainer, providers
class SecondContainer(BaseContainer):
    lazy_value: LazyProvider[int] = LazyProvider("first_container.FirstContainer.value_provider")
    

with SecondContainer.lazy_value.context_sync(force=True):
    SecondContainer.lazy_value.resolve_sync() # 42
```

--------------------------------

### Override a nested provider in a that-depends container

Source: https://github.com/modern-python/that-depends/blob/main/docs/testing/provider-overriding.md

Complete example showing how to override the 'settings' provider with a local test database URL. The override affects the 'sqla_engine' and 'some_sqla_dao' providers because they depend on 'settings'. The example uses a Postgres test container, runs a query, and resets the override in a finally block.

```python
from pydantic_settings import BaseSettings
from sqlalchemy import create_engine, Engine, text
from testcontainers.postgres import PostgresContainer
from that_depends import BaseContainer, providers, Provide, inject


class SomeSQLADao:
    def __init__(self, *, sqla_engine: Engine):
        self.engine = sqla_engine
        self._connection = None

    def __enter__(self):
        self._connection = self.engine.connect()
        return self

    def __exit__(self, exc_type, exc_val, exc_tb):
        self._connection.close()

    def exec_query(self, query: str):
        return self._connection.execute(text(query))


class Settings(BaseSettings):
    db_url: str = 'some_production_db_url'


class DIContainer(BaseContainer):
    settings = providers.Singleton(Settings)
    sqla_engine = providers.Singleton(create_engine, settings.db_url)
    some_sqla_dao = providers.Factory(SomeSQLADao, sqla_engine=sqla_engine)


@inject
def exec_query_example(some_sqla_dao=Provide[DIContainer.some_sqla_dao]):
    with some_sqla_dao:
        result = some_sqla_dao.exec_query('SELECT 234')

    return next(result)


def main():
    pg_container = PostgresContainer(image='postgres:alpine3.19')
    pg_container.start()
    db_url = pg_container.get_connection_url()

    """
    We override only settings, but this override will also affect the 'sqla_engine' 
    and 'some_sqla_dao' providers because the 'settings' provider is used by them!
    """
    local_testing_settings = Settings(db_url=db_url)
    DIContainer.settings.override_sync(local_testing_settings)

    try:
        result = exec_query_example()
        assert result == (234,)
    finally:
        DIContainer.settings.reset_override_sync()
        pg_container.stop()


if __name__ == '__main__':
    main()

```

--------------------------------

### Initialize State asynchronously

Source: https://github.com/modern-python/that-depends/blob/main/docs/providers/state.md

Initialize the State provider with a value using the async context manager. Resolve with await resolve() to get the value. If resolved without initialization, StateNotInitializedError is raised.

```python

with Container.my_state.init(42):
    print(await Container.my_state.resolve()) # 42

```

--------------------------------

### Use ContextResource with container_context

Source: https://github.com/modern-python/that-depends/blob/main/docs/providers/factories.md

Shows how to use .provider_sync inside a container_context when the provider depends on a ContextResource with a named scope. The example uses ContextScopes.REQUEST and a session resource.

```python
import typing

from that_depends import BaseContainer, ContextScopes, container_context
from that_depends.providers import ContextResource, Factory


def create_session() -> typing.Iterator[str]:
    yield "session"


class ContextfulContainer(BaseContainer):
    default_scope = ContextScopes.REQUEST
    session = ContextResource(create_session)
    greeting = Factory(lambda session: f"Hello from {session}", session.cast)


with container_context(ContextfulContainer, scope=ContextScopes.REQUEST):
    result = ContextfulContainer.greeting.provider_sync()
```

--------------------------------

### Propagation example

Source: https://github.com/modern-python/that-depends/blob/main/docs/introduction/tear-down.md

Shows that tear_down() propagates to dependent providers. When B is torn down, A is also torn down, so a new resolution of A returns a different value.

```python
class MyContainer(BaseContainer):
    B = providers.Singleton(lambda: random.random())
    A = providers.Singleton(lambda x: x, B)

b = await MyContainer.B()
a = await MyContainer.A()

assert a == b

await MyContainer.B.tear_down()
a_new = await MyContainer.A()
assert a_new != a
```

--------------------------------

### Resolve synchronously with .provider_sync

Source: https://github.com/modern-python/that-depends/blob/main/docs/providers/factories.md

Shows how to use the .provider_sync property to get a no-argument synchronous callable that returns the resolved value. The output is shown as 'Hello from sync provider!'.

```python
# In a synchronous function or interactive session
>>> msg = MyContainer.sync_message.provider_sync
>>> print(msg())
Hello from sync provider!
```

--------------------------------

### Override multiple providers with override_providers_sync

Source: https://github.com/modern-python/that-depends/blob/main/docs/testing/provider-overriding.md

Replaces a single provider override with a dictionary of providers to override multiple at once. The example shows overriding the 'settings' provider with a local testing settings object, and includes a try/finally to stop the Postgres container.

```python
def main():
    pg_container = PostgresContainer(image='postgres:alpine3.19')
    pg_container.start()
    db_url = pg_container.get_connection_url()

    local_testing_settings = Settings(db_url=db_url)
    providers_for_overriding = {
        'settings': local_testing_settings,
        # more values...
    }
    with DIContainer.override_providers_sync(providers_for_overriding):
        try:
            result = exec_query_example()
            assert result == (234,)
        finally:
            pg_container.stop()
```

--------------------------------

### Force enter context with context_async

Source: https://github.com/modern-python/that-depends/blob/main/docs/introduction/scopes.md

Use context_async(force=True) to (re-)initialize a ContextResource outside its defined scope. The example shows that after forcing, the current scope is None and the resource can be resolved.

```python
p = providers.ContextResource(my_resource).with_config(scope=ContextScopes.APP)

async with p.context_async(force=True):
   assert get_current_scope() == None
   await p.resolve()  # will resolve
```

--------------------------------

### ContextResource injection failure example

Source: https://github.com/modern-python/that-depends/blob/main/docs/introduction/generator-injection.md

Attempts to inject a ContextResource provider into a generator with matching scope. This raises a ContextProviderError because context initialization is not allowed for generators.

```python
def sync_resource() -> typing.Iterator[float]:
    yield random.random() 

class Container(BaseContainer):
    sync_provider = providers.ContextResource(sync_resource).with_config(scope=ContextScopes.INJECT)
    dependent_provider = providers.Factory(lambda x: x, sync_provider.cast)

@inject(scope=ContextScopes.INJECT) # (1)!
def injected(val: float = Provide[Container.dependent_provider]) -> typing.Generator[float, None, None]:
    yield val 

# This will raise a `ContextProviderError`!
next(injected())
```

--------------------------------

### Provider selector using Pydantic-Settings

Source: https://github.com/modern-python/that-depends/blob/main/docs/providers/selector.md

Selects a provider based on a key from a Pydantic-Settings instance. The selector uses settings.cast.storage_backend to get the key.

```python
from typing import Literal
from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    storage_backend: Literal["local", "remote"] = "remote"

class DIContainer(BaseContainer):
    settings = providers.Singleton(Settings)
    selector = providers.Selector(
        settings.cast.storage_backend,
        local=providers.Factory(StorageServiceLocal),
        remote=providers.Factory(StorageServiceRemote),
    )
```

--------------------------------

### Contravariant binding example

Source: https://github.com/modern-python/that-depends/blob/main/docs/introduction/type-based-injection.md

Shows how to enable contravariant binding with `contravariant=True` in the `bind` method. The injected parameter is of type `A`, but receives an instance of `B` because `A` is a supertype of `B`.

```python
class A: ...

class B(A): ...

class Container(BaseContainer):
    my_provider = providers.Factory(lambda: B()).bind(B, contravariant=True)

@Container.inject
async def foo(v: A = Provide()) -> A: # (1)!
    return v
```

--------------------------------

### Define inner and outer containers with resource providers

Source: https://github.com/modern-python/that-depends/blob/main/docs/introduction/multiple-containers.md

Defines an InnerContainer with sync and async resource providers, and an OuterContainer that references those providers in a List provider. This setup requires manual lifecycle management of InnerContainer.

```python
import datetime
import typing

from that_depends import BaseContainer, providers


def create_sync_resource() -> typing.Iterator[datetime.datetime]:
    yield datetime.datetime.now(tz=datetime.timezone.utc)


async def create_async_resource() -> typing.AsyncIterator[datetime.datetime]:
    yield datetime.datetime.now(tz=datetime.timezone.utc)


class InnerContainer(BaseContainer):
    sync_resource = providers.Resource(create_sync_resource)
    async_resource = providers.Resource(create_async_resource)


class OuterContainer(BaseContainer):
    sequence = providers.List(InnerContainer.sync_resource, InnerContainer.async_resource)
```

--------------------------------

### Incompatible container_context() usage in 1.*

Source: https://github.com/modern-python/that-depends/blob/main/docs/migration/v2.md

Shows an example of an incompatibility with that-depends 1.*: entering container_context() without explicit arguments and importing MyContainer later, which causes an error when resolving a ContextResource.

```python
from that_depends import container_context

async def some_async_function():
    # Enter a new context but import `MyContainer` later
    async with container_context():
        from some_other_module import MyContainer
        # Attempt to resolve a `ContextResource` resource
        my_resource = await MyContainer.my_context_resource.async_resolve()  # ❌ Error!
```

--------------------------------

### FastAPI route using custom dependency and fetch_context_item

Source: https://github.com/modern-python/that-depends/blob/main/docs/integrations/fastapi.md

Define a FastAPI route that depends on the custom init_di_context dependency and uses a provider that fetches the request from the container context via fetch_context_item. This example shows how to access the request in a route without using DIContextMiddleware.

```python
# main.py (extended)
from fastapi import FastAPI, Request, Depends
from starlette.responses import JSONResponse
from that_depends import fetch_context_item

from request_deps import init_di_context
from mycontainer import MyContainer

app = FastAPI()

# Notice no DIContextMiddleware here, but you could combine them
@app.get("/request-based", dependencies=[Depends(init_di_context)])
async def get_request_info(
    # This provider fetches the request from context:
    request_in_container: Request = Depends(MyContainer.resolver(lambda: fetch_context_item("request"))),
):
    # The provider can read from that-depends context. We used .resolver(...) here as an example,
    # but you can define a dedicated provider in MyContainer that returns fetch_context_item("request").
    return JSONResponse({"request_url": str(request_in_container.url)})
```

--------------------------------

### Resolving a ContextResource after context initialization

Source: https://github.com/modern-python/that-depends/blob/main/docs/introduction/scopes.md

Once the context is initialized, the resource can be resolved regardless of the current scope. The example shows that resolving before initialization raises an exception, and that the resolved value remains the same across nested scopes.

```python
await p.resolve()  # will raise an exception

async with container_context(p, scope=ContextScopes.APP):
   val_1 = await p.resolve()  # will resolve
   async with container_context(scope=ContextScopes.REQUEST):
      val_2 = await p.resolve()  # will resolve
      assert val_1 == val_2  # but value stays the same since context is the same
```

--------------------------------

### Set up a dependency injection container with providers

Source: https://github.com/modern-python/that-depends/blob/main/docs/index.md

Creates a container class with a provider that uses the async resource creator.

```python
from that_depends import BaseContainer, providers

class Container(BaseContainer):
    provider = providers.Resource(create_async_resource)
```

--------------------------------

### Quick reference for context initialization methods

Source: https://github.com/modern-python/that-depends/blob/main/docs/providers/context-resources.md

Table comparing container_context(), SupportsContext explicit methods, and SupportsContext decorator for resetting contexts of providers and containers.

```python
| Intention                                             | Using `container_context()`                   | Using `SupportsContext` explicitly         | Using `SupportsContext` decorator |
|-------------------------------------------------------|-----------------------------------------------|--------------------------------------------|-----------------------------------|
| Reset a `provider.ContextResource` context            | `async with container_context(my_provider):`  | `async with my_provider.context_async():`  | `@my_provider.context`            |
| Reset a sync `provider.ContextResource` context       | `with container_context(my_provider):`        | `with my_provider.context_sync():`         | `@my_provider.context`            |
| Reset all resources in a container                   | `async with container_context(my_container):` | `async with my_container.context_async():` | `@my_container.context`           |
| Reset all sync resources in a container              | `with container_context(my_container):`       | `with my_container.context_sync():`        | `@my_container.context`           |
```

--------------------------------

### Initialize context and resolve ContextResource

Source: https://github.com/modern-python/that-depends/blob/main/docs/providers/context-resources.md

Shows how to enter a context for a container using container_context and resolve async and sync resources. Must enter the context before resolving, otherwise a RuntimeError occurs.

```python
async with container_context(MyContainer):  # this will initialize a new context for MyContainer
    await MyContainer.async_resource.resolve()  # "async resource"
    MyContainer.sync_resource.resolve_sync()          # "sync resource"
```

--------------------------------

### Use factories with parameters

Source: https://github.com/modern-python/that-depends/blob/main/docs/providers/factories.md

Shows how Factory can accept dependencies as parameters. The greeting factory depends on the name factory, and the output is 'Hello, Alice!'.

```python
def greet(name: str) -> str:
    return f"Hello, {name}!"

class MyContainer(BaseContainer):
    name = Factory(lambda: "Alice")
    greeting = Factory(greet, name)
```

```python
>>> greeting_sync_fn = MyContainer.greeting.provider_sync
>>> print(greeting_sync_fn())
Hello, Alice!
```

--------------------------------

### Manually resolve config and connection

Source: https://github.com/modern-python/that-depends/blob/main/docs/providers/singleton.md

Shows how to manually resolve the configuration synchronously and the database connection asynchronously.

```python
# Synchronously resolve the config
cfg = MyContainer.config.resolve_sync()

# Asynchronously resolve the DB connection
connection = await MyContainer.db_connection.resolve()
```

--------------------------------

### Build a dependency graph with providers (Singleton, Factory, cast)

Source: https://github.com/modern-python/that-depends/blob/main/docs/introduction/ioc-container.md

Demonstrates building a dependency graph inside a container. The config provider is a Singleton, session is a Factory that receives the config's db attribute, and user_repository depends on both config and session. The cast property on session changes its type to the creator's return type to prevent type errors.

```python
from that_depends import providers

class Container(BaseContainer):
    config = providers.Singleton(Config)
    session = providers.Factory(create_db_session, config=config.db) # (1)!
    
    user_repository = providers.Factory(
        UserRepository,
        config.users,
        session=session.cast, # (3)!
    ) # (2)!
```

--------------------------------

### Initialize global context with keyword argument (v2 style)

Source: https://github.com/modern-python/that-depends/blob/main/docs/migration/v2.md

Shows the new way of passing the initial context using the global_context keyword argument in v2.

```python
my_global_context = {"some_key": "some_value"}
async with container_context(global_context=my_global_context):
    assert fetch_context_item("some_key") == "some_value"
```

--------------------------------

### Replace init_async_resources with init_resources

Source: https://github.com/modern-python/that-depends/blob/main/docs/migration/v2.md

The method BaseContainer.init_async_resources() has been removed. Use BaseContainer.init_resources() instead. The first block shows a container class definition, the second shows the old call, and the third shows the new call.

```python
from that_depends import BaseContainer

class MyContainer(BaseContainer):
    # Define your providers here
    ...
```

```python
await MyContainer.init_async_resources()
```

```python
await MyContainer.init_resources()
```

--------------------------------

### Use a context manager class as a resource

Source: https://github.com/modern-python/that-depends/blob/main/docs/providers/resources.md

Shows how to use a standard context manager class with `Resource`. The `__enter__` and `__exit__` methods are called automatically on resolve and teardown.

```python
import typing
from that_depends.providers import Resource


class SyncFileManager:
    def __enter__(self) -> str:
        print("Opening file")
        return "/path/to/file"

    def __exit__(self, exc_type, exc_val, exc_tb):
        print("Closing file")


sync_file_resource = Resource(SyncFileManager)

# usage
file_path = sync_file_resource.resolve_sync()
print(file_path)
sync_file_resource.tear_down_sync()
```

--------------------------------

### Call the function

Source: https://github.com/modern-python/that-depends/blob/main/docs/introduction/injection.md

Calls greet_user() without arguments, which resolves the injected provider and prints the greeting.

```python
print(greet_user())  # "Greeting: Hello from MyContainer"
```

--------------------------------

### Get the database id of an issue

Source: https://github.com/modern-python/that-depends/blob/main/docs/agents/issue-tracker.md

Fetch the numeric database id of an issue using `gh api` and `jq` to extract the `.id` field.

```bash
gh api repos/<owner>/<repo>/issues/<n> --jq .id
```

--------------------------------

### Initialize container context

Source: https://github.com/modern-python/that-depends/blob/main/docs/integrations/fastapi.md

Pass arguments to create_fastapi_route_class() to initialize container context.

```python
from that_depends import ContextScopes

my_route_class = create_fastapi_route_class(MyContainer, global_context={"key": "value"}, scope=ContextScopes.REQUEST)
```

--------------------------------

### @inject default scope behavior

Source: https://github.com/modern-python/that-depends/blob/main/docs/introduction/scopes.md

Example showing that @inject does not enter the scope by default. The provider is resolved because it is a default argument, but get_current_scope() returns None.

```python
def iterator() -> typing.Iterator[float]:
    yield random.random()

class Container(BaseContainer):
    default_scope = ContextScopes.INJECT
    provider = providers.ContextResource(iterator)

@inject(scope=ContextScopes.INJECT)
def injected(v: int = Provide[Container.provider]) -> int:
    assert get_current_scope() == None # (1)!
    return v

injected()
```

--------------------------------

### Check current scope with get_current_scope()

Source: https://github.com/modern-python/that-depends/blob/main/docs/introduction/scopes.md

Use get_current_scope() inside a container_context block to verify the active scope. The example asserts that the current scope equals ContextScopes.APP.

```python
from that_depends.providers.context_resources import get_current_scope, ContextScopes

async with container_context(scope=ContextScopes.APP):
    assert get_current_scope() == ContextScopes.APP
```

--------------------------------

### Attach resources to a container

Source: https://github.com/modern-python/that-depends/blob/main/docs/providers/resources.md

Shows how to attach the sync and async resource creators to a container using the `Resource` provider.

```python
from that_depends import BaseContainer
from that_depends.providers import Resource

class MyContainer(BaseContainer):
    sync_resource = Resource(create_sync_resource)
    async_resource = Resource(create_async_resource)
```

--------------------------------

### Define container with Singleton provider and async factory

Source: https://github.com/modern-python/that-depends/blob/main/docs/providers/singleton.md

Defines a container `MyContainer` with a `Singleton` provider for `Settings` and an async factory for a database connection. The async factory `get_db_connection` is defined separately and uses the settings fields.

```python
from that_depends import BaseContainer, providers

async def get_db_connection(address: str, port: int, db_name: str):
    # e.g., create an async DB connection
    ...

class MyContainer(BaseContainer):
    # We'll parse settings only once
    config = providers.Singleton(Settings)

    # We'll pass the config's DB fields into an async factory for a DB connection
    db_connection = providers.AsyncFactory(
        get_db_connection,
        config.db.address,
        config.db.port,
        config.db.db_name,
    )
```

--------------------------------

### Sync tear-down raising CannotTearDownSyncError

Source: https://github.com/modern-python/that-depends/blob/main/docs/introduction/tear-down.md

Shows that tear_down_sync() raises CannotTearDownSyncError when dependent resources are async. The example defines an async resource and attempts sync tear-down.

```python
async def async_creator(val: float) -> typing.AsyncIterator[float]:
    yield val
    print("Finalization!")


class MyContainer(BaseContainer):
    B = providers.Singleton(lambda: random.random())
    A = providers.Resource(async_creator, B.cast)


b = await MyContainer.B()
a = await MyContainer.A()

MyContainer.B.tear_down_sync()  # raises
```

--------------------------------

### Inject provider by name with Provide["A.b.name"]

Source: https://github.com/modern-python/that-depends/blob/main/docs/introduction/string-injection.md

Shows how to inject a provider attribute by name using the Provide marker. The string format is Container.Provider[.attribute.attribute...]. Provide[] validates the format immediately and raises ValueError if invalid, but container/provider existence is checked only when the function is called.

```python
from that_depends import BaseContainer, inject, Provide

class Config(BaseSettings):
    name: str = "Damian"

class A(BaseContainer):
    b = providers.Factory(Config)

@inject
def read(val = Provide["A.b.name"]):
    return val

assert read() == "Damian"
```

--------------------------------

### Pass provider_sync callable to another class

Source: https://github.com/modern-python/that-depends/blob/main/docs/providers/factories.md

Demonstrates storing and passing the .provider_sync callable to another class. The AnotherClass constructor accepts a callable and calls it to get the message.

```python
class AnotherClass:
    def __init__(self, sync_factory_callable: callable):
        self._factory_callable = sync_factory_callable

    def get_message(self) -> str:
        return self._factory_callable()


# Passing MyContainer.sync_message.provider_sync to AnotherClass
provider_callable = MyContainer.sync_message.provider_sync
another_instance = AnotherClass(provider_callable)
print(another_instance.get_message())  # "Hello from sync provider!"
```

--------------------------------

### Read a pull request with comments and diff

Source: https://github.com/modern-python/that-depends/blob/main/docs/agents/issue-tracker.md

Use `gh pr view` with `--comments` to view a PR and its comments, and `gh pr diff` to get the diff.

```bash
gh pr view <number> --comments
```

```bash
gh pr diff <number>
```

--------------------------------

### Explicitly pass resources to container_context()

Source: https://github.com/modern-python/that-depends/blob/main/docs/migration/v2.md

Shows how to avoid entering container_context() without arguments by passing all resources supporting context initialization explicitly. This is recommended to prevent unexpected behavior and improve performance.

```python
from that_depends import container_context

MyContainer: BaseContainer
my_context_resource_provider: ContextResource

async with container_context(MyContainer, my_context_resource_provider):
 # Resolve resources
 my_container_instance = MyContainer.my_context_resource.sync_resolve()
 my_provider_instance = my_context_resource_provider.sync_resolve()
```

--------------------------------

### State.init

Source: https://github.com/modern-python/that-depends/blob/main/docs/providers/state.md

Initializes the state provider with a value within a context. The value is available for resolution within the context and can be nested.

```APIDOC
## State.init

### Description
Initializes the state provider with a value within a context. The value is available for resolution within the context and can be nested.

### Method
Context manager

### Usage
```python
with Container.my_state.init(value):
    # resolve state
```

### Parameters
- **value** (Any) - Required - The value to store in the state provider.

### Behavior
- The state provider resolves to the last initialized value within nested contexts.
- Resolving without initialization raises `StateNotInitializedError`.

### Example
```python
with Container.my_state.init(42):
    print(await Container.my_state.resolve())  # 42
```
```

--------------------------------

### ContextResource injection success example

Source: https://github.com/modern-python/that-depends/blob/main/docs/introduction/generator-injection.md

Shows that generator injection works when the context does not need to be initialized. The @inject scope does not match the provider's scope, and the context is set up externally.

```python
def sync_resource() -> typing.Iterator[float]:
    yield random.random() 

class Container(BaseContainer):
    sync_provider = providers.ContextResource(sync_resource).with_config(scope=ContextScopes.REQUEST)
    dependent_provider = providers.Factory(lambda x: x, sync_provider.cast)

@inject(scope=ContextScopes.INJECT) # (1)!
def injected(val: float = Provide[Container.dependent_provider]) -> typing.Generator[float, None, None]:
    yield val 


with container_context(scope=ContextScopes.REQUEST):
    # This will resolve as expected
    next(injected())
```

--------------------------------

### Create LazyProvider with separate module and provider strings

Source: https://github.com/modern-python/that-depends/blob/main/docs/experimental/lazy.md

Creates a LazyProvider using separate strings for the module and the provider attribute path. Alternative to the single import string approach.

```python
from that_depends.experimental import LazyProvider

lazy_p = LazyProvider(module_string="my.module", provider_string="attribute.path")
```

--------------------------------

### container_context (context manager)

Source: https://github.com/modern-python/that-depends/blob/main/docs/providers/context-resources.md

Initializes a global context using the container_context context manager. Within the scope, you can fetch context items by key.

```APIDOC
## container_context (context manager)

### Description
Initializes a global context using the `container_context` context manager. Within the scope, you can fetch context items by key.

### Usage
```python
from that_depends import container_context, fetch_context_item

async with container_context(global_context={"key": "value"}):
    # run some code
    fetch_context_item("key")  # returns 'value'
```

### Parameters
- `global_context` (dict) - Required - A dictionary of key-value pairs to store in the global context.

### Notes
- The values are accessible only within the scope of the context manager.
- Initializing a new context without `preserve_global_context=True` will reset the global context.
```

--------------------------------

### FastAPI app with DIContextMiddleware in main.py

Source: https://github.com/modern-python/that-depends/blob/main/docs/integrations/fastapi.md

Sets up a FastAPI app with DIContextMiddleware, optionally passing a container and global_context. The route uses Depends(MyContainer.current_time) to inject a provider. Requires a mycontainer module with MyContainer and its current_time provider.

```python
# main.py
from fastapi import FastAPI, Depends
from starlette.responses import Response
from that_depends.providers import DIContextMiddleware

from mycontainer import MyContainer

app = FastAPI()

# Attach the middleware, optionally passing the container and/or a global_context
app.add_middleware(
    DIContextMiddleware,
    MyContainer,
    global_context={"app_name": "MyApp"},  # optional dictionary available in the context
)

@app.get("/")
def get_time(
    # Using container's provider as a dependency:
    current_time: str = Depends(MyContainer.current_time)
) -> Response:
    return Response(
        content=f"Current time is: {current_time}",
        media_type="text/plain",
    )
```

--------------------------------

### Resolve and tear down resources synchronously and asynchronously

Source: https://github.com/modern-python/that-depends/blob/main/docs/providers/resources.md

Demonstrates explicit resolution and teardown for both sync and async resources. `resolve_sync()` and `resolve()` create the instance if needed; `tear_down_sync()` and `tear_down()` run the teardown logic and reset the cache.

```python
# Synchronous resource usage
value_sync = MyContainer.sync_resource.resolve_sync()
print(value_sync)  # "sync resource"
MyContainer.sync_resource.tear_down_sync()

# Asynchronous resource usage
import asyncio


async def main():
    value_async = await MyContainer.async_resource.resolve()
    print(value_async)  # "async resource"
    await MyContainer.async_resource.tear_down()


asyncio.run(main())
```

--------------------------------

### Define a container and a provider

Source: https://github.com/modern-python/that-depends/blob/main/docs/introduction/injection.md

Creates a BaseContainer subclass with a Singleton provider that returns a greeting string.

```python
from that_depends import BaseContainer
from that_depends.providers import Singleton

class MyContainer(BaseContainer):
    greeting_provider = Singleton(lambda: "Hello from MyContainer")
```

--------------------------------

### @inject with enter_scope=True

Source: https://github.com/modern-python/that-depends/blob/main/docs/introduction/scopes.md

Shows how to enter the scope for the duration of the function by setting enter_scope=True. This initializes context for all matching providers, allowing resolution.

```python
class Container(BaseContainer):
    default_scope = ContextScopes.INJECT
    provider = providers.ContextResource(iterator).with_config(scope=ContextScopes.INJECT)
    another_provider = providers.ContextResource(iterator).with_config(scope=ContextScopes.INJECT)

@inject(scope=ContextScopes.INJECT, enter_scope=True)
def injected(v: int = Provide[Container.provider]) -> int:
    assert get_current_scope() == ContextScopes.INJECT
    Container.another_provider.resolve_sync() # (1)!
    return v
```

--------------------------------

### Enter sync context with container_context

Source: https://github.com/modern-python/that-depends/blob/main/docs/providers/context-resources.md

container_context also implements ContextManager, allowing with. A sync context only allows resolution of sync dependencies.

```python
with container_context(MyContainer):
    ...
```

--------------------------------

### Create LazyProvider with single import string

Source: https://github.com/modern-python/that-depends/blob/main/docs/experimental/lazy.md

Creates a LazyProvider using a single string that specifies the full path to the provider. Useful for referencing providers without importing them directly.

```python
from that_depends.experimental import LazyProvider

lazy_p = LazyProvider("my.module.attribute.path")
```

--------------------------------

### Fixed string selector for testing

Source: https://github.com/modern-python/that-depends/blob/main/docs/providers/selector.md

Uses a fixed string key 'local' to always select the local provider. Useful for quick testing.

```python
class DIContainer(BaseContainer):
    selector = providers.Selector(
        "local",
        local=providers.Factory(StorageServiceLocal),
        remote=providers.Factory(StorageServiceRemote),
    )
```

--------------------------------

### Dependency injection with router class and string provider

Source: https://github.com/modern-python/that-depends/blob/main/docs/integrations/fastapi.md

Use Provide with a string provider to inject a dependency in a FastAPI endpoint.

```python
from that_depends import Provide

@router.get("/time")
async def get_time(current_time: datetime.datetime = Provide["MyContainer.current_time"]) -> datetime.datetime:
    return current_time
```

--------------------------------

### Create a custom router class

Source: https://github.com/modern-python/that-depends/blob/main/docs/integrations/fastapi.md

Create a custom route class using create_fastapi_route_class().

```python
from that_depends.integrations.fastapi import create_fastapi_route_class

my_route_class = create_fastapi_route_class()
```

--------------------------------

### Replace AsyncResource with Resource

Source: https://github.com/modern-python/that-depends/blob/main/docs/migration/v2.md

The AsyncResource class has been removed. Use providers.Resource instead. The first block shows the old import and usage, the second shows the new import and usage.

```python
from that_depends.providers import AsyncResource
my_provider = AsyncResource(some_async_function)
```

```python
from that_depends.providers import Resource
my_provider = Resource(some_async_function)
```

--------------------------------

### Reset all container contexts with reset_all_containers=True

Source: https://github.com/modern-python/that-depends/blob/main/docs/migration/v2.md

Shows how to reset the context for all ContextResource instances in addition to setting a global context. Note that this only reinitializes resources defined within containers.

```python
async with container_context(global_context=my_global_context, reset_all_containers=True):
   assert fetch_context_item("some_key") == "some_value"
```

--------------------------------

### Resolve dependencies in your code

Source: https://github.com/modern-python/that-depends/blob/main/docs/index.md

Resolves the provider by awaiting it directly.

```python
await Container.provider()
```

--------------------------------

### Scan for agent skills with skilly

Source: https://github.com/modern-python/that-depends/blob/main/docs/index.md

Runs skilly to scan for available agent skills.

```shell
uvx skilly scan
```

--------------------------------

### Dependency injection with router class

Source: https://github.com/modern-python/that-depends/blob/main/docs/integrations/fastapi.md

Use Provide with a provider to inject a dependency in a FastAPI endpoint.

```python
from that_depends import Provide

@router.get("/time")
async def get_time(current_time: datetime.datetime = Provide[MyContainer.current_time]) -> datetime.datetime:
    return current_time
```

--------------------------------

### Use DIContextMiddleware with RabbitBroker

Source: https://github.com/modern-python/that-depends/blob/main/docs/integrations/faststream.md

Shows how to add DIContextMiddleware to the broker's middlewares to initialize context resources. The scope is set to ContextScopes.REQUEST.

```python
from that_depends.integrations.faststream import DIContextMiddleware
from that_depends import ContextScopes
from faststream.rabbit import  RabbitBroker

broker = RabbitBroker(middlewares=[DIContextMiddleware(Container, scope=ContextScopes.REQUEST)])
```

--------------------------------

### Initialize global context with container_context

Source: https://github.com/modern-python/that-depends/blob/main/docs/providers/context-resources.md

Use `container_context` as an async context manager to set a global context. Within the scope, `fetch_context_item` retrieves the value by key.

```python
from that_depends import container_context, fetch_context_item

async with container_context(global_context={"key": "value"}):
    # run some code
    fetch_context_item("key")  # returns 'value'
```

--------------------------------

### Inject values with @inject decorator

Source: https://github.com/modern-python/that-depends/blob/main/docs/providers/singleton.md

Shows how to inject the database connection into a function using the `@inject` decorator and the `Provide` placeholder.

```python
from that_depends import inject, Provide

@inject
async def with_db_connection(conn = Provide[MyContainer.db_connection]):
    # conn is the created DB connection
    ...
```

--------------------------------

### Define and resolve an Object provider

Source: https://github.com/modern-python/that-depends/blob/main/docs/providers/object.md

Creates a container with an Object provider that returns the integer 1, and asserts that resolve_sync() returns 1.

```python
from that_depends import BaseContainer, providers


class DIContainer(BaseContainer):
    object_provider = providers.Object(1)


assert DIContainer.object_provider.resolve_sync() == 1
```

--------------------------------

### Singleton provider usage with sync and async resolution and injection

Source: https://github.com/modern-python/that-depends/blob/main/docs/providers/singleton.md

Defines a container with a Singleton provider and demonstrates synchronous and asynchronous resolution, caching behavior, and injection using the @inject decorator.

```python
import random

from that_depends import BaseContainer, Provide, inject, providers


def some_function() -> float:
   """Generate number between 0.0 and 1.0"""
   return random.random()


# define container with `Singleton` provider:
class MyContainer(BaseContainer):
   singleton = providers.Singleton(some_function)


# The provider will call `some_function` once and cache the return value

# 1) Synchronous resolution
MyContainer.singleton.resolve_sync()  # e.g. 0.3
MyContainer.singleton.resolve_sync()  # 0.3 (cached)

# 2) Asynchronous resolution
await MyContainer.singleton.resolve()  # 0.3 (same cached value)


# 3) Injection example
@inject
async def with_singleton(number: float = Provide[MyContainer.singleton]):
   # number == 0.3
   ...
```

--------------------------------

### Callable selector using os.getenv

Source: https://github.com/modern-python/that-depends/blob/main/docs/providers/selector.md

Selects a provider based on the STORAGE_BACKEND environment variable, defaulting to 'local'. The selector is a lambda that returns a string key.

```python
import os
from typing import Protocol
from that_depends import BaseContainer, providers

class StorageService(Protocol):
    ...

class StorageServiceLocal(StorageService):
    ...

class StorageServiceRemote(StorageService):
    ...

class DIContainer(BaseContainer):
    storage_service = providers.Selector(
        lambda: os.getenv("STORAGE_BACKEND", "local"),
        local=providers.Factory(StorageServiceLocal),
        remote=providers.Factory(StorageServiceRemote),
    )
```

--------------------------------

### Create a wayfinder map issue

Source: https://github.com/modern-python/that-depends/blob/main/docs/agents/issue-tracker.md

Create a single issue labelled `wayfinder:map` to hold the map body.

```bash
gh issue create --label wayfinder:map
```

--------------------------------

### Enter async context with container_context

Source: https://github.com/modern-python/that-depends/blob/main/docs/providers/context-resources.md

container_context implements AsyncContextManager, allowing async with. An async context allows resolution of both sync and async dependencies.

```python
async with container_context(MyContainer):
    ...
```

--------------------------------

### List open GitHub issues with JSON and jq

Source: https://github.com/modern-python/that-depends/blob/main/docs/agents/issue-tracker.md

List open issues with `gh issue list`, outputting JSON with selected fields and using `jq` to transform the data. Use `--label` and `--state` filters as needed.

```bash
gh issue list --state open --json number,title,body,labels,comments --jq '[.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]'
```

--------------------------------

### Define sync and async providers in a container

Source: https://github.com/modern-python/that-depends/blob/main/docs/providers/factories.md

Shows how to define a BaseContainer subclass with a sync Factory and an async AsyncFactory. The sync_message provider calls a plain function, while async_message calls an async function.

```python
from that_depends import BaseContainer
from that_depends.providers import Factory, AsyncFactory

def build_sync_message() -> str:
    return "Hello from sync provider!"

async def build_async_message() -> str:
    # Possibly perform async setup, I/O, etc.
    return "Hello from async provider!"

class MyContainer(BaseContainer):
    # Synchronous Factory
    sync_message = Factory(build_sync_message)

    # Asynchronous Factory
    async_message = AsyncFactory(build_async_message)
```

--------------------------------

### Create a custom ContextScope

Source: https://github.com/modern-python/that-depends/blob/main/docs/introduction/scopes.md

Creates a custom scope by instantiating ContextScope with a string identifier. Use this when the default scopes do not fit your needs.

```python
from that_depends.providers.context_resources import ContextScope

CUSTOM = ContextScope("CUSTOM")
```

--------------------------------

### Inject async function with Provide default

Source: https://github.com/modern-python/that-depends/blob/main/docs/introduction/injection.md

Use @inject on an async function. The greeting parameter uses Provide[MyContainer.greeting_provider] as its default. Async providers cannot be injected into sync functions.

```python
@inject
async def async_greet_user(greeting: str = Provide[MyContainer.greeting_provider]) -> str:
    # asynchronous operations...
    return f"Greeting: {greeting}"
```

--------------------------------

### Create a container with a provider

Source: https://github.com/modern-python/that-depends/blob/main/docs/integrations/fastapi.md

Define a container with a provider that creates a datetime object.

```python
# mycontainer.py
import datetime

from that_depends import BaseContainer, providers

def create_time() -> datetime.datetime:
    """Example sync resource creator."""
    return datetime.datetime.now()

class MyContainer(BaseContainer):
    # A simple provider that always returns a "datetime.datetime" object
    current_time = providers.Factory(create_time)
```

--------------------------------

### Container alias with Provide["C.b.name"]

Source: https://github.com/modern-python/that-depends/blob/main/docs/introduction/string-injection.md

Demonstrates using a container alias to replace the container name in the Provide string. After setting alias = "C", the original container name 'A' can no longer be used.

```python
class A(BaseContainer):
    alias = "C" # replaces the container name.
    b = providers.Factory(Config)

@inject
def read(val = Provide["C.b.name"]): # `A` can no longer be used.
    return val

assert read() == "Damian"
```

--------------------------------

### Inject the provider into a function

Source: https://github.com/modern-python/that-depends/blob/main/docs/introduction/injection.md

Decorates greet_user with @inject and uses Provide[MyContainer.greeting_provider] as the default value for the greeting parameter.

```python
from that_depends import inject, Provide

@inject
def greet_user(greeting: str = Provide[MyContainer.greeting_provider]) -> str:
    return f"Greeting: {greeting}"
```

--------------------------------

### provider.override_sync(value) in 3.*

Source: https://github.com/modern-python/that-depends/blob/main/docs/migration/v3.md

In 3.*, use .override_sync() for synchronous overriding. Similar changes apply to .override_context_sync() and .reset_override_sync().

```python
provider.override_sync(value)
```

--------------------------------

### Initialize global context with positional argument (v1 style)

Source: https://github.com/modern-python/that-depends/blob/main/docs/migration/v2.md

Shows the old way of passing a dictionary to container_context() as a positional argument. This is no longer supported in v2.

```python
my_global_context = {"some_key": "some_value"}
async with container_context(my_global_context):
    assert fetch_context_item("some_key") == "some_value"
```

--------------------------------

### Define a container by subclassing BaseContainer

Source: https://github.com/modern-python/that-depends/blob/main/docs/introduction/ioc-container.md

Shows the minimal structure for defining a container. Subclass BaseContainer and define providers as class attributes. The ellipsis (...) is a placeholder for the actual provider definitions.

```python
from that_depends import BaseContainer

class Container(BaseContainer):
    # define your providers here
    ...
```

--------------------------------

### Retrieve global context item by type

Source: https://github.com/modern-python/that-depends/blob/main/docs/providers/context-resources.md

Use `fetch_context_item_by_type` to retrieve the first item of a given type from the global context. Note: only the first matching item is returned if multiple candidates exist.

```python
from that_depends import fetch_context_item_by_type
with container_context(global_context={"key": 4}):
    fetch_context_item_by_type(int) # returns 4
```

--------------------------------

### Initialize context for a specific resource

Source: https://github.com/modern-python/that-depends/blob/main/docs/providers/context-resources.md

Using container_context with a specific resource initializes a new context for that resource only.

```python
# this will init a new context for the specific resource only.
async with container_context(MyContainer.async_resource):
    ...
```
Tokens:
Raw