[Question] What does the @inject decorator do?

Hi I am playing around with the dependency_injector library and I am trying to find out what the @inject decorator does. I have tried this sample program with and without the @inject decorator and noticed no difference. Is the @inject decorate necessary?

import sys
import uuid

from dependency_injector import containers, providers
from dependency_injector.wiring import inject, Provide


class Service:
    def __init__(self):
        self.uuid = uuid.uuid4()


class Container(containers.DeclarativeContainer):

    service = providers.Factory(Service)


@inject # Commenting this out has no effect on the program
def main(service: Service = Provide[Container.service]) -> None:
    print(service.uuid)


if __name__ == '__main__':
    container = Container()
    container.wire(modules=[sys.modules[__name__]])

    main()

[rmk135]

Hi @ecs-jnguyen ,

That’s a very good question. My pleasure to provide an explanation.

Decorator @inject registers functions and methods in wiring module.

Why that’s needed? The answer is in how wiring works. Wiring introspects a module and looks for any functions or methods that have Provide markers. That works fine, but there are some cases when it’s impossible to introspect properly.

Case 1 is closures:

def foo():
    @inject
    def bar(x = Provide[...]):  # no way to reach it with introspection
        ...

Case 2 is replacing class decorators. The example of this is click library. Its decorator is class-based. This class based decorator hides the actual callable in the internals. No guarantee that it can be introspected:

@click.command()
@click.option('-c', '--configuration-file', help='Configuration file path', default='config.yml')
@click.argument('test_key')
@inject  # Registers it in wiring module before the reference is masked by click class
def cli(test_key, configuration_file, config: Config = Provider[Container.config]) -> None:
    ...

print(type(cli))  # Output: <class 'click.core.Command'>

Case 3 is memorizing decorator. This is typical for web and api frameworks when defining the routes. Framework decorator memorizes a reference to the function before the wiring happens. Even when wiring passes later, other framework keeps reference to pre-wiring-decorated callable:

from fastapi import APIRouter, Depends

router = APIRouter()


@router.get('/', response_model=Response)
@inject  # Registers it in wiring module before router has memorized pre-decorated function
async def index(
        query: Optional[str] = None,
        limit: Optional[str] = None,
        default_query: str = Depends(Provide[Container.config.default.query]),
        default_limit: int = Depends(Provide[Container.config.default.limit.as_int()]),
        search_service: SearchService = Depends(Provide[Container.search_service]),
):
    ...

Early versions of the Dependency Injector 4 didn’t have @inject decorator. It worked fine when framework could introspect. I’ve added @inject after discovered cases above. To not confuse people with the rules, I recommend to use @inject all the time. It gives a guarantee that wiring will find the markers.

[ecs-jnguyen]

@rmk135 Thanks for getting back to me. using the ‘string’ identifiers should help. Hopefully i don’t run into any circular dependencies lol