Adding callable provider docs and some minor changes to factory docs

docs/_providers.rst

@@ -164,7 +164,3 @@ Example:
     assert object_a_1 is not object_a_2
     assert object_a_1.get_one() == object_a_2.get_one() == 2
 
-
-
-
-.. _Constructor injection: http://en.wikipedia.org/wiki/Dependency_injection#Constructor_injection

docs/providers/callable.rst

@@ -0,0 +1,64 @@
+Callable providers
+------------------
+
+``Callable`` provider is a provider that decorates 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 like keyword arguments during call time.
+
+Context keyword arguments have higher priority than ``KwArg`` injections.
+
+Example:
+
+.. code-block:: python
+
+    """`Callable` providers examples."""
+
+    from objects.providers import Callable
+    from objects.providers import Singleton
+
+    from objects.injections import KwArg
+
+
+    class UserService(object):
+
+        """Example class UserService."""
+
+        def get_by_id(self, id):
+            """Return user info by user id."""
+            return {'id': id, 'login': 'example_user'}
+
+
+    def get_user_by_id(user_id, users_service):
+        """Example function that has input arg and dependency on database."""
+        return users_service.get_by_id(user_id)
+
+
+    # UserService and get_user_by_id providers:
+    users_service = Singleton(UserService)
+    get_user_by_id = Callable(get_user_by_id,
+                              KwArg('users_service', users_service))
+
+    # Making some asserts:
+    assert get_user_by_id(1) == {'id': 1, 'login': 'example_user'}
+    assert get_user_by_id(2) == {'id': 2, 'login': 'example_user'}
+
+
+    # Context keyword arguments priority example:
+    class UserServiceMock(object):
+
+        """Example class UserService."""
+
+        def get_by_id(self, id):
+            """Return user info by user id."""
+            return {'id': id, 'login': 'mock'}
+
+
+    user_service_mock = UserServiceMock()
+
+    user3 = get_user_by_id(1, users_service=user_service_mock)
+
+    assert user3 == {'id': 1, 'login': 'mock'}
+

docs/providers/factory.rst

@@ -48,8 +48,8 @@ injections that are used by ``Factory`` provider:
       ``__init__()`` method in time of object's creation via keyword argument.
       Takes keyword name of ``__init__()`` argument and injectable value.
     - ``Attribute`` - injection is done by setting specified attribute with
-      injectable value right after object's creation. Takes attribute name and
-      injectable value.
+      injectable value right after object's creation. Takes attribute's name
+      and injectable value.
     - ``Method`` - injection is done by calling of specified method with
       injectable value right after object's creation and attribute injections
       are done. Takes method name and injectable value.

docs/providers/index.rst

@@ -11,3 +11,4 @@ All providers are callable. They describe how particular objects are provided.
     factory
     singleton
     static
+    callable

examples/providers/callable.py

@@ -0,0 +1,47 @@
+"""`Callable` providers examples."""
+
+from objects.providers import Callable
+from objects.providers import Singleton
+
+from objects.injections import KwArg
+
+
+class UserService(object):
+
+    """Example class UserService."""
+
+    def get_by_id(self, id):
+        """Return user info by user id."""
+        return {'id': id, 'login': 'example_user'}
+
+
+def get_user_by_id(user_id, users_service):
+    """Example function that has input arg and dependency on database."""
+    return users_service.get_by_id(user_id)
+
+
+# UserService and get_user_by_id providers:
+users_service = Singleton(UserService)
+get_user_by_id = Callable(get_user_by_id,
+                          KwArg('users_service', users_service))
+
+# Making some asserts:
+assert get_user_by_id(1) == {'id': 1, 'login': 'example_user'}
+assert get_user_by_id(2) == {'id': 2, 'login': 'example_user'}
+
+
+# Context keyword arguments priority example:
+class UserServiceMock(object):
+
+    """Example class UserService."""
+
+    def get_by_id(self, id):
+        """Return user info by user id."""
+        return {'id': id, 'login': 'mock'}
+
+
+user_service_mock = UserServiceMock()
+
+user3 = get_user_by_id(1, users_service=user_service_mock)
+
+assert user3 == {'id': 1, 'login': 'mock'}

examples/readme2/callable_providers.py

@@ -1,26 +0,0 @@
-"""`Callable` providers 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