diff --git a/docs/catalogs/index.rst b/docs/catalogs/index.rst index bf3005d0..d403ba21 100644 --- a/docs/catalogs/index.rst +++ b/docs/catalogs/index.rst @@ -4,35 +4,34 @@ Catalogs Catalogs are collections of providers. Main purpose of catalogs is to group providers. -There are, actually, several popular use cases of catalogs: +There are, actually, several popular cases of catalogs usage: -- Grouping of providers from same architectural layer (for example, +- Grouping of providers from the same architectural layer (for example, ``Services``, ``Models`` and ``Forms`` catalogs). -- Grouping of providers from a same functional components (for example, +- Grouping of providers from the same functional groups (for example, catalog ``Users``, that contains all functional parts of ``Users`` component). -Als, for both of these and some other cases, it might be useful to attach +Also, for both of these and some other cases, it might be useful to attach some init / shutdown functionality or something else, that deals with group of providers. Writing catalogs ---------------- -Catalogs have to be created by extending base catalog class -``dependency_injector.catalog.AbstractCatalog``. +Catalogs have to extend base catalog class ``di.AbstractCatalog``. Providers have to be defined like catalog's attributes. Every provider in -catalog has name. This name should follow ``some_provider`` manner, that is -standard naming convention for names of attributes in Python. +catalog has name. This name should follow ``some_provider`` convention, +that is standard naming convention for attribute names in Python. .. note:: - It might be useful to add such - ``""":type: (dependency_injector.Provider) -> Object1"""`` documentation - blocks one line after provider definition for every provider. It will help - code analysis tools and IDE's to understand that variable above contains - some callable object, that returns particular instance as a result of call. + It might be useful to add such ``""":type: (di.Provider) -> Object1"""`` + documentation blocks one line after provider definition for every provider. + It will help code analyzing tools and IDE's to understand that variable + above contains some callable object, that returns particular instance + in a result of call. Example: @@ -49,13 +48,13 @@ Operating with catalog providers There are several things that could be useful for operating with catalog providers: -- First of all, ``Catalog.providers`` attribute contains ``dict`` with all - catalog providers and their catalog names. This dictionary could be used - for any kind of operations that could be done with providers. The only note, - is that ``Catalog.providers`` attribute is read-only. -- Second one, ``Catalog.filter(provider_type=Provider)`` method could be - used for filtering catalog providers by provider types (for example, for - getting all ``Factory`` 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). Example: @@ -71,15 +70,15 @@ same names in overridden catalog. There are two ways to override catalog by another catalog: -- Use ``Catalog.override(Catalog)`` method. -- Use ``@override(Catalog)`` class decorator. +- Use ``di.AbstractCatalog.override(AnotherCatalog)`` method. +- Use ``@di.override(AnotherCatalog)`` class decorator. -Example of overriding catalog using ``Catalog.override()`` method: +Example of overriding catalog using ``di.AbstractCatalog.override()`` method: .. literalinclude:: ../../examples/catalogs/override.py :language: python -Example of overriding catalog using ``@override()`` decorator: +Example of overriding catalog using ``@di.override()`` decorator: .. literalinclude:: ../../examples/catalogs/override_decorator.py :language: python diff --git a/docs/images/catalogs/simple.png b/docs/images/catalogs/simple.png index 71006b0c..ae675ca6 100644 Binary files a/docs/images/catalogs/simple.png and b/docs/images/catalogs/simple.png differ diff --git a/examples/catalogs/override.py b/examples/catalogs/override.py index ff45a9ca..07bb8f0f 100644 --- a/examples/catalogs/override.py +++ b/examples/catalogs/override.py @@ -1,4 +1,4 @@ -"""`Catalog.override()` example.""" +"""Catalog overriding example.""" import collections import dependency_injector as di diff --git a/examples/catalogs/override_decorator.py b/examples/catalogs/override_decorator.py index 099aa577..0f53d244 100644 --- a/examples/catalogs/override_decorator.py +++ b/examples/catalogs/override_decorator.py @@ -1,4 +1,4 @@ -"""Catalog `@override()` decorator example.""" +"""Catalog overriding using `@di.override()` decorator example.""" import collections import dependency_injector as di