Update callable provider docs

docs/main/changelog.rst

@@ -9,8 +9,8 @@ follows `Semantic versioning`_
 
 Development version
 -------------------
-- Update ``Singleton`` provider documentation.
+- Update ``Singleton`` provider documentation and rework examples.
-- Rework ``Singleton`` provider examples.
+- Update ``Callable`` provider documentation and rework examples.
 
 3.34.0
 ------

docs/providers/callable.rst

@@ -1,69 +1,20 @@
-Callable providers
+Callable provider
-------------------
+-----------------
+
+.. meta::
+   :keywords: Python,DI,Dependency injection,IoC,Inversion of Control,Function,Method,Example
+   :description: Callable provider helps to make dependencies injection into functions. This page
+                 demonstrates how to use a Callable provider.
 
 .. currentmodule:: dependency_injector.providers
 
-:py:class:`Callable` provider calls wrapped callable on every call.
+:py:class:`Callable` provider calls a function, a method or another callable.
 
-Callable providers and injections
+.. literalinclude:: ../../examples/providers/callable.py
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-:py:class:`Callable` provider takes a various number of positional and keyword 
-arguments that are used as wrapped callable injections. Every time, when 
-:py:class:`Callable` provider is called, positional and keyword argument 
-injections would be passed as callable arguments.
-
-Injections are done according to the next rules:
-
-+ 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 :ref:`callable_providers_delegation`.
-+ All other injectable values are provided *"as is"*.
-+ Positional context arguments will be appended after :py:class:`Callable` 
-  positional injections.
-+ 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 
-injections:
-
-.. literalinclude:: ../../examples/providers/callable_args.py
    :language: python
+   :lines: 3-
 
-Next one example shows usage of :py:class:`Callable` with keyword argument 
+``Callable`` provider handles an injection of the dependencies the same way like a
-injections:
+:ref:`factory-provider`.
-
-.. image:: /images/providers/callable.png
-    :width: 100%
-    :align: center
-
-.. literalinclude:: ../../examples/providers/callable_kwargs.py
-   :language: python
-
-.. _callable_providers_delegation:
-
-Callable providers delegation
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-:py:class:`Callable` provider could be delegated to any other provider via 
-any kind of injection. 
-
-Delegation of :py:class:`Callable` providers is the same as 
-:py:class:`Factory` providers delegation, please follow 
-:ref:`factory_providers_delegation` section for examples (with exception 
-of using :py:class:`DelegatedCallable` instead of
-:py:class:`DelegatedFactory`).
-
-Abstract callable providers
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-:py:class:`AbstractCallable` provider is a :py:class:`Callable` provider that
-must be explicitly overridden before calling.
-
-Behaviour of :py:class:`AbstractCallable` providers is the same as of
-:py:class:`AbstractFactory`, please follow :ref:`abstract_factory_providers`
-section for examples (with exception of using :py:class:`AbstractCallable`
-provider instead of :py:class:`AbstractFactory`).
 
 .. disqus::

examples/providers/callable.py

@@ -0,0 +1,18 @@
+"""`Callable` provider example."""
+
+import passlib.hash
+
+from dependency_injector import providers
+
+
+password_hasher = providers.Callable(
+    passlib.hash.sha256_crypt.hash,
+    salt_size=16,
+    rounds=10000,
+)
+password_verifier = providers.Callable(passlib.hash.sha256_crypt.verify)
+
+
+if __name__ == '__main__':
+    hashed_password = password_hasher('super secret')
+    assert password_verifier('super secret', hashed_password)

examples/providers/callable_args.py

@@ -1,16 +0,0 @@
-"""`Callable` providers with positional arguments example."""
-
-import dependency_injector.providers as providers
-
-
-# Creating even and odd filter providers:
-even_filter = providers.Callable(filter, lambda x: x % 2 == 0)
-odd_filter = providers.Callable(filter, lambda x: x % 2 != 0)
-
-# Creating even and odd ranges using range() and filter providers:
-even_range = even_filter(range(1, 10))
-odd_range = odd_filter(range(1, 10))
-
-# Making some asserts:
-assert even_range == [2, 4, 6, 8]
-assert odd_range == [1, 3, 5, 7, 9]

examples/providers/callable_kwargs.py

@@ -1,16 +0,0 @@
-"""`Callable` providers with keyword arguments example."""
-
-import passlib.hash
-
-import dependency_injector.providers as providers
-
-
-# Password hasher and verifier providers:
-password_hasher = providers.Callable(passlib.hash.sha256_crypt.encrypt,
-                                     salt_size=16,
-                                     rounds=10000)
-password_verifier = providers.Callable(passlib.hash.sha256_crypt.verify)
-
-# Making some asserts:
-hashed_password = password_hasher('super secret')
-assert password_verifier('super secret', hashed_password)