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 f49ecc8d..00000000 Binary files a/docs/images/internals.png and /dev/null differ 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 ======================