Add docs about Factory and Singleton provides specialization

docs/main/changelog.rst

@@ -9,10 +9,8 @@ follows `Semantic versioning`_
 
 Development version
 -------------------
-- Add possibility to validate ``Factory`` provided type on ``Factory`` 
-  initialization.
-- Add possibility to validate ``Singleton`` provided type on ``Singleton`` 
-  initialization.
+- Add possibility to specialize ``Factory`` provided type.
+- Add possibility to specialize ``Singleton`` provided type.
 - Make some refactorings for providers.
 
 1.11.2

docs/providers/factory.rst

@@ -174,3 +174,14 @@ Example:
 
 .. literalinclude:: ../../examples/providers/factory_delegation.py
    :language: python
+
+Factory providers specialization
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+:py:class:`Factory` provider could be specialized for any kind of needs via 
+declaring its subclasses. 
+
+One of such features is a limitation to :py:class:`Factory` provided type:
+
+.. literalinclude:: ../../examples/providers/factory_provided_type.py
+   :language: python

docs/providers/singleton.rst

@@ -18,13 +18,9 @@ Example:
 Singleton providers and injections
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-:py:class:`Singleton` providers use :py:class:`Factory` providers for first 
-creation of specified class instance, so, all of the rules about injections 
-are the same, as for :py:class:`Factory` providers.
-
-.. image:: /images/providers/singleton_internals.png
-    :width: 80%
-    :align: center
+:py:class:`Singleton` provider extends :py:class:`Factory` provider, so, all 
+of the rules about injections are the same, as for :py:class:`Factory` 
+provider.
 
 .. note::
 
@@ -73,3 +69,14 @@ Example:
 
 .. literalinclude:: ../../examples/providers/singleton_delegation.py
    :language: python
+
+Singleton providers specialization
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+:py:class:`Singleton` provider could be specialized for any kind of needs via 
+declaring its subclasses. 
+
+One of such features is a limitation to :py:class:`Singleton` provided type:
+
+.. literalinclude:: ../../examples/providers/singleton_provided_type.py
+   :language: python

examples/providers/factory_provided_type.py

@@ -0,0 +1,35 @@
+"""`Factory` specialization for limitation to provided type example."""
+
+from dependency_injector import providers
+from dependency_injector import errors
+
+
+class BaseService(object):
+    """Base service class."""
+
+
+class UsersService(BaseService):
+    """Users service."""
+
+
+class PhotosService(BaseService):
+    """Photos service."""
+
+
+class ServiceProvider(providers.Factory):
+    """Service provider."""
+
+    provided_type = BaseService
+
+
+# Creating several service providers with BaseService instances:
+users_service_provider = ServiceProvider(UsersService)
+photos_service_provider = ServiceProvider(PhotosService)
+
+# Trying to create service provider with not a BaseService instance:
+try:
+    some_service_provider = ServiceProvider(object)
+except errors.Error as exception:
+    print exception
+    # __main__.ServiceProvider can provide only
+    # <class '__main__.BaseService'> instances

examples/providers/singleton_provided_type.py

@@ -0,0 +1,35 @@
+"""`Singleton` specialization for limitation to provided type example."""
+
+from dependency_injector import providers
+from dependency_injector import errors
+
+
+class BaseService(object):
+    """Base service class."""
+
+
+class UsersService(BaseService):
+    """Users service."""
+
+
+class PhotosService(BaseService):
+    """Photos service."""
+
+
+class ServiceProvider(providers.Singleton):
+    """Service provider."""
+
+    provided_type = BaseService
+
+
+# Creating several service providers with BaseService instances:
+users_service_provider = ServiceProvider(UsersService)
+photos_service_provider = ServiceProvider(PhotosService)
+
+# Trying to create service provider with not a BaseService instance:
+try:
+    some_service_provider = ServiceProvider(object)
+except errors.Error as exception:
+    print exception
+    # __main__.ServiceProvider can provide only
+    # <class '__main__.BaseService'> instances