From ca986698e952a4c085139e8156ab3f494e6956a1 Mon Sep 17 00:00:00 2001 From: Roman Mogylatov Date: Thu, 3 Sep 2020 16:19:40 -0400 Subject: [PATCH] Update key features page and remove structure page --- README.rst | 2 +- docs/containers/index.rst | 2 ++ docs/images/internals.png | Bin 8260 -> 0 bytes docs/index.rst | 47 +++++++++++++++++++++------ docs/introduction/index.rst | 1 - docs/introduction/key_features.rst | 28 +++++++++------- docs/introduction/structure.rst | 50 ----------------------------- docs/main/changelog.rst | 2 ++ docs/providers/configuration.rst | 2 ++ 9 files changed, 60 insertions(+), 74 deletions(-) delete mode 100644 docs/images/internals.png delete mode 100644 docs/introduction/structure.rst diff --git a/README.rst b/README.rst index 9604c0ee..7128b6b9 100644 --- a/README.rst +++ b/README.rst @@ -52,7 +52,7 @@ What is ``Dependency Injector``? ``Dependency Injector`` is a dependency injection framework for Python. -It helps you in implementing the dependency injection principle. +It helps you implementing the dependency injection principle. What is dependency injection? ----------------------------- diff --git a/docs/containers/index.rst b/docs/containers/index.rst index 1e5d7c33..c1abec16 100644 --- a/docs/containers/index.rst +++ b/docs/containers/index.rst @@ -1,3 +1,5 @@ +.. _containers: + Containers ========== diff --git a/docs/images/internals.png b/docs/images/internals.png deleted file mode 100644 index f49ecc8db6710bd13aebd91cc7d13a665671b343..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 8260 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 diff --git a/docs/index.rst b/docs/index.rst index 168ef255..409df690 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -64,22 +64,49 @@ Dependency Injector --- Dependency injection framework for Python ``Dependency Injector`` is a dependency injection framework for Python. -It stands on two principles: +It helps implementing the dependency injection principle. -- Explicit is better than implicit (PEP20). -- Do no magic to your code. +Key features of the ``Dependency Injector``: -How does it different from the other frameworks? +- **Providers**. Provides ``Factory``, ``Singleton``, ``Callable``, ``Coroutine``, ``Object``, + ``List``, ``Configuration``, ``Dependency`` and ``Selector`` providers that help assembling your + objects. See :ref:`providers`. +- **Overriding**. Can override any provider by another provider on the fly. This helps in testing + and configuring dev / stage environment to replace API clients with stubs etc. See + :ref:`provider-overriding`. +- **Configuration**. Read configuration from ``yaml`` & ``ini`` files, environment variables + and dictionaries. See :ref:`configuration-provider`. +- **Containers**. Provides declarative and dynamic containers. See :ref:`containers`. +- **Performance**. Written in ``Cython``. +- **Maturity**. Mature and ready for production. -- **No autowiring.** The framework does NOT do any autowiring / autoresolving of the dependencies. You need to specify everything explicitly. Because *"Explicit is better than implicit" (PEP20)*. -- **Does not pollute your code.** Your application does NOT know and does NOT depend on the framework. No ``@inject`` decorators, annotations, patching or any other magic tricks. +.. code-block:: python -``Dependency Injector`` makes a simple contract with you: + from dependency_injector import containers, providers -- You tell the framework how to assemble your objects -- The framework does it for you -The power of the ``Dependency Injector`` is in its simplicity and straightforwardness. It is a simple tool for the powerful concept. + class Container(containers.DeclarativeContainer): + + config = providers.Configuration() + + api_client = providers.Singleton( + ApiClient, + api_key=config.api_key, + timeout=config.timeout.as_int(), + ) + + service = providers.Factory( + Service, + api_client=api_client, + ) + + + if __name__ == '__main__': + container = Container() + container.config.api_key.from_env('API_KEY') + container.config.timeout.from_env('TIMEOUT') + + service = container.service() With the ``Dependency Injector`` you keep **application structure in one place**. This place is called **the container**. You use the container to manage all the components of the diff --git a/docs/introduction/index.rst b/docs/introduction/index.rst index 3e7ce7cc..0c3588de 100644 --- a/docs/introduction/index.rst +++ b/docs/introduction/index.rst @@ -17,4 +17,3 @@ dependency injection pattern, inversion of control principle and what_is_di di_in_python key_features - structure diff --git a/docs/introduction/key_features.rst b/docs/introduction/key_features.rst index bceb6e93..21e97331 100644 --- a/docs/introduction/key_features.rst +++ b/docs/introduction/key_features.rst @@ -6,25 +6,32 @@ Key features :description: This article describes key features of the Dependency Injector framework. -``Dependency Injector`` is a dependency injection framework for Python. It takes the -responsibility of assembling your objects. +Key features of the ``Dependency Injector``: -Key features of the ``Dependency Injector`` are: +- **Providers**. Provides ``Factory``, ``Singleton``, ``Callable``, ``Coroutine``, ``Object``, + ``List``, ``Configuration``, ``Dependency`` and ``Selector`` providers that help assembling your + objects. See :ref:`providers`. +- **Overriding**. Can override any provider by another provider on the fly. This helps in testing + and configuring dev / stage environment to replace API clients with stubs etc. See + :ref:`provider-overriding`. +- **Configuration**. Read configuration from ``yaml`` & ``ini`` files, environment variables + and dictionaries. See :ref:`configuration-provider`. +- **Containers**. Provides declarative and dynamic containers. See :ref:`containers`. +- **Performance**. Written in ``Cython``. +- **Maturity**. Mature and ready for production. -- **Pythonic design**. Simple & explicit. -- **High performance**. Written in ``Cython``. -- **Maturity and production readiness**. Downloaded over 200.000 times a month. - -It stands on two principles: +The framework stands on two principles: - **Explicit is better than implicit (PEP20)**. - **Do not do any magic to your code**. -How is the ``Dependency Injector`` different from the other frameworks? +How is that different from the other frameworks? - **No autowiring.** The framework does NOT do any autowiring / autoresolving of the dependencies. You need to specify everything explicitly. Because *"Explicit is better than implicit" (PEP20)*. - **Does not pollute your code.** Your application does NOT know and does NOT depend on the framework. No ``@inject`` decorators, annotations, patching or any other magic tricks. +The power of the framework is in a simplicity. ``Dependency Injector`` is a simple tool for the powerful concept. + In addition ``Dependency Injector`` is: - Tested. @@ -33,7 +40,4 @@ In addition ``Dependency Injector`` is: - Semantically versioned. - Distributed as pre-compiled wheels. -The power of the ``Dependency Injector`` is in its straightforwardness. It is a simple tool for -the powerful concept. - .. disqus:: diff --git a/docs/introduction/structure.rst b/docs/introduction/structure.rst deleted file mode 100644 index 195b3d39..00000000 --- a/docs/introduction/structure.rst +++ /dev/null @@ -1,50 +0,0 @@ -Structure of Dependency Injector --------------------------------- - -.. meta:: - :keywords: Python,DI,Dependency injection,IoC,Inversion of Control - :description: This article describes "Dependency Injector" framework - components and their interaction between each other. - Providers and containers are the former components of - the framework. - -Current section describes *Dependency Injector* main entities and their -interaction between each other. - -.. image:: /images/internals.png - :width: 100% - :align: center - -There are 2 main entities: providers & containers. - -Providers -~~~~~~~~~ - -Providers are strategies of accessing objects. For example, -:py:class:`dependency_injector.providers.Factory` creates new instance -of provided class every time it is called. -:py:class:`dependency_injector.providers.Singleton` creates provided -instance once and returns it on every next call. Base class is - -:py:class:`dependency_injector.providers.Provider`. - -Providers could be: - -+ Injected into each other. -+ Overridden by each other. -+ Extended. - -Containers -~~~~~~~~~~ - -Containers are collections of providers. They are used for grouping -of providers by some principles. Base class is - -:py:class:`dependency_injector.containers.DeclarativeContainer`. - -Containers could be: - -+ Overridden by each other. -+ Copied from each other. -+ Extended. - - -.. disqus:: diff --git a/docs/main/changelog.rst b/docs/main/changelog.rst index 6e5d20f2..2dde548e 100644 --- a/docs/main/changelog.rst +++ b/docs/main/changelog.rst @@ -9,7 +9,9 @@ follows `Semantic versioning`_ Development version ------------------- +- Update index documentation page. - Update "Key Features" documentation page. +- Remove "Structure of Dependency Injector" documentation page. 3.36.0 ------ diff --git a/docs/providers/configuration.rst b/docs/providers/configuration.rst index 9d049e18..0ce046e6 100644 --- a/docs/providers/configuration.rst +++ b/docs/providers/configuration.rst @@ -1,3 +1,5 @@ +.. _configuration-provider: + Configuration provider ======================