Update catalog provider bundles docs

docs/catalogs/bundles.rst

@@ -0,0 +1,28 @@
+Creating catalog provider bundles
+---------------------------------
+
+``di.AbstractCatalog.Bundle`` is a limited collection of catalog providers. 
+While catalog could be used as a centralized place for particular providers 
+group, such bundles of catalog providers can be used for creating several 
+limited scopes that could be passed to different subsystems.
+
+``di.AbstractCatalog.Bundle`` has exactly the same API as 
+``di.AbstractCatalog`` except of the limitations on getting providers.
+
+Each ``di.AbstractCatalog`` has a reference to its bundle class - 
+``di.AbstractCatalog.Bundle``. For example, if some concrete catalog has name 
+``SomeCatalog``, then its bundle class could be reached as 
+``SomeCatalog.Bundle``. 
+
+``di.AbstractCatalog.Bundle`` expects to get the list of its catalog providers
+as positional arguments and will limit the scope of created bundle to this 
+list. 
+
+Example:
+
+.. image:: /images/catalogs/bundles.png
+    :width: 100%
+    :align: center
+
+.. literalinclude:: ../../examples/catalogs/bundles.py
+   :language: python

docs/catalogs/index.rst

@@ -21,5 +21,5 @@ of providers.
 
     writing
     operating
-    subsets
+    bundles
     overriding

docs/catalogs/subsets.rst

@@ -1,19 +0,0 @@
-Creating catalog subsets
-------------------------
-
-``di.AbstractCatalog`` subset is a limited collection of catalog providers. 
-While catalog could be used as a centralized place for particular providers 
-group, such subsets of catalog providers can be used for creating several 
-limited scopes that could be passed to different subsystems.
-
-``di.AbstractCatalog`` subsets could be created by instantiating of particular 
-catalog with passing provider names to the constructor.
-
-Example:
-
-.. image:: /images/catalogs/subsets.png
-    :width: 100%
-    :align: center
-
-.. literalinclude:: ../../examples/catalogs/subsets.py
-   :language: python

examples/catalogs/bundles.py

@@ -1,4 +1,4 @@
-"""Catalog subsets example."""
+"""Catalog bundles example."""
 
 import dependency_injector as di
 
@@ -22,7 +22,7 @@ class BaseWebView(object):
         """Initializer.
 
         :type services: Services
-        :param services: Subset of service providers
+        :param services: Bundle of service providers
         """
         self.services = services
 
@@ -35,11 +35,11 @@ class AuthView(BaseWebView):
 class PhotosView(BaseWebView):
     """Example photo processing web view."""
 
-# Creating example views with appropriate service provider packs:
+# Creating example views with appropriate service provider bundles:
-auth_view = AuthView(Services.Pack(Services.users,
+auth_view = AuthView(Services.Bundle(Services.users,
-                                   Services.auth))
+                                     Services.auth))
-photos_view = PhotosView(Services.Pack(Services.users,
+photos_view = PhotosView(Services.Bundle(Services.users,
-                                       Services.photos))
+                                         Services.photos))
 
 # Making some asserts:
 assert auth_view.services.users is Services.users
@@ -47,7 +47,7 @@ assert auth_view.services.auth is Services.auth
 try:
     auth_view.services.photos
 except di.Error:
-    # `photos` service provider is not in scope of `auth_view` services subset,
+    # `photos` service provider is not in scope of `auth_view` services bundle,
     # so `di.Error` will be raised.
     pass
 
@@ -57,5 +57,5 @@ try:
     photos_view.services.auth
 except di.Error as exception:
     # `auth` service provider is not in scope of `photo_processing_view`
-    # services subset, so `di.Error` will be raised.
+    # services bundle, so `di.Error` will be raised.
     pass