From 0efebb337f37b1dd8ecadc35354af731a53ebfeb Mon Sep 17 00:00:00 2001
From: Roman Mogilatov <rmogilatov@gmail.com>
Date: Mon, 20 Jul 2015 19:31:31 +0300
Subject: [PATCH] Adding explanation for Singleton and Callable providers
 delegation

---
 docs/providers/callable.rst                   | 35 +++++++++++++++++++
 docs/providers/singleton.rst                  | 30 ++++++++++++++++
 examples/providers/callable_delegation.py     | 16 +++++++++
 .../{callable.py => callable_injections.py}   |  0
 examples/providers/singleton_delegation.py    | 14 ++++++++
 5 files changed, 95 insertions(+)
 create mode 100644 examples/providers/callable_delegation.py
 rename examples/providers/{callable.py => callable_injections.py} (100%)
 create mode 100644 examples/providers/singleton_delegation.py

diff --git a/docs/providers/callable.rst b/docs/providers/callable.rst
index a9091e99..a2ca017e 100644
--- a/docs/providers/callable.rst
+++ b/docs/providers/callable.rst
@@ -5,6 +5,9 @@ Callable providers
 some injections. Every call of this provider returns result of call of initial
 callable.
 
+Callable providers and injections
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 ``Callable`` provider uses ``KwArg`` injections. ``KwArg`` injections are
 done by passing injectable values as keyword arguments during call time.
 
@@ -36,3 +39,35 @@ Example:
     # Making some asserts (client's code):
     hashed_password = password_hasher('super secret')
     assert password_verifier('super secret', hashed_password)
+
+Callable providers delegation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``Callable`` provider could be delegated to any other provider via any kind of
+injection. Delegation of ``Callable`` providers is the same as ``Factory`` and
+``Singleton`` providers delegation, please follow *Factory providers 
+delegation* section for example.
+
+``Callable`` delegate could be created obviously using 
+``Delegate(Callable())`` or by calling ``Callable.delegate()`` method.
+
+Example:
+
+.. code-block:: python
+
+    """`Callable` providers delegation example."""
+
+    import sys
+
+    from objects.providers import Callable
+    from objects.providers import Delegate
+
+
+    # Some callable provider and few delegates of it:
+    callable_provider = Callable(sys.exit)
+    callable_provider_delegate1 = callable_provider.delegate()
+    callable_provider_delegate2 = Delegate(callable_provider)
+
+    # Making some asserts:
+    assert callable_provider_delegate1() is callable_provider
+    assert callable_provider_delegate2() is callable_provider
diff --git a/docs/providers/singleton.rst b/docs/providers/singleton.rst
index dbe03bba..4da14692 100644
--- a/docs/providers/singleton.rst
+++ b/docs/providers/singleton.rst
@@ -102,3 +102,33 @@ Example:
 
     # Making some asserts:
     assert user_service3 is not user_service1
+
+Singleton providers delegation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``Singleton`` provider could be delegated to any other provider via any kind of
+injection. Delegation of ``Singleton`` providers is the same as ``Factory``
+providers delegation, please follow *Factory providers delegation* section for
+example.
+
+``Singleton`` delegate could be created obviously using 
+``Delegate(Singleton())`` or by calling ``Singleton.delegate()`` method.
+
+Example:
+
+.. code-block:: python
+
+    """`Singleton` providers delegation example."""
+
+    from objects.providers import Singleton
+    from objects.providers import Delegate
+
+
+    # Some singleton provider and few delegates of it:
+    singleton_provider = Singleton(object)
+    singleton_provider_delegate1 = singleton_provider.delegate()
+    singleton_provider_delegate2 = Delegate(singleton_provider)
+
+    # Making some asserts:
+    assert singleton_provider_delegate1() is singleton_provider
+    assert singleton_provider_delegate2() is singleton_provider
diff --git a/examples/providers/callable_delegation.py b/examples/providers/callable_delegation.py
new file mode 100644
index 00000000..d8569afe
--- /dev/null
+++ b/examples/providers/callable_delegation.py
@@ -0,0 +1,16 @@
+"""`Callable` providers delegation example."""
+
+import sys
+
+from objects.providers import Callable
+from objects.providers import Delegate
+
+
+# Some callable provider and few delegates of it:
+callable_provider = Callable(sys.exit)
+callable_provider_delegate1 = callable_provider.delegate()
+callable_provider_delegate2 = Delegate(callable_provider)
+
+# Making some asserts:
+assert callable_provider_delegate1() is callable_provider
+assert callable_provider_delegate2() is callable_provider
diff --git a/examples/providers/callable.py b/examples/providers/callable_injections.py
similarity index 100%
rename from examples/providers/callable.py
rename to examples/providers/callable_injections.py
diff --git a/examples/providers/singleton_delegation.py b/examples/providers/singleton_delegation.py
new file mode 100644
index 00000000..9ca2fce9
--- /dev/null
+++ b/examples/providers/singleton_delegation.py
@@ -0,0 +1,14 @@
+"""`Singleton` providers delegation example."""
+
+from objects.providers import Singleton
+from objects.providers import Delegate
+
+
+# Some singleton provider and few delegates of it:
+singleton_provider = Singleton(object)
+singleton_provider_delegate1 = singleton_provider.delegate()
+singleton_provider_delegate2 = Delegate(singleton_provider)
+
+# Making some asserts:
+assert singleton_provider_delegate1() is singleton_provider
+assert singleton_provider_delegate2() is singleton_provider