diff --git a/docs/catalogs/bundles.rst b/docs/catalogs/bundles.rst index 50c76866..3dbfc99e 100644 --- a/docs/catalogs/bundles.rst +++ b/docs/catalogs/bundles.rst @@ -1,5 +1,5 @@ -Creating catalog provider bundles ---------------------------------- +Catalog provider bundles +------------------------ ``di.DeclarativeCatalog.Bundle`` is a limited collection of catalog providers. While catalog could be used as a centralized place for particular providers diff --git a/docs/catalogs/declarative.rst b/docs/catalogs/declarative.rst new file mode 100644 index 00000000..d3efc0b6 --- /dev/null +++ b/docs/catalogs/declarative.rst @@ -0,0 +1,65 @@ +Declarative catalogs +-------------------- + +``di.DeclarativeCatalog`` is a catalog of providers that could be defined in +declarative manner. It should cover most of the cases when list of providers +that would be included in catalog is deterministic (catalog will not change +its structure in runtime). + +Definition of declarative catalogs +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Declarative catalogs have to extend base declarative catalog class - +``di.DeclarativeCatalog``. + +Providers have to be defined like catalog's class attributes. Every provider in +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: di.Provider -> Object1"""`` + docstrings just on the next line after provider's definition. It will + help code analyzing tools and IDE's to understand that variable above + contains some callable object, that returns particular instance as a + result of its call. + +Here is an simple example of declarative catalog with several factories: + +.. image:: /images/catalogs/declarative.png + :width: 85% + :align: center + +.. literalinclude:: ../../examples/catalogs/declarative.py + :language: python + +Declarative catalogs API +~~~~~~~~~~~~~~~~~~~~~~~~ + +``di.DeclarativeCatalog`` has several features that could be useful for some +kind of operations on catalog's providers: + +- ``di.DeclarativeCatalog.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.DeclarativeCatalog.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.DeclarativeCatalog.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.DeclarativeCatalog.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.DeclarativeCatalog.filter()`` method use + ``di.DeclarativeCatalog.providers``. + +Example: + +.. image:: /images/catalogs/declarative_api.png + :width: 100% + :align: center + +.. literalinclude:: ../../examples/catalogs/declarative_api.py + :language: python diff --git a/docs/catalogs/dynamic.rst b/docs/catalogs/dynamic.rst new file mode 100644 index 00000000..e10c951e --- /dev/null +++ b/docs/catalogs/dynamic.rst @@ -0,0 +1,2 @@ +Dynamic catalogs +---------------- diff --git a/docs/catalogs/index.rst b/docs/catalogs/index.rst index cfc3d579..24faa91e 100644 --- a/docs/catalogs/index.rst +++ b/docs/catalogs/index.rst @@ -19,7 +19,7 @@ of providers. .. toctree:: :maxdepth: 2 - writing - operating + declarative + dynamic bundles overriding diff --git a/docs/catalogs/operating.rst b/docs/catalogs/operating.rst deleted file mode 100644 index 1841c4a3..00000000 --- a/docs/catalogs/operating.rst +++ /dev/null @@ -1,30 +0,0 @@ -Operating with catalogs ------------------------ - -``di.DeclarativeCatalog`` has several features that could be useful for some -kind of operations on catalog's providers: - -- ``di.DeclarativeCatalog.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.DeclarativeCatalog.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.DeclarativeCatalog.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.DeclarativeCatalog.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.DeclarativeCatalog.filter()`` method use - ``di.DeclarativeCatalog.providers``. - -Example: - -.. image:: /images/catalogs/operating_with_providers.png - :width: 100% - :align: center - -.. literalinclude:: ../../examples/catalogs/operating_with_providers.py - :language: python diff --git a/docs/catalogs/writing.rst b/docs/catalogs/writing.rst deleted file mode 100644 index c6ee929f..00000000 --- a/docs/catalogs/writing.rst +++ /dev/null @@ -1,25 +0,0 @@ -Writing catalogs ----------------- - -Catalogs have to extend base catalog class ``di.DeclarativeCatalog``. - -Providers have to be defined like catalog's attributes. Every provider in -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: di.Provider -> Object1"""`` - docstrings just on the next line after provider's definition. It will - help code analyzing tools and IDE's to understand that variable above - contains some callable object, that returns particular instance as a - result of its call. - -Here is an simple example of catalog with several factories: - -.. image:: /images/catalogs/writing_catalogs.png - :width: 85% - :align: center - -.. literalinclude:: ../../examples/catalogs/writing_catalogs.py - :language: python diff --git a/docs/conf.py b/docs/conf.py index b4abe519..c225b114 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -28,7 +28,7 @@ import re # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = [] +extensions = ['sphinx.ext.autodoc'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] diff --git a/docs/images/catalogs/declarative.png b/docs/images/catalogs/declarative.png new file mode 100644 index 00000000..eaefa8fc Binary files /dev/null and b/docs/images/catalogs/declarative.png differ diff --git a/docs/images/catalogs/declarative_api.png b/docs/images/catalogs/declarative_api.png new file mode 100644 index 00000000..79cbafd6 Binary files /dev/null and b/docs/images/catalogs/declarative_api.png differ diff --git a/docs/images/catalogs/writing_catalogs.png b/docs/images/catalogs/writing_catalogs.png deleted file mode 100644 index fdc84ec5..00000000 Binary files a/docs/images/catalogs/writing_catalogs.png and /dev/null differ diff --git a/docs/providers/custom.rst b/docs/providers/custom.rst index 2d5374e8..1b3d0fd9 100644 --- a/docs/providers/custom.rst +++ b/docs/providers/custom.rst @@ -1,4 +1,4 @@ -Writing custom providers +Writing of custom providers ------------------------ List of *Dependency Injector* providers could be widened with custom providers. diff --git a/examples/catalogs/writing_catalogs.py b/examples/catalogs/declarative.py similarity index 92% rename from examples/catalogs/writing_catalogs.py rename to examples/catalogs/declarative.py index ebb89746..8d22778f 100644 --- a/examples/catalogs/writing_catalogs.py +++ b/examples/catalogs/declarative.py @@ -1,4 +1,4 @@ -"""Catalog example.""" +"""Declarative catalog example.""" import dependency_injector as di diff --git a/examples/catalogs/operating_with_providers.py b/examples/catalogs/declarative_api.py similarity index 95% rename from examples/catalogs/operating_with_providers.py rename to examples/catalogs/declarative_api.py index ebbac118..0b055491 100644 --- a/examples/catalogs/operating_with_providers.py +++ b/examples/catalogs/declarative_api.py @@ -1,4 +1,4 @@ -"""Operating with catalog providers example.""" +"""Declarative catalog API example.""" import dependency_injector as di