From aeace8cba51d7f57bab3e8aaa155bf2c2cc4a0f8 Mon Sep 17 00:00:00 2001 From: Roman Mogylatov Date: Wed, 2 Sep 2020 17:59:31 -0400 Subject: [PATCH] Update documentation on injecting provided object attributes, items or method calls --- docs/main/changelog.rst | 1 + docs/providers/overriding.rst | 2 +- docs/providers/provided_instance.rst | 46 ++++++++----------- examples/providers/provided_instance.py | 1 + .../providers/provided_instance_complex.py | 1 + 5 files changed, 22 insertions(+), 29 deletions(-) diff --git a/docs/main/changelog.rst b/docs/main/changelog.rst index 2170edba..f9da42f0 100644 --- a/docs/main/changelog.rst +++ b/docs/main/changelog.rst @@ -10,6 +10,7 @@ follows `Semantic versioning`_ Development version ------------------- - Update providers overriding documentation and rework examples. +- Update documentation on injecting provided object attributes, items or method calls. 3.35.1 ------ diff --git a/docs/providers/overriding.rst b/docs/providers/overriding.rst index a8c4b006..23effd80 100644 --- a/docs/providers/overriding.rst +++ b/docs/providers/overriding.rst @@ -10,7 +10,7 @@ Provider overriding .. currentmodule:: dependency_injector.providers -Any provider can be overridden by another provider. +You can override any provider by another provider. When provider is overridden it calls to the overriding provider instead of providing the object by its own. diff --git a/docs/providers/provided_instance.rst b/docs/providers/provided_instance.rst index f19fdddd..cee70a9c 100644 --- a/docs/providers/provided_instance.rst +++ b/docs/providers/provided_instance.rst @@ -1,13 +1,14 @@ -Injecting attributes, items, or call methods of the provided instance -===================================================================== +Injecting provided object attributes, items, or call its methods +================================================================ + +.. meta:: + :keywords: Python,DI,Dependency injection,IoC,Inversion of Control,Attribute,Method,Call + :description: This page demonstrates how to inject attributes, items or call method of the + provided instance. .. currentmodule:: dependency_injector.providers -In this section you will know how to inject provided instance attribute or item into the other -provider. - -It also describes how to call a method of the provided instance and use the result of -this call as an injection value. +You can inject provided object attribute, item or result of its method call. .. literalinclude:: ../../examples/providers/provided_instance.py :language: python @@ -15,14 +16,14 @@ this call as an injection value. :lines: 3- To use the feature you should use the ``.provided`` attribute of the injected provider. This -attribute helps to specify what happens with the provided instance. You can retrieve an injection -value from: +attribute helps to specify what happens with the provided instance before the injection. You can +use any combination of the following: -- an attribute of the provided instance -- an item of the provided instance -- a call of the provided instance method +- an attribute of the provided object +- an item of the provided object +- a call of the provided object method -When you use the call of the provided instance method you can specify the injections into this +When you use a call of the provided instance method you can specify the injections for this method like you do with any other provider. You can do nested constructions: @@ -32,35 +33,24 @@ You can do nested constructions: :emphasize-lines: 24-30 :lines: 3- -Attribute ``.provided`` is available for the providers that return instances. Providers that -have ``.provided`` attribute: +The ``.provided`` attribute is available for the next providers: -- :py:class:`Callable` and its subclasses - :py:class:`Factory` and its subclasses - :py:class:`Singleton` and its subclasses +- :py:class:`Callable` and its subclasses - :py:class:`Object` - :py:class:`List` - :py:class:`Selector` - :py:class:`Dependency` -Special providers like :py:class:`Configuration` or :py:class:`Delegate` do not have the -``.provided`` attribute. - -Provider subclasses -------------------- - When you create a new provider subclass and want to implement the ``.provided`` attribute, you -should use the :py:class:`ProvidedInstance` provider. +should use the :py:class:`ProvidedInstance` provider. Add the ``.provided`` property +implementation to a new subclass: .. code-block:: python @property def provided(self): - """Return :py:class:`ProvidedInstance` provider.""" return ProvidedInstance(self) -In all other cases you should not use :py:class:`ProvidedInstance`, :py:class:`AttributeGetter`, -:py:class:`ItemGetter`, or :py:class:`MethodCaller` providers directly. Use the ``.provided`` -attribute of the injected provider instead. - .. disqus:: diff --git a/examples/providers/provided_instance.py b/examples/providers/provided_instance.py index 2e538120..e61f9bb7 100644 --- a/examples/providers/provided_instance.py +++ b/examples/providers/provided_instance.py @@ -33,6 +33,7 @@ client_factory = providers.Factory( value4=service.provided.get_value.call(), ) + if __name__ == '__main__': client = client_factory() assert client.value1 == client.value2 == client.value3 == 'foo' diff --git a/examples/providers/provided_instance_complex.py b/examples/providers/provided_instance_complex.py index 0e5ea107..20381f9b 100644 --- a/examples/providers/provided_instance_complex.py +++ b/examples/providers/provided_instance_complex.py @@ -31,6 +31,7 @@ demo_list = providers.List( dependency.provided['foo']['baz'].call(service)['arg'].get_value.call(), ) + if __name__ == '__main__': assert demo_list() == [ 10,