Update documentation on injecting provided object attributes, items or method calls

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
 ------

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.

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
+You can inject provided object attribute, item or result of its method call.
-provider.
-
-It also describes how to call a method of the provided instance and use the result of
-this call as an injection value.
 
 .. 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
+attribute helps to specify what happens with the provided instance before the injection. You can
-value from:
+use any combination of the following:
 
-- an attribute of the provided instance
+- an attribute of the provided object
-- an item of the provided instance
+- an item of the provided object
-- a call of the provided instance method
+- 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
+The ``.provided`` attribute is available for the next providers:
-have ``.provided`` attribute:
 
-- :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::

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'

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,