Update singleton provider docs

docs/providers/factory.rst

@@ -29,7 +29,7 @@ Injections are done according to the next rules:
 + All providers (instances of :py:class:`Provider`) are called every time 
   when injection needs to be done.
 + Providers could be injected "as is" (delegated), if it is defined obviously.
-  Check out `Factory providers delegation`_.
+  Check out :ref:`factory_providers_delegation`.
 + All other injectable values are provided *"as is"*.
 + Positional context arguments will be appended after :py:class:`Factory` 
   positional injections.
@@ -50,6 +50,8 @@ injectable values are also provided by another factories:
    :language: python
    :linenos:
 
+.. _factory_providers_delegation:
+
 Factory providers delegation
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -89,6 +91,8 @@ Example:
    :language: python
    :linenos:
 
+.. _factory_providers_specialization:
+
 Factory providers specialization
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/providers/singleton.rst

@@ -16,6 +16,20 @@ Example:
    :language: python
    :linenos:
 
+Singleton providers resetting
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Created and memorized by :py:class:`Singleton` instance can be reset. Reset of
+:py:class:`Singleton`'s memorized instance is done by clearing reference to 
+it.  Further lifecycle of memorized instance is out of :py:class:`Singleton` 
+provider's control and dependes on garbage collection strategy.
+
+Example:
+
+.. literalinclude:: ../../examples/providers/singleton_reseting.py
+   :language: python
+   :linenos:
+
 Singleton providers and injections
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -42,47 +56,17 @@ provider.
     . It makes possible to inject providers *as is*. Please check out 
     `Singleton providers delegation`_ section.
 
-Singleton providers resetting
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Created and memorized by :py:class:`Singleton` instance can be reset. Reset of
-:py:class:`Singleton`'s memorized instance is done by clearing reference to 
-it.  Further lifecycle of memorized instance is out of :py:class:`Singleton` 
-provider's control.
-
-Example:
-
-.. literalinclude:: ../../examples/providers/singleton_reseting.py
-   :language: python
-   :linenos:
-
 Singleton providers delegation
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 :py:class:`Singleton` provider could be delegated to any other provider via 
-any kind of injection. Delegation of :py:class:`Singleton` providers is the 
+any kind of injection. 
-same as :py:class:`Factory` providers delegation, please follow *Factory 
-providers delegation* section for example.
 
-:py:class:`Singleton` delegate could be created obviously using 
+Delegation of :py:class:`Singleton` providers is the same as 
-``Delegate(Singleton(...))`` or by calling ``Singleton(...).delegate()`` 
+:py:class:`Factory` providers delegation, please follow 
-method.
+:ref:`factory_providers_delegation` section for examples (with exception 
-
+about using :py:class:`DelegatedSingleton` instead of 
-Example:
+:py:class:`DelegatedFactory`).
-
-.. literalinclude:: ../../examples/providers/singleton_delegation.py
-   :language: python
-   :linenos:
-
-Alternative way of doing :py:class:`Singleton` delegation is an usage of 
-:py:class:`DelegatedSingleton`. :py:class:`DelegatedSingleton` is a 
-:py:class:`Singleton` that is always injected "as is".
-
-Example:
-
-.. literalinclude:: ../../examples/providers/delegated_singleton.py
-   :language: python
-   :linenos:
 
 Singleton providers specialization
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -90,9 +74,6 @@ Singleton providers specialization
 :py:class:`Singleton` provider could be specialized for any kind of needs via 
 declaring its subclasses. 
 
-One of such `builtin` features is a limitation to :py:class:`Singleton` 
+Specialization of :py:class:`Singleton` providers is the same as 
-provided type:
+:py:class:`Factory` providers specialization, please follow 
-
+:ref:`factory_providers_specialization` section for examples.
-.. literalinclude:: ../../examples/providers/singleton_provided_type.py
-   :language: python
-   :linenos:

examples/providers/delegated_singleton.py

@@ -1,18 +0,0 @@
-"""`DelegatedSingleton` providers example."""
-
-import dependency_injector.providers as providers
-
-
-# Some delegated singleton provider:
-singleton_provider = providers.DelegatedSingleton(object)
-registry = providers.DelegatedSingleton(dict,
-                                        object1=singleton_provider,
-                                        object2=singleton_provider)
-
-# Getting several references to singleton object:
-registry = registry()
-singleton_object1 = registry['object1']()
-singleton_object2 = registry['object2']()
-
-# Making some asserts:
-assert singleton_object1 is singleton_object2

examples/providers/singleton.py

@@ -1,20 +1,19 @@
 """`Singleton` providers example."""
 
+import collections
+
 import dependency_injector.providers as providers
 
 
-class UserService(object):
+UsersService = collections.namedtuple('UsersService', [])
-    """Example class UserService."""
 
 # Singleton provider creates new instance of specified class on first call and
 # returns same instance on every next call.
-users_service_provider = providers.Singleton(UserService)
+users_service_provider = providers.Singleton(UsersService)
 
 # Retrieving several UserService objects:
-user_service1 = users_service_provider()
+users_service1 = users_service_provider()
-user_service2 = users_service_provider()
+users_service2 = users_service_provider()
 
 # Making some asserts:
-assert user_service1 is user_service2
+assert users_service1 is users_service2
-assert isinstance(user_service1, UserService)
-assert isinstance(user_service2, UserService)

examples/providers/singleton_delegation.py

@@ -1,13 +0,0 @@
-"""`Singleton` providers delegation example."""
-
-import dependency_injector.providers as providers
-
-
-# Some singleton provider and few delegates of it:
-singleton_provider = providers.Singleton(object)
-singleton_provider_delegate1 = singleton_provider.delegate()
-singleton_provider_delegate2 = providers.Delegate(singleton_provider)
-
-# Making some asserts:
-assert singleton_provider_delegate1() is singleton_provider
-assert singleton_provider_delegate2() is singleton_provider

examples/providers/singleton_reseting.py

@@ -1,28 +1,27 @@
 """`Singleton` providers resetting example."""
 
+import collections
+
 import dependency_injector.providers as providers
 
 
-class UserService(object):
+UsersService = collections.namedtuple('UsersService', [])
-    """Example class UserService."""
 
 # Users service singleton provider:
-users_service_provider = providers.Singleton(UserService)
+users_service_provider = providers.Singleton(UsersService)
 
-# Retrieving several UserService objects:
+# Retrieving several UsersService objects:
-user_service1 = users_service_provider()
+users_service1 = users_service_provider()
-user_service2 = users_service_provider()
+users_service2 = users_service_provider()
 
 # Making some asserts:
-assert user_service1 is user_service2
+assert users_service1 is users_service2
-assert isinstance(user_service1, UserService)
-assert isinstance(user_service2, UserService)
 
 # Resetting of memorized instance:
 users_service_provider.reset()
 
 # Retrieving one more UserService object:
-user_service3 = users_service_provider()
+users_service3 = users_service_provider()
 
 # Making some asserts:
-assert user_service3 is not user_service1
+assert users_service3 is not users_service1