From a612e42a992464ba6d97e0436605bd8e59dd0e2d Mon Sep 17 00:00:00 2001
From: Roman Mogilatov <roman.mogilatov@cupid.com>
Date: Fri, 19 Jun 2015 12:44:46 +0300
Subject: [PATCH] First steps with providers delegation docs

---
 docs/providers/delegation.rst    | 75 ++++++++++++++++++++++++++++++++
 docs/providers/index.rst         |  1 +
 examples/providers/delegation.py | 68 +++++++++++++++++++++++++++++
 3 files changed, 144 insertions(+)
 create mode 100644 docs/providers/delegation.rst
 create mode 100644 examples/providers/delegation.py

diff --git a/docs/providers/delegation.rst b/docs/providers/delegation.rst
new file mode 100644
index 00000000..585dcdc1
--- /dev/null
+++ b/docs/providers/delegation.rst
@@ -0,0 +1,75 @@
+Providers delegation
+--------------------
+
+Example:
+
+.. code-block:: python
+
+    """Providers delegation example."""
+
+    from objects.providers import Factory
+    from objects.providers import Singleton
+
+    from objects.injections import KwArg
+
+
+    class User(object):
+
+        """Example class User."""
+
+        def __init__(self, id, name):
+            """Initializer.
+
+            :param id: int
+            :param name: str
+            :return:
+            """
+            self.id = id
+            self.name = name
+
+
+    class UserService(object):
+
+        """Example class UserService.
+
+        UserService has dependency on users factory.
+        """
+
+        def __init__(self, users_factory):
+            """Initializer.
+
+            :param users_factory: objects.providers.Factory
+            :return:
+            """
+            self.users_factory = users_factory
+
+        def get_by_id(self, id):
+            """Return user info by user id."""
+            return self.users_factory(id=id, name=self._get_name_from_db(id))
+
+        def _get_name_from_db(self, id):
+            """Return user's name from database by his id.
+
+            Main purpose of this method is just to show the fact of retrieving
+            some user's data from database, so, actually, it simulates work
+            with database just by merging constant string with provided user's id.
+            """
+            return ''.join(('user', str(id)))
+
+
+    # Users factory and UserService provider:
+    users_factory = Factory(User)
+    users_service = Singleton(UserService,
+                              KwArg('users_factory', users_factory.delegate()))
+
+
+    # Creating several User objects:
+    user1 = users_service().get_by_id(1)
+    user2 = users_service().get_by_id(2)
+
+    # Making some asserts:
+    assert user1.id == 1
+    assert user1.name == 'user1'
+
+    assert user2.id == 2
+    assert user2.name == 'user2'
diff --git a/docs/providers/index.rst b/docs/providers/index.rst
index 8815ba0e..070c57c7 100644
--- a/docs/providers/index.rst
+++ b/docs/providers/index.rst
@@ -13,3 +13,4 @@ All providers are callable. They describe how particular objects are provided.
     static
     callable
     external_dependency
+    delegation
diff --git a/examples/providers/delegation.py b/examples/providers/delegation.py
new file mode 100644
index 00000000..cfaff6d8
--- /dev/null
+++ b/examples/providers/delegation.py
@@ -0,0 +1,68 @@
+"""Providers delegation example."""
+
+from objects.providers import Factory
+from objects.providers import Singleton
+
+from objects.injections import KwArg
+
+
+class User(object):
+
+    """Example class User."""
+
+    def __init__(self, id, name):
+        """Initializer.
+
+        :param id: int
+        :param name: str
+        :return:
+        """
+        self.id = id
+        self.name = name
+
+
+class UserService(object):
+
+    """Example class UserService.
+
+    UserService has dependency on users factory.
+    """
+
+    def __init__(self, users_factory):
+        """Initializer.
+
+        :param users_factory: objects.providers.Factory
+        :return:
+        """
+        self.users_factory = users_factory
+
+    def get_by_id(self, id):
+        """Return user info by user id."""
+        return self.users_factory(id=id, name=self._get_name_from_db(id))
+
+    def _get_name_from_db(self, id):
+        """Return user's name from database by his id.
+
+        Main purpose of this method is just to show the fact of retrieving
+        some user's data from database, so, actually, it simulates work
+        with database just by merging constant string with provided user's id.
+        """
+        return ''.join(('user', str(id)))
+
+
+# Users factory and UserService provider:
+users_factory = Factory(User)
+users_service = Singleton(UserService,
+                          KwArg('users_factory', users_factory.delegate()))
+
+
+# Creating several User objects:
+user1 = users_service().get_by_id(1)
+user2 = users_service().get_by_id(2)
+
+# Making some asserts:
+assert user1.id == 1
+assert user1.name == 'user1'
+
+assert user2.id == 2
+assert user2.name == 'user2'