From 219932d9cc5ca7886d79476bdce085904eeab377 Mon Sep 17 00:00:00 2001
From: Roman Mogilatov <roman.mogilatov@cupid.com>
Date: Tue, 14 Apr 2015 23:56:46 +0300
Subject: [PATCH] Adding docs on callale provider

---
 docs/providers.rst                    | 35 ++++++++++++++++++++++
 examples/callable_provider.py         | 42 ---------------------------
 examples/readme2/callable_provider.py | 26 +++++++++++++++++
 3 files changed, 61 insertions(+), 42 deletions(-)
 delete mode 100644 examples/callable_provider.py
 create mode 100644 examples/readme2/callable_provider.py

diff --git a/docs/providers.rst b/docs/providers.rst
index 94ee9066..3f2c49c6 100644
--- a/docs/providers.rst
+++ b/docs/providers.rst
@@ -156,6 +156,41 @@ predicted by readability and providable object's type.
 Callable provider
 -----------------
 
+``Callable`` provider is a provider that decorates particular callable with
+some injections. Every call of this provider returns result of call of initial
+callable.
+
+ Example:
+
+ .. code-block:: python
+
+    """`Callable` provider examples."""
+
+    from objects.providers import Callable
+    from objects.providers import Singleton
+
+    from objects.injections import KwArg
+
+    import sqlite3
+
+
+    def some_function(arg, database):
+        """Example function that has input arg and dependency on database."""
+        return database.execute('SELECT @1', [arg]).fetchone()[0]
+
+
+    # Database and `ObjectA` providers.
+    database = Singleton(sqlite3.Connection,
+                         KwArg('database', ':memory:'))
+
+    some_function = Callable(some_function,
+                             KwArg('database', database))
+
+    # Some asserts.
+    assert some_function(1) == 1
+    assert some_function(2) == 2
+    assert some_function(2231) == 2231
+
 External dependency provider
 ----------------------------
 
diff --git a/examples/callable_provider.py b/examples/callable_provider.py
deleted file mode 100644
index feef362c..00000000
--- a/examples/callable_provider.py
+++ /dev/null
@@ -1,42 +0,0 @@
-"""Callable provider examples."""
-
-from objects.catalog import AbstractCatalog
-
-from objects.providers import Singleton
-from objects.providers import Callable
-
-from objects.injections import KwArg
-from objects.injections import Attribute
-
-import sqlite3
-
-
-def consuming_function(arg, db):
-    """Example function that has input arg and dependency on database."""
-    return arg, db
-
-
-class Catalog(AbstractCatalog):
-
-    """Catalog of objects providers."""
-
-    database = Singleton(sqlite3.Connection,
-                         KwArg('database', ':memory:'),
-                         Attribute('row_factory', sqlite3.Row))
-    """:type: (objects.Provider) -> sqlite3.Connection"""
-
-    consuming_function = Callable(consuming_function,
-                                  KwArg('db', database))
-    """:type: (objects.Provider) -> consuming_function"""
-
-
-# Some calls.
-arg1, db1 = Catalog.consuming_function(1)
-arg2, db2 = Catalog.consuming_function(2)
-arg3, db3 = Catalog.consuming_function(3)
-
-# Some asserts.
-assert db1 is db2 is db3
-assert arg1 == 1
-assert arg2 == 2
-assert arg3 == 3
diff --git a/examples/readme2/callable_provider.py b/examples/readme2/callable_provider.py
new file mode 100644
index 00000000..cca90cb3
--- /dev/null
+++ b/examples/readme2/callable_provider.py
@@ -0,0 +1,26 @@
+"""`Callable` provider examples."""
+
+from objects.providers import Callable
+from objects.providers import Singleton
+
+from objects.injections import KwArg
+
+import sqlite3
+
+
+def some_function(arg, database):
+    """Example function that has input arg and dependency on database."""
+    return database.execute('SELECT @1', [arg]).fetchone()[0]
+
+
+# Database and `ObjectA` providers.
+database = Singleton(sqlite3.Connection,
+                     KwArg('database', ':memory:'))
+
+some_function = Callable(some_function,
+                         KwArg('database', database))
+
+# Some asserts.
+assert some_function(1) == 1
+assert some_function(2) == 2
+assert some_function(2231) == 2231