diff --git a/docs/advanced_usage/index.rst b/docs/advanced_usage/index.rst index c2133e63..2548e27e 100644 --- a/docs/advanced_usage/index.rst +++ b/docs/advanced_usage/index.rst @@ -7,28 +7,35 @@ Current section of documentation describes advanced usage of @inject decorator ----------------- -``@di.inject()`` decorator can be used for making *inline* dependency +.. module:: dependency_injector.injections + +:py:func:`inject` decorator is a part of +:py:mod:`dependency_injector.injections` module. + +:py:func:`inject` decorator can be used for making *inline* dependency injections. It *patches* decorated callable in such way that dependency injection will be done during every call of decorated callable. -``di.inject()`` takes a various number of positional and keyword arguments +:py:func:`inject` takes a various number of positional and keyword arguments that are used as decorated callable injections. Every time, when -``di.inject()`` is called, positional and keyword argument injections would be -passed as an callable arguments. +:py:func:`inject` is called, positional and keyword argument injections would +be passed as an callable arguments. Such behaviour is very similar to the standard Python ``functools.partial`` object, except of one thing: all injectable values are provided -*"as is"*, except of providers (subclasses of ``di.Provider``). Providers +*"as is"*, except of providers (subclasses of +:py:class:`dependency_injector.providers.Provider`). Providers will be called every time, when injection needs to be done. For example, -if injectable value of injection is a ``di.Factory``, it will provide new one +if injectable value of injection is a +:py:class:`dependency_injector.providers.Factory`, it will provide new one instance (as a result of its call) every time, when injection needs to be done. -``di.inject()`` behaviour with context positional and keyword arguments is +:py:func:`inject` behaviour with context positional and keyword arguments is very like a standard Python ``functools.partial``: -- Positional context arguments will be appended after ``di.inject()`` +- Positional context arguments will be appended after :py:func:`inject` positional injections. -- Keyword context arguments have priority on ``di.inject()`` keyword +- Keyword context arguments have priority on :py:func:`inject` keyword injections and will be merged over them. Example: @@ -36,7 +43,7 @@ Example: .. literalinclude:: ../../examples/advanced_usage/inject_simple.py :language: python -Example of usage ``@di.inject()`` decorator with Flask: +Example of usage :py:func:`inject` decorator with Flask: .. literalinclude:: ../../examples/advanced_usage/inject_flask.py :language: python @@ -45,11 +52,12 @@ Example of usage ``@di.inject()`` decorator with Flask: @inject decorator with classes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -``@di.inject()`` could be applied for classes. In such case, it will look for +:py:func:`inject` could be applied for classes. In such case, it will look for class ``__init__()`` method and pass injection to it. If decorated class has -no ``__init__()`` method, appropriate ``di.Error`` will be raised. +no ``__init__()`` method, appropriate +:py:exc:`dependency_injector.errors.Error` will be raised. -Example of usage ``@di.inject()`` with Flask class-based view: +Example of usage :py:func:`inject` with Flask class-based view: .. literalinclude:: ../../examples/advanced_usage/inject_flask_class_based.py :language: python