From 9c661744d5b1f451aae51c39732646d11d9b5e35 Mon Sep 17 00:00:00 2001
From: Roman Mogilatov <rmogilatov@gmail.com>
Date: Wed, 7 Oct 2015 19:41:53 +0300
Subject: [PATCH] Update docs about catalogs inheritance

---
 docs/catalogs/index.rst                       | 25 +++++++-----
 docs/main/changelog.rst                       |  1 +
 examples/catalogs/operating_with_providers.py | 38 +++++++++++--------
 3 files changed, 39 insertions(+), 25 deletions(-)

diff --git a/docs/catalogs/index.rst b/docs/catalogs/index.rst
index d403ba21..a1a36705 100644
--- a/docs/catalogs/index.rst
+++ b/docs/catalogs/index.rst
@@ -45,16 +45,23 @@ Example:
 Operating with catalog providers
 --------------------------------
 
-There are several things that could be useful for operating with catalog
-providers:
+``di.AbstractCatalog`` has several features that could be useful for some kind 
+of operations on catalog's providers:
 
-- First of all, ``di.AbstractCatalog.providers`` attribute contains ``dict`` 
-  with all catalog providers. This dictionary could be used for any kind of 
-  operations that could be done with providers. The only note, is that 
-  ``di.AbstractCatalog.providers`` attribute is read-only.
-- Second one, ``di.AbstractCatalog.filter(provider_type=di.Provider)`` method 
-  could be used for filtering catalog providers by provider types (for example,
-  for getting all ``di.Factory`` providers).
+- ``di.AbstractCatalog.providers`` is read-only attribute that contains 
+  ``dict`` of all catalog providers, including providers that are inherited 
+  from parent catalogs, where key is the name of provider and value is 
+  provider itself.
+- ``di.AbstractCatalog.cls_providers`` is read-only attribute contains ``dict``
+  of current catalog providers, where key is the name of provider and value is 
+  provider itself.
+- ``di.AbstractCatalog.inherited_providers`` is read-only attribute contains 
+  ``dict`` of all providers that are inherited from parent catalogs, where key 
+  is the name of provider and value is provider itself. 
+- ``di.AbstractCatalog.filter(provider_type=di.Provider)`` is a class method 
+  that could be used for filtering catalog providers by provider types 
+  (for example, for getting all ``di.Factory`` providers). 
+  ``di.AbstractCatalog.filter()`` method use ``di.AbstractCatalog.providers``.
 
 Example:
 
diff --git a/docs/main/changelog.rst b/docs/main/changelog.rst
index 7bfa3905..69cf93a0 100644
--- a/docs/main/changelog.rst
+++ b/docs/main/changelog.rst
@@ -12,6 +12,7 @@ Development version
 -------------------
 
 - Add functionality for decorating classes with ``@di.inject``.
+- Add enhancement for ``di.AbstractCatalog`` inheritance.
 
 0.9.5
 -----
diff --git a/examples/catalogs/operating_with_providers.py b/examples/catalogs/operating_with_providers.py
index aac10d07..d3246168 100644
--- a/examples/catalogs/operating_with_providers.py
+++ b/examples/catalogs/operating_with_providers.py
@@ -3,29 +3,35 @@
 import dependency_injector as di
 
 
-class Catalog(di.AbstractCatalog):
+class CatalogA(di.AbstractCatalog):
 
-    """Providers catalog."""
+    """Example catalog A."""
 
     provider1 = di.Factory(object)
     """:type: (di.Provider) -> object"""
 
-    provider2 = di.Factory(object)
-    """:type: (di.Provider) -> object"""
 
-    provider3 = di.Singleton(object)
-    """:type: (di.Provider) -> object"""
+class CatalogB(CatalogA):
 
-    provider4 = di.Singleton(object)
+    """Example catalog B."""
+
+    provider2 = di.Singleton(object)
     """:type: (di.Provider) -> object"""
 
 
-# Making some asserts:
-assert Catalog.providers == dict(provider1=Catalog.provider1,
-                                 provider2=Catalog.provider2,
-                                 provider3=Catalog.provider3,
-                                 provider4=Catalog.provider4)
-assert Catalog.filter(di.Factory) == dict(provider1=Catalog.provider1,
-                                          provider2=Catalog.provider2)
-assert Catalog.filter(di.Singleton) == dict(provider3=Catalog.provider3,
-                                            provider4=Catalog.provider4)
+# Making some asserts for `providers` attribute:
+assert CatalogA.providers == dict(provider1=CatalogA.provider1)
+assert CatalogB.providers == dict(provider1=CatalogA.provider1,
+                                  provider2=CatalogB.provider2)
+
+# Making some asserts for `cls_providers` attribute:
+assert CatalogA.cls_providers == dict(provider1=CatalogA.provider1)
+assert CatalogB.cls_providers == dict(provider2=CatalogB.provider2)
+
+# Making some asserts for `inherited_providers` attribute:
+assert CatalogA.inherited_providers == dict()
+assert CatalogB.inherited_providers == dict(provider1=CatalogA.provider1)
+
+# Making some asserts for `filter()` method:
+assert CatalogB.filter(di.Factory) == dict(provider1=CatalogA.provider1)
+assert CatalogB.filter(di.Singleton) == dict(provider2=CatalogB.provider2)