diff --git a/docs/providers/factory.rst b/docs/providers/factory.rst index 19999aaa..af45fc5a 100644 --- a/docs/providers/factory.rst +++ b/docs/providers/factory.rst @@ -30,22 +30,50 @@ injected following these rules: :language: python :lines: 3- -Passing dependencies to the underlying providers -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Passing arguments to the underlying providers +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``Factory`` provider can pass the arguments to the underlying providers. This helps when you need +to assemble a nested objects graph and pass the arguments deep inside. + +Consider the example: .. image:: images/factory_init_injections_underlying.png -You can use :py:class:`Factory` provider to build complex object graphs. +To create an ``Algorithm`` you need to provide all the dependencies: ``ClassificationTask``, +``Loss``, and ``Regularizer``. The last object in the chain, the ``Regularizer`` has a dependency +on the ``alpha`` value. The ``alpha`` value varies from algorithm to algorithm: -Consider next example: +.. code-block:: python -.. literalinclude:: ../../examples/providers/factory_deep_init_injections.py + Algorithm( + task=ClassificationTask( + loss=Loss( + regularizer=Regularizer( + alpha=alpha, # <-- the dependency + ), + ), + ), + ) + + +``Factory`` provider helps to deal with the such assembly. You need to create the factories for +all the classes and use special double-underscore ``__`` syntax for passing the ``alpha`` argument: + +.. literalinclude:: ../../examples/providers/factory_init_injections_underlying.py :language: python + :lines: 3- + :emphasize-lines: 24-35,39,42,45 -.. note:: +When you use ``__`` separator in the name of the keyword argument the ``Factory`` looks for +the dependency with the same name as the left part of the ``__`` expression. - You can use ``__`` separator in the name of the keyword argument to pass the value to the child - factory, e.g. ``algorithm_factory(task__loss__regularizer__alpha=0.5)``. +.. code-block:: + + __= + +If ```` is found the underlying provider will receive the +``=`` as an argument. .. _factory_providers_delegation: diff --git a/examples/providers/factory_deep_init_injections.py b/examples/providers/factory_init_injections_underlying.py similarity index 85% rename from examples/providers/factory_deep_init_injections.py rename to examples/providers/factory_init_injections_underlying.py index 3791b906..98a386a7 100644 --- a/examples/providers/factory_deep_init_injections.py +++ b/examples/providers/factory_init_injections_underlying.py @@ -4,22 +4,22 @@ from dependency_injector import providers class Regularizer: - def __init__(self, alpha): + def __init__(self, alpha: float): self.alpha = alpha class Loss: - def __init__(self, regularizer): + def __init__(self, regularizer: Regularizer): self.regularizer = regularizer class ClassificationTask: - def __init__(self, loss): + def __init__(self, loss: Loss): self.loss = loss class Algorithm: - def __init__(self, task): + def __init__(self, task: ClassificationTask): self.task = task