Update callable provider docs

+ Add providers class diagram

dependency_injector/providers/callable.py

@@ -15,9 +15,6 @@ from dependency_injector.errors import Error
 class Callable(Provider):
     r""":py:class:`Callable` provider calls wrapped callable on every call.
 
-    :py:class:`Callable` provider provides callable that is called on every
-    provider call with some predefined dependency injections.
-
     :py:class:`Callable` supports positional and keyword argument injections:
 
     .. code-block:: python

docs/api/providers.rst

@@ -1,6 +1,10 @@
 ``dependency_injector.providers``
 ---------------------------------
 
+.. image:: /images/providers/providers_class_diagram.png
+    :width: 100%
+    :align: center
+
 .. automodule:: dependency_injector.providers
    :members:
    :inherited-members:

docs/providers/callable.rst

@@ -3,37 +3,26 @@ Callable providers
 
 .. currentmodule:: dependency_injector.providers
 
-:py:class:`Callable` provider is a provider that wraps particular callable with
+:py:class:`Callable` provider calls wrapped callable on every call.
-some injections. Every call of this provider returns result of call of initial
-callable.
 
 Callable providers and injections
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-:py:class:`Callable` takes a various number of positional and keyword 
+:py:class:`Callable` provider takes a various number of positional and keyword 
-arguments that are used as decorated callable injections. Every time, when 
+arguments that are used as wrapped callable injections. Every time, when 
-:py:class:`Callable` is called, positional and keyword argument injections 
+:py:class:`Callable` provider is called, positional and keyword argument 
-would be passed as an callable arguments.
+injections would be passed as an callable arguments.
 
-Such behaviour is very similar to the standard Python ``functools.partial`` 
+Injections are done according to the next rules:
-object with several more things: 
 
 + All providers (instances of :py:class:`Provider`) are called every time 
   when injection needs to be done.
 + Providers could be injected "as is" (delegated), if it is defined obviously.
-  Check out `Callable providers delegation`_.
+  Check out :ref:`callable_providers_delegation`.
-+ All other injectable values are provided *"as is"*
++ All other injectable values are provided *"as is"*.
-  
++ Positional context arguments will be appended after :py:class:`Callable` 
-For example, if injectable value of injection is a :py:class:`Factory`, it 
-will provide new one instance (as a result of its call) every time, when 
-injection needs to be done.
-
-:py:class:`Callable` behaviour with context positional and keyword arguments 
-is very like a standard Python ``functools.partial``:
-
-- Positional context arguments will be appended after :py:class:`Callable` 
   positional injections.
-- Keyword context arguments have priority on :py:class:`Callable` keyword 
++ Keyword context arguments have priority on :py:class:`Callable` keyword 
   injections and will be merged over them.
 
 Example that shows usage of :py:class:`Callable` with positional argument 
@@ -54,31 +43,16 @@ injections:
    :language: python
    :linenos:
 
-.. _callable_delegation:
+.. _callable_providers_delegation:
 
 Callable providers delegation
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-:py:class:`Callable` provider could be delegated to any other provider via any 
+:py:class:`Callable` provider could be delegated to any other provider via 
-kind of injection. Delegation of :py:class:`Callable` providers is the same as 
+any kind of injection. 
-:py:class:`Factory` and :py:class:`Singleton` providers delegation, please 
-follow *Factory providers delegation* section for example.
 
-:py:class:`Callable` delegate could be created obviously using 
+Delegation of :py:class:`Callable` providers is the same as 
-``Delegate(Callable(...))`` or by calling ``Callable(...).delegate()`` method.
+:py:class:`Factory` providers delegation, please follow 
-
+:ref:`factory_providers_delegation` section for examples (with exception 
-Example:
+about using :py:class:`DelegatedCallable` instead of 
-
+:py:class:`DelegatedFactory`).
-.. literalinclude:: ../../examples/providers/callable_delegation.py
-   :language: python
-   :linenos:
-
-Alternative way of doing :py:class:`Callable` delegation is an usage of 
-:py:class:`DelegatedCallable`. :py:class:`DelegatedCallable` is a 
-:py:class:`Callable` that is always injected "as is".
-
-Example:
-
-.. literalinclude:: ../../examples/providers/delegated_callable.py
-   :language: python
-   :linenos:

docs/providers/index.rst

@@ -19,6 +19,12 @@ be thread safe.
 
 Providers module API docs - :py:mod:`dependency_injector.providers`
 
+Providers class diagram:
+
+.. image:: /images/providers/providers_class_diagram.png
+    :width: 100%
+    :align: center
+
 ..  toctree::
     :maxdepth: 2
 

examples/providers/callable_delegation.py

@@ -1,14 +0,0 @@
-"""`Callable` providers delegation example."""
-
-import sys
-import dependency_injector.providers as providers
-
-
-# Creating some callable provider and few delegates of it:
-callable_provider = providers.Callable(sys.exit)
-callable_provider_delegate1 = callable_provider.delegate()
-callable_provider_delegate2 = providers.Delegate(callable_provider)
-
-# Making some asserts:
-assert callable_provider_delegate1() is callable_provider
-assert callable_provider_delegate2() is callable_provider

examples/providers/callable_kwargs.py

@@ -1,11 +1,11 @@
 """`Callable` providers with keyword arguments example."""
 
 import passlib.hash
+
 import dependency_injector.providers as providers
 
 
-# Password hasher and verifier providers (hash function could be changed
+# Password hasher and verifier providers:
-# anytime (for example, to sha512) without any changes in client's code):
 password_hasher = providers.Callable(passlib.hash.sha256_crypt.encrypt,
                                      salt_size=16,
                                      rounds=10000)

examples/providers/delegated_callable.py

@@ -1,22 +0,0 @@
-"""`DelegatedCallable` providers example."""
-
-import dependency_injector.providers as providers
-
-
-def command1(config):
-    """Some example command."""
-    return config['some_value'] * 5
-
-
-def command2(command1):
-    """Some example command."""
-    return command1() / 2
-
-# Creating callable providers for commands:
-command1_provider = providers.DelegatedCallable(command1,
-                                                config={'some_value': 4})
-command2_provider = providers.DelegatedCallable(command2,
-                                                command1=command1_provider)
-
-# Making some asserts:
-assert command2_provider() == 10