Update docs of Callable provider with description of positional agrument injections and new example

docs/main/changelog.rst

@@ -16,7 +16,7 @@ Development version
 - Add images for catalog "Writing catalogs" and "Operating with catalogs" 
   examples.
 - Add functionality for using positional argument injections with 
-  ``di.Factory`` and ``di.Singleton`` providers.
+  ``di.Factory``, ``di.Singleton`` and ``di.Callable`` providers.
 - Add optimization for ``di.Injection.value`` property that will compute 
   type of injection once, instead of doing this on every call.
 - Add functionality for decorating classes with ``@di.inject``.

docs/providers/callable.rst

@@ -8,20 +8,40 @@ callable.
 Callable providers and injections
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-``di.Callable`` provider uses keyword argument injections. Keyword argument 
-injections are done by passing injectable values as keyword arguments during 
-call time.
+``di.Callable`` takes a various number of positional and keyword arguments 
+that are used as decorated callable injections. Every time, when 
+``di.Callable`` is called, positional and keyword argument injections would be 
+passed as an callable arguments.
 
-Context keyword arguments have higher priority than keyword argument 
-injections.
+Such behaviour is very similar to the standard Python ``functools.partial`` 
+object, except of one thing: all injectable values are provided 
+*"as is"*, except of providers (subclasses of ``di.Provider``). Providers 
+will be called every time, when injection needs to be done. For example, 
+if injectable value of injection is a ``di.Factory``, it will provide new one 
+instance (as a result of its call) every time, when injection needs to be done.
 
-Example:
+``di.Callable`` behaviour with context positional and keyword arguments is 
+very like a standard Python ``functools.partial``:
+
+- Positional context arguments will be appended after ``di.Callable`` 
+  positional injections.
+- Keyword context arguments have priority on ``di.Callable`` keyword 
+  injections and will be merged over them.
+
+Example that shows usage of ``di.Callable`` with positional argument 
+injections:
+
+.. literalinclude:: ../../examples/providers/callable_args.py
+   :language: python
+
+Next one example shows usage of ``di.Callable`` with keyword argument 
+injections:
 
 .. image:: /images/providers/callable.png
     :width: 100%
     :align: center
 
-.. literalinclude:: ../../examples/providers/callable_injections.py
+.. literalinclude:: ../../examples/providers/callable_kwargs.py
    :language: python
 
 Callable providers delegation

examples/providers/callable_args.py

@@ -0,0 +1,16 @@
+"""`di.Callable` providers with positional arguments example."""
+
+import dependency_injector as di
+
+
+# Creating even and odd filter providers:
+even_filter = di.Callable(filter, lambda x: x % 2 == 0)
+odd_filter = di.Callable(filter, lambda x: x % 2 != 0)
+
+# Creating even and odd ranges using xrange() and filter providers:
+even_range = even_filter(xrange(1, 10))
+odd_range = odd_filter(xrange(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,4 +1,4 @@
-"""`di.Callable` providers example."""
+"""`di.Callable` providers with keyword arguments example."""
 
 import passlib.hash
 import dependency_injector as di
@@ -10,6 +10,6 @@ password_hasher = di.Callable(passlib.hash.sha256_crypt.encrypt,
                               rounds=10000)
 password_verifier = di.Callable(passlib.hash.sha256_crypt.verify)
 
-# Making some asserts (client's code):
+# Making some asserts:
 hashed_password = password_hasher('super secret')
 assert password_verifier('super secret', hashed_password)