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

Author: rmk135

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,28 +1,29 @@
-Injecting attributes, items, or call methods of the provided instance
-=====================================================================
+Injecting provided object attributes, items, or call its methods
+================================================================
 
-.. currentmodule:: dependency_injector.providers
+.. 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.
 
-In this section you will know how to inject provided instance attribute or item into the other
-provider.
+.. currentmodule:: dependency_injector.providers
 
-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
  :emphasize-lines: 26-32
  :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::

examples/providers/provided_instance.py

@@ -33,6 +33,7 @@ def __init__(self, value1, value2, value3, value4):
  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 @@ def get_value(self):
  dependency.provided['foo']['baz'].call(service)['arg'].get_value.call(),
 )
 
+
 if __name__ == '__main__':
  assert demo_list() == [
  10,