From 54eb60698b4e9f6e6090ef1bc450b720b51adfc5 Mon Sep 17 00:00:00 2001
From: Roman Mogilatov <rmogilatov@gmail.com>
Date: Thu, 16 Jul 2015 00:48:30 +0300
Subject: [PATCH] Reverting removing of Callable docs

---
 docs/providers/callable.rst | 60 +++++++++++++++++++++++++++++++++++++
 docs/providers/index.rst    |  1 +
 2 files changed, 61 insertions(+)
 create mode 100644 docs/providers/callable.rst

diff --git a/docs/providers/callable.rst b/docs/providers/callable.rst
new file mode 100644
index 00000000..9d1b4b35
--- /dev/null
+++ b/docs/providers/callable.rst
@@ -0,0 +1,60 @@
+Callable providers
+------------------
+
+``Callable`` provider is a provider that wraps particular callable with
+some injections. Every call of this provider returns result of call of initial
+callable.
+
+``Callable`` provider uses ``KwArg`` injections. ``KwArg`` injections are
+done by passing injectable values as keyword arguments during call time.
+
+Context keyword arguments have higher priority than ``KwArg`` injections.
+
+Example:
+
+.. image:: /images/callable.png
+    :width: 100%
+    :align: center
+
+.. code-block:: python
+
+    """`Callable` providers examples."""
+
+    from objects.providers import Callable
+    from objects.injections import KwArg
+
+
+    class SomeCrypt(object):
+
+        """Example class SomeCrypt."""
+
+        @staticmethod
+        def encrypt(data, password):
+            """Encypt data using password."""
+            return ''.join((password, data, password))
+
+        @staticmethod
+        def decrypt(data, password):
+            """Decrypt data using password."""
+            return data[len(password):-len(password)]
+
+
+    # Encrypt and decrypt function providers:
+    encrypt = Callable(SomeCrypt.encrypt,
+                       KwArg('password', 'secret123'))
+    decrypt = Callable(SomeCrypt.decrypt,
+                       KwArg('password', 'secret123'))
+
+    # Making some asserts:
+    initial_data = 'some_data'
+
+    encrypted1 = encrypt(initial_data)
+    decrypted1 = decrypt(encrypted1)
+
+    assert decrypted1 == initial_data
+
+    # Context keyword arguments priority example:
+    encrypted2 = encrypt(initial_data, password='another_secret')
+    decrypted2 = decrypt(encrypted2)
+
+    assert decrypted2 != initial_data
diff --git a/docs/providers/index.rst b/docs/providers/index.rst
index 1b5eab00..070c57c7 100644
--- a/docs/providers/index.rst
+++ b/docs/providers/index.rst
@@ -11,5 +11,6 @@ All providers are callable. They describe how particular objects are provided.
     factory
     singleton
     static
+    callable
     external_dependency
     delegation