@inject decorator - what is it for?

[hoou]

Hey, we found out that even if we omit the @Inject decorator before the function definition, dependencies injection still works.
So what is it for exactly? Can't find any specific information about this in docs, it just tells us to always use it. But why?

Here is an example code that works for me:

import sys

from dependency_injector import containers, providers, wiring

class Service:
    def __init__(self):
        print("service created")

    def do_something(self):
        print("something")

class Container(containers.DeclarativeContainer):
    serv = providers.Singleton(Service)

# no inject <============================================
def f(s = wiring.Provide[Container.serv]):
    s.do_something()
    print(id(s))


def main():
    container = Container()
    container.wire(modules=[sys.modules[__name__]])
    f()
    f()
    f()


if __name__ == '__main__':
    main()

[rmk135]

Hey @hoou , that's a good question. I already got one over here #404 (comment). Quoting my answer here:

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.