Merge branch 'release/3.22.0' into master

README.rst

@@ -55,10 +55,12 @@ What is ``Dependency Injector``?
 Why do I need it?
 =================
 
-``Dependency Injector`` helps you improve application structure.
+``Dependency Injector`` helps you understand and change the structure of the application.
 
 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 application. All the component dependencies are defined explicitly. This provides the control on the application structure. It is **easy to understand and change** it.
+This place is called **the container**. You use the container to manage all the components of the
+application. All the component dependencies are defined explicitly. This provides the control on
+the application structure. It is **easy to understand and change** it.
 
 .. figure:: https://raw.githubusercontent.com/wiki/ets-labs/python-dependency-injector/img/di-map.svg
    :target: https://github.com/ets-labs/python-dependency-injector
@@ -72,6 +74,7 @@ This place is called **the container**. You use the container to manage all the
     from dependency_injector import containers, providers
     from dependency_injector.ext import flask
     from flask import Flask
+    from flask_bootstrap import Bootstrap
     from github import Github
 
     from . import views, services
@@ -82,6 +85,8 @@ This place is called **the container**. You use the container to manage all the
 
         app = flask.Application(Flask, __name__)
 
+        bootstrap = flask.Extension(Bootstrap)
+
         config = providers.Configuration()
 
         github_client = providers.Factory(
@@ -118,6 +123,9 @@ Running such container looks like this:
         app = container.app()
         app.container = container
 
+        bootstrap = container.bootstrap()
+        bootstrap.init_app(app)
+
         app.add_url_rule('/', view_func=container.index_view.as_view())
 
         return app

docs/api/containers.rst

@@ -1,5 +1,5 @@
-``dependency_injector.containers``
+dependency_injector.containers
-----------------------------------
+==============================
 
 .. automodule:: dependency_injector.containers
    :members:

docs/api/errors.rst

@@ -1,5 +1,5 @@
-``dependency_injector.errors``
+dependency_injector.errors
-------------------------------
+==========================
 
 .. automodule:: dependency_injector.errors
    :members:

docs/api/flaskext.rst

@@ -1,5 +1,5 @@
-``dependency_injector.ext.flask``
+dependency_injector.ext.flask
----------------------------------
+=============================
 
 .. automodule:: dependency_injector.ext.flask
    :members:

docs/api/providers.rst

@@ -1,5 +1,5 @@
-``dependency_injector.providers``
+dependency_injector.providers
----------------------------------
+=============================
 
 .. automodule:: dependency_injector.providers
    :members:

docs/api/top_level.rst

@@ -1,5 +1,5 @@
-``dependency_injector``
+dependency_injector
------------------------
+===================
 
 .. automodule:: dependency_injector
    :members: __version__

docs/conf.py

@@ -15,6 +15,7 @@
 import os
 import re
 import sys
+import alabaster
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -29,8 +30,11 @@ sys.path.insert(0, os.path.abspath('..'))
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['sphinx.ext.autodoc',
+extensions = [
-              'sphinxcontrib.disqus']
+    'alabaster',
+    'sphinx.ext.autodoc',
+    'sphinxcontrib.disqus',
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -112,7 +116,8 @@ todo_include_todos = False
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'sphinx_rtd_theme'
+# html_theme = 'sphinx_rtd_theme'
+html_theme = 'alabaster'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -120,7 +125,7 @@ html_theme = 'sphinx_rtd_theme'
 # html_context = {}
 
 # Add any paths that contain custom themes here, relative to this directory.
-#html_theme_path = ['_themes']
+html_theme_path = [alabaster.get_path()]
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
@@ -291,6 +296,13 @@ autodoc_member_order = 'bysource'
 
 disqus_shortname = 'python-dependency-injector'
 
-
+html_theme_options = {
-def setup(app):
+    'github_user': 'ets-labs',
-    app.add_css_file('sphinx_rtd_theme-hotfix.css')
+    'github_repo': 'python-dependency-injector',
+    'github_type': 'star',
+    'github_button': True,
+    'github_banner': True,
+    'logo': 'logo.svg',
+    'description': 'Dependency injection framework for Python',
+    'code_font_size': '10pt',
+}

docs/containers/declarative.rst

@@ -32,7 +32,6 @@ factories:
 
 .. literalinclude:: ../../examples/containers/declarative.py
    :language: python
-   :linenos:
 
 Example of declarative containers inheritance:
 
@@ -42,7 +41,6 @@ Example of declarative containers inheritance:
 
 .. literalinclude:: ../../examples/containers/declarative_inheritance.py
    :language: python
-   :linenos:
 
 Example of declarative containers's provider injections:
 
@@ -52,7 +50,6 @@ Example of declarative containers's provider injections:
 
 .. literalinclude:: ../../examples/containers/declarative_injections.py
    :language: python
-   :linenos:
 
 
 .. disqus::

docs/containers/dynamic.rst

@@ -17,14 +17,12 @@ Here is an simple example of defining dynamic container with several factories:
 
 .. literalinclude:: ../../examples/containers/dynamic.py
    :language: python
-   :linenos:
 
 Next example demonstrates creation of dynamic container based on some 
 configuration:
 
 .. literalinclude:: ../../examples/containers/dynamic_runtime_creation.py
    :language: python
-   :linenos:
 
 
 .. disqus::

docs/containers/overriding.rst

@@ -18,13 +18,11 @@ method:
 
 .. literalinclude:: ../../examples/containers/override_declarative.py
    :language: python
-   :linenos:
 
 Example of overriding container using :py:func:`override` decorator:
 
 .. literalinclude:: ../../examples/containers/override_declarative_decorator.py
    :language: python
-   :linenos:
 
 Also there are several useful :py:class:`DeclarativeContainer` methods and 
 properties that help to work with container overridings:

docs/containers/specialization.rst

@@ -14,14 +14,12 @@ for limitation of its provided type:
 
 .. literalinclude:: ../../examples/containers/declarative_provider_type.py
    :language: python
-   :linenos:
 
 Limitation for providers type could be used with :py:class:`DynamicContainer` 
 as well:
 
 .. literalinclude:: ../../examples/containers/dynamic_provider_type.py
    :language: python
-   :linenos:
 
 
 .. disqus::

docs/examples/bundles_miniapp.rst

@@ -37,7 +37,6 @@ Listing of ``bundles/users/__init__.py``:
 
 .. literalinclude:: ../../examples/miniapps/bundles/bundles/users/__init__.py
    :language: python
-   :linenos:
 
 .. note::
 
@@ -47,7 +46,6 @@ Listing of ``bundles/photos/__init__.py``:
 
 .. literalinclude:: ../../examples/miniapps/bundles/bundles/photos/__init__.py
    :language: python
-   :linenos:
 
 .. note::
 
@@ -65,7 +63,6 @@ Listing of ``run.py``:
 
 .. literalinclude:: ../../examples/miniapps/bundles/run.py
    :language: python
-   :linenos:
 
 Links
 ~~~~~

docs/examples/chained_factories.rst

@@ -10,14 +10,12 @@ Listing of ``data.py``, demonstrates sample classes structure:
 
 .. literalinclude:: ../../examples/miniapps/factory_patterns/data.py
    :language: python
-   :linenos:
 
 Listing of ``chained_factories.py``, demonstrates "Chained Factories"
 pattern and provide some explanation:
 
 .. literalinclude:: ../../examples/miniapps/factory_patterns/chained_factories.py
    :language: python
-   :linenos:
 
 
 .. disqus::

docs/examples/factory_of_factories.rst

@@ -9,14 +9,12 @@ Listing of ``data.py``, demonstrates sample classes structure:
 
 .. literalinclude:: ../../examples/miniapps/factory_patterns/data.py
    :language: python
-   :linenos:
 
 Listing of ``factory_of_factories.py``, demonstrates "Chained Factories"
 pattern and provide some explanation:
 
 .. literalinclude:: ../../examples/miniapps/factory_patterns/factory_of_factories.py
    :language: python
-   :linenos:
 
 
 .. disqus::

docs/examples/movie_lister.rst

@@ -70,7 +70,6 @@ Listing of ``movies/__init__.py``:
 
 .. literalinclude:: ../../examples/miniapps/movie_lister/movies/__init__.py
    :language: python
-   :linenos:
 
 Example application
 ~~~~~~~~~~~~~~~~~~~
@@ -88,13 +87,11 @@ Listing of ``examples/main.py``:
 
 .. literalinclude:: ../../examples/miniapps/movie_lister/example/main.py
    :language: python
-   :linenos:
 
 Listing of ``examples/db.py``:
 
 .. literalinclude:: ../../examples/miniapps/movie_lister/example/db.py
    :language: python
-   :linenos:
 
 Csv application
 ~~~~~~~~~~~~~~~
@@ -103,7 +100,6 @@ Listing of ``app_csv.py``:
 
 .. literalinclude:: ../../examples/miniapps/movie_lister/app_csv.py
    :language: python
-   :linenos:
 
 Database application
 ~~~~~~~~~~~~~~~~~~~~
@@ -112,7 +108,6 @@ Listing of ``app_db.py``:
 
 .. literalinclude:: ../../examples/miniapps/movie_lister/app_db.py
    :language: python
-   :linenos:
 
 Csv and database application
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -121,7 +116,6 @@ Listing of ``app_db_csv.py``:
 
 .. literalinclude:: ../../examples/miniapps/movie_lister/app_db_csv.py
    :language: python
-   :linenos:
 
 
 .. disqus::

docs/examples/password_hashing_miniapp.rst

@@ -14,6 +14,5 @@ Listing of ``example.py``:
 
 .. literalinclude:: ../../examples/miniapps/password_hashing/example.py
    :language: python
-   :linenos:
 
 .. disqus::

docs/examples/services_miniapp_v1.rst

@@ -47,13 +47,11 @@ Listing of ``example/services.py``:
 
 .. literalinclude:: ../../examples/miniapps/services_v1/example/services.py
    :language: python
-   :linenos:
 
 Listing of ``example/main.py``:
 
 .. literalinclude:: ../../examples/miniapps/services_v1/example/main.py
    :language: python
-   :linenos:
 
 IoC containers
 ~~~~~~~~~~~~~~
@@ -62,7 +60,6 @@ Listing of ``containers.py``:
 
 .. literalinclude:: ../../examples/miniapps/services_v1/containers.py
    :language: python
-   :linenos:
 
 Run application
 ~~~~~~~~~~~~~~~
@@ -71,7 +68,6 @@ Listing of ``run.py``:
 
 .. literalinclude:: ../../examples/miniapps/services_v1/run.py
    :language: python
-   :linenos:
 
 
 .. disqus::

docs/examples/services_miniapp_v2.rst

@@ -47,13 +47,11 @@ Listing of ``example/services.py``:
 
 .. literalinclude:: ../../examples/miniapps/services_v2/example/services.py
    :language: python
-   :linenos:
 
 Listing of ``example/main.py``:
 
 .. literalinclude:: ../../examples/miniapps/services_v2/example/main.py
    :language: python
-   :linenos:
 
 IoC container
 ~~~~~~~~~~~~~
@@ -62,7 +60,6 @@ Listing of ``container.py``:
 
 .. literalinclude:: ../../examples/miniapps/services_v2/container.py
    :language: python
-   :linenos:
 
 Run application
 ~~~~~~~~~~~~~~~
@@ -71,7 +68,6 @@ Listing of ``run.py``:
 
 .. literalinclude:: ../../examples/miniapps/services_v2/run.py
    :language: python
-   :linenos:
 
 
 .. disqus::

docs/examples/use_cases_miniapp.rst

@@ -29,7 +29,6 @@ Listing of ``use_cases/containers.py``:
 
 .. literalinclude:: ../../examples/miniapps/use_cases/containers.py
    :language: python
-   :linenos:
 
 Run application
 ~~~~~~~~~~~~~~~
@@ -38,7 +37,6 @@ Listing of ``run.py``:
 
 .. literalinclude:: ../../examples/miniapps/use_cases/run.py
    :language: python
-   :linenos:
 
 Instructions for running:
 

docs/index.rst

@@ -17,8 +17,6 @@ Dependency Injector --- Dependency injection framework for Python
 
 .. _index:
 
-.. figure:: https://raw.githubusercontent.com/wiki/ets-labs/python-dependency-injector/img/logo.svg
-
 .. image:: https://img.shields.io/pypi/v/dependency_injector.svg
    :target: https://pypi.org/project/dependency-injector/
    :alt: Latest Version
@@ -63,27 +61,21 @@ Dependency Injector --- Dependency injection framework for Python
    :target: https://coveralls.io/github/ets-labs/python-dependency-injector?branch=master
    :alt: Coverage Status
 
-What is ``Dependency Injector``?
+``Dependency Injector`` is a dependency injection framework for Python.
-================================
 
-``Dependency Injector`` is a dependency injection microframework for Python.
+It helps you understand and change the structure of the application.
-It was designed to be a unified and developer-friendly tool that helps
-implement a dependency injection design pattern in a formal, pretty, and
-Pythonic way.
 
-The key features of the *Dependency Injector* framework are:
+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
+application. All the component dependencies are defined explicitly. This provides the control on
+the application structure. It is **easy to understand and change** it.
 
-+ Easy, smart, and pythonic style.
+.. figure:: https://raw.githubusercontent.com/wiki/ets-labs/python-dependency-injector/img/di-map.svg
-+ Obvious and clear structure.
+   :target: https://github.com/ets-labs/python-dependency-injector
-+ Extensibility and flexibility.
-+ High performance.
-+ Memory efficiency.
-+ Thread safety.
-+ Documented.
-+ Semantically versioned.
 
-*Dependency Injector* containers and providers are implemented as C extension
+*The container is like a map of your application. You always know what depends on what.*
-types using Cython.
+
+Explore the documentation to know more about the ``Dependency Injector``.
 
 Contents
 --------
@@ -93,6 +85,7 @@ Contents
 
     introduction/index
     main/installation
+    tutorials/index
     providers/index
     containers/index
     examples/index

docs/introduction/di_in_python.rst

@@ -103,19 +103,16 @@ Listing of ``example.engines`` module:
 
 .. literalinclude:: ../../examples/miniapps/engines_cars/example/engines.py
    :language: python
-   :linenos:
 
 Listing of ``example.cars`` module:
 
 .. literalinclude:: ../../examples/miniapps/engines_cars/example/cars.py
    :language: python
-   :linenos:
 
 Next example demonstrates creation of several cars with different engines:
 
 .. literalinclude:: ../../examples/miniapps/engines_cars/example_di.py
    :language: python
-   :linenos:
 
 While previous example demonstrates advantages of dependency injection, there
 is a disadvantage demonstration as well - creation of car requires additional 
@@ -128,7 +125,6 @@ using :doc:`Dependency Injector <../index>`:
 
 .. literalinclude:: ../../examples/miniapps/engines_cars/example_ioc_containers.py
    :language: python
-   :linenos:
 
 Useful links
 ~~~~~~~~~~~~

docs/introduction/key_features.rst

@@ -1,5 +1,5 @@
-Key features of Dependency Injector
+Key features
------------------------------------
+------------
 
 .. meta::
    :keywords: Python,DI,Dependency injection,IoC,Inversion of Control
@@ -7,13 +7,16 @@ Key features of Dependency Injector
                  framework. It also provides some cases and recommendations 
                  about usage of "Dependency Injector" framework.
 
-*Dependency Injector* is a dependency injection framework for Python projects. 
-It was designed to be unified, developer-friendly tool for managing any kind
-of Python objects and their dependencies in formal, pretty way.
 
-*Dependency Injector* framework key features are:
+``Dependency Injector`` is a dependency injection framework for Python.
+It was designed to be a unified and developer-friendly tool that helps
+implement a dependency injection design pattern in a formal, pretty, and
+Pythonic way.
 
-+ Easy, smart, and pythonic style.
+The key features of the ``Dependency Injector`` framework are:
+
++ Easy, smart, and Pythonic style.
++ Does NOT pollute client code.
 + Obvious and clear structure.
 + Extensibility and flexibility.
 + High performance.
@@ -21,29 +24,28 @@ of Python objects and their dependencies in formal, pretty way.
 + Thread safety.
 + Documented.
 + Semantically versioned.
++ Distributed as pre-compiled wheels.
 
-*Dependency Injector* framework could be used in different application types:
+``Dependency Injector`` containers and providers are implemented as C extension
+types using ``Cython``.
 
-+ Web applications based on Flask, Django or any other web framework.
+``Dependency Injector`` framework can be used in the different application types:
-+ Asynchronous applications based on asyncio, Tornado and Twisted.
+
++ Web applications based on the ``Flask``, ``Django`` or any other web framework.
++ Asynchronous applications ``asyncio``, ``aiohttp``, ``Tornado``, or ``Twisted``.
 + Standalone frameworks and libraries.
 + GUI applications.
 
-*Dependency Injector* framework could be integrated on different project 
+``Dependency Injector`` framework can be integrated on the different project
 stages:
 
-+ It could be used in the beginning of development of new applications.
++ It can be used in the beginning of the development of a new application.
-+ It could be integrated into applications that are in active development 
++ It can be integrated into application that is on its active development stage.
-  stage.
++ It can be used for refactoring of legacy application.
-+ It could be used for refactoring of legacy applications.
 
-Components of *Dependency Injector* framework could be used:
+Components of ``Dependency Injector`` framework could be used:
 
 + In composition with each other.
-+ Separately between each other.
++ Independently from each other.
-
-Main idea of *Dependency Injector* framework is to be useful tool for the 
-right thing.
-
 
 .. disqus::

docs/introduction/what_is_di.rst

@@ -83,14 +83,12 @@ Let's go through the code of ``example.py``:
 
 .. literalinclude:: ../../examples/di_demo/example.py
    :language: python
-   :linenos:
 
 At some point, things defined above mean, that the code from ``example.py``,
 could look different, like in ``example_di.py``:
 
 .. literalinclude:: ../../examples/di_demo/example_di.py
    :language: python
-   :linenos:
 
 Best explanation, ever
 ~~~~~~~~~~~~~~~~~~~~~~

docs/main/changelog.rst

@@ -7,6 +7,12 @@ that were made in every particular version.
 From version 0.7.6 *Dependency Injector* framework strictly 
 follows `Semantic versioning`_
 
+3.22.0
+------
+- Migrate docs to ``alabaster`` theme.
+- Add ``Bootstrap`` extension to the ``ghnav-flask`` example.
+- Add stubs for the tutorials to the docs.
+
 3.21.2
 ------
 - Hotfix changelog typo.

docs/providers/callable.rst

@@ -30,7 +30,6 @@ injections:
 
 .. literalinclude:: ../../examples/providers/callable_args.py
    :language: python
-   :linenos:
 
 Next one example shows usage of :py:class:`Callable` with keyword argument 
 injections:
@@ -41,7 +40,6 @@ injections:
 
 .. literalinclude:: ../../examples/providers/callable_kwargs.py
    :language: python
-   :linenos:
 
 .. _callable_providers_delegation:
 

docs/providers/configuration.rst

@@ -9,7 +9,6 @@ Configuration providers
    :language: python
    :emphasize-lines: 4,9-10
    :lines: 4-14
-   :linenos:
 
 It implements "use first, define later" principle.
 
@@ -23,13 +22,11 @@ Loading from ``ini`` file
    :language: python
    :lines: 3-5,6-
    :emphasize-lines: 6
-   :linenos:
 
 where ``examples/providers/configuration/config.ini`` is:
 
 .. literalinclude:: ../../examples/providers/configuration/config.ini
    :language: ini
-   :linenos:
 
 :py:meth:`Configuration.from_ini` supports environment variables interpolation. Use
 ``${ENV_NAME}`` format in the configuration file to substitute value of environment
@@ -45,13 +42,11 @@ Loading from ``yaml`` file
    :language: python
    :lines: 3-5,6-
    :emphasize-lines: 6
-   :linenos:
 
 where ``examples/providers/configuration/config.yml`` is:
 
 .. literalinclude:: ../../examples/providers/configuration/config.yml
    :language: ini
-   :linenos:
 
 :py:meth:`Configuration.from_yaml` supports environment variables interpolation. Use
 ``${ENV_NAME}`` format in the configuration file to substitute value of environment
@@ -73,7 +68,6 @@ Loading from ``dict``
    :language: python
    :lines: 3-5,6-
    :emphasize-lines: 6-13
-   :linenos:
 
 Loading from environment variable
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -85,7 +79,6 @@ Loading from environment variable
    :language: python
    :lines: 5-7,13-21
    :emphasize-lines: 6-8
-   :linenos:
 
 Loading from multiple sources
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -97,12 +90,10 @@ configuration is merged recursively over existing configuration.
    :language: python
    :lines: 3-5,6-14
    :emphasize-lines: 6-7
-   :linenos:
 
 where ``examples/providers/configuration/config.local.yml`` is:
 
 .. literalinclude:: ../../examples/providers/configuration/config.local.yml
    :language: ini
-   :linenos:
 
 .. disqus::

docs/providers/coroutine.rst

@@ -18,7 +18,6 @@ coroutine:
 
 .. literalinclude:: ../../examples/providers/coroutine_async_await.py
    :language: python
-   :linenos:
 
 Coroutine providers and injections
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

docs/providers/custom.rst

@@ -30,7 +30,6 @@ Example:
 
 .. literalinclude:: ../../examples/providers/custom_factory.py
    :language: python
-   :linenos:
 
 
 .. disqus::

docs/providers/dependency.rst

@@ -39,6 +39,5 @@ Example:
 
 .. literalinclude:: ../../examples/providers/dependency.py
    :language: python
-   :linenos:
 
 .. disqus::

docs/providers/factory.rst

@@ -14,7 +14,6 @@ Nothing could be better than brief example:
 
 .. literalinclude:: ../../examples/providers/factory.py
    :language: python
-   :linenos:
 
 Factory providers and __init__ injections
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -48,7 +47,6 @@ injectable values are also provided by another factories:
 
 .. literalinclude:: ../../examples/providers/factory_init_injections.py
    :language: python
-   :linenos:
 
 .. _factory_providers_delegation:
 
@@ -92,7 +90,6 @@ Example:
 
 .. literalinclude:: ../../examples/providers/factory_delegation.py
    :language: python
-   :linenos:
 
 .. _factory_providers_specialization:
 
@@ -107,7 +104,6 @@ provided type:
 
 .. literalinclude:: ../../examples/providers/factory_provided_type.py
    :language: python
-   :linenos:
 
 .. _abstract_factory_providers:
 
@@ -142,13 +138,11 @@ Listing of ``cache.py``:
 
 .. literalinclude:: ../../examples/providers/abstract_factory/cache.py
    :language: python
-   :linenos:
 
 Listing of ``example.py``:
 
 .. literalinclude:: ../../examples/providers/abstract_factory/example.py
    :language: python
-   :linenos:
 
 Factory aggregate providers
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -167,7 +161,6 @@ Next prototype might be the best demonstration of
 
 .. literalinclude:: ../../examples/providers/factory_aggregate/prototype.py
    :language: python
-   :linenos:
 
 Example below shows one of the :py:class:`FactoryAggregate` use cases, when 
 concrete implementation (game) must be selected based on dynamic input (CLI). 
@@ -176,12 +169,10 @@ Listing of ``games.py``:
 
 .. literalinclude:: ../../examples/providers/factory_aggregate/games.py
    :language: python
-   :linenos:
 
 Listing of ``example.py``:
 
 .. literalinclude:: ../../examples/providers/factory_aggregate/example.py
    :language: python
-   :linenos:
 
 .. disqus::

docs/providers/list.rst

@@ -9,7 +9,6 @@ List providers
    :language: python
    :emphasize-lines: 6-9
    :lines: 6-8, 23-29
-   :linenos:
 
 :py:class:`List` provider is needed for injecting a list of dependencies. It handles
 positional argument injections the same way as :py:class:`Factory` provider:
@@ -27,7 +26,6 @@ Full example:
    :language: python
    :emphasize-lines: 23-26
    :lines: 3-
-   :linenos:
 
 .. note::
 

docs/providers/object.rst

@@ -9,7 +9,6 @@ Example:
 
 .. literalinclude:: ../../examples/providers/object.py
    :language: python
-   :linenos:
 
 
 .. disqus::

docs/providers/overriding.rst

@@ -33,7 +33,6 @@ Example:
 
 .. literalinclude:: ../../examples/providers/overriding_simple.py
    :language: python
-   :linenos:
 
 Example:
 
@@ -43,7 +42,6 @@ Example:
 
 .. literalinclude:: ../../examples/providers/overriding_users_model.py
    :language: python
-   :linenos:
 
 
 .. disqus::

docs/providers/selector.rst

@@ -9,7 +9,6 @@ Selector providers
    :language: python
    :emphasize-lines: 6-10
    :lines: 3-5,14-20
-   :linenos:
 
 :py:class:`Selector` provider has a callable called ``selector`` and a dictionary of providers.
 
@@ -26,6 +25,5 @@ Full example:
    :language: python
    :emphasize-lines: 14-18
    :lines: 3-
-   :linenos:
 
 .. disqus::

docs/providers/singleton.rst

@@ -14,7 +14,6 @@ Example:
 
 .. literalinclude:: ../../examples/providers/singleton.py
    :language: python
-   :linenos:
 
 Singleton providers resetting
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -28,7 +27,6 @@ Example:
 
 .. literalinclude:: ../../examples/providers/singleton_resetting.py
    :language: python
-   :linenos:
 
 Singleton providers and injections
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -108,7 +106,6 @@ Example:
 
 .. literalinclude:: ../../examples/providers/singleton_thread_locals.py
    :language: python
-   :linenos:
 
 
 .. disqus::

docs/tutorials/aiohttp.rst

@@ -0,0 +1,4 @@
+Aiohttp tutorial
+================
+
+Coming soon...

docs/tutorials/asyncio.rst

@@ -0,0 +1,4 @@
+Asyncio tutorial
+================
+
+Coming soon...

docs/tutorials/flask.rst

@@ -0,0 +1,4 @@
+Flask tutorial
+==============
+
+Coming soon...

docs/tutorials/index.rst

@@ -0,0 +1,12 @@
+Tutorials
+=========
+
+This section contains tutorials that show how to apply dependency injection for popular Python
+frameworks.
+
+..  toctree::
+    :maxdepth: 2
+
+    flask
+    aiohttp
+    asyncio

examples/di_demo/example.py

@@ -2,16 +2,16 @@
 
 
 class Service:
-    """Some "Service"."""
+    """The Service."""
 
 
 class Client:
-    """Some "Client" that uses "Service"."""
+    """The Client that uses the Service."""
 
     def __init__(self):
-        """Initialize instance."""
+        """Initialize the Client."""
-        self.service = Service()  # Service instance is created inside Client
+        self.service = Service()  # The Service is created by the Client
 
 
 if __name__ == '__main__':
-    client = Client()  # Application creates Client's instance
+    client = Client()  # Application creates the Client

examples/di_demo/example_di.py

@@ -1,18 +1,18 @@
-"""The Code, that demonstrates dependency injection pattern."""
+"""The Code that demonstrates dependency injection pattern."""
 
 
 class Service:
-    """Some "Service"."""
+    """The Service."""
 
 
 class Client:
-    """Some "Client" that uses "Service"."""
+    """The Client that uses the Service."""
 
-    def __init__(self, service):  # Service instance is injected into Client
+    def __init__(self, service):  # The Service is injected into the Client
-        """Initialize instance."""
+        """Initialize the Client."""
         self.service = service
 
 
 if __name__ == '__main__':
-    service = Service()       # Application creates Service instance
+    service = Service()       # Application creates the Service
-    client = Client(service)  # and inject Service instance into the Client
+    client = Client(service)  # and inject the Service into the Client

examples/miniapps/engines_cars/example/engines.py

@@ -4,8 +4,8 @@
 class Engine:
     """Example engine base class.
 
-    Engine is a heart of every car. Engine is a very common term and could be
+    Engine is a heart of every car. Engine is a very common term and
-    implemented in very different ways.
+    could be implemented in very different ways.
     """
 
 

examples/miniapps/ghnav-flask/githubnavigator/application.py

@@ -12,6 +12,9 @@ def create_app():
     app = container.app()
     app.container = container
 
+    bootstrap = container.bootstrap()
+    bootstrap.init_app(app)
+
     app.add_url_rule('/', view_func=container.index_view.as_view())
 
     return app

examples/miniapps/ghnav-flask/githubnavigator/containers.py

@@ -3,6 +3,7 @@
 from dependency_injector import containers, providers
 from dependency_injector.ext import flask
 from flask import Flask
+from flask_bootstrap import Bootstrap
 from github import Github
 
 from . import views, services
@@ -13,6 +14,8 @@ class ApplicationContainer(containers.DeclarativeContainer):
 
     app = flask.Application(Flask, __name__)
 
+    bootstrap = flask.Extension(Bootstrap)
+
     config = providers.Configuration()
 
     github_client = providers.Factory(

examples/miniapps/ghnav-flask/githubnavigator/services.py

@@ -29,7 +29,6 @@ class SearchService:
                 'url': repository.owner.html_url,
                 'avatar_url': repository.owner.avatar_url,
             },
-            'created_at': repository.created_at,
             'latest_commit': self._format_commit(commits[0]) if commits else {},
         }
 

examples/miniapps/ghnav-flask/githubnavigator/templates/base.html

@@ -0,0 +1,26 @@
+<!doctype html>
+<html lang="en">
+    <head>
+        {% block head %}
+        <!-- Required meta tags -->
+        <meta charset="utf-8">
+        <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
+
+        {% block styles %}
+            <!-- Bootstrap CSS -->
+            {{ bootstrap.load_css() }}
+        {% endblock %}
+
+        <title>{% block title %}{% endblock %}</title>
+        {% endblock %}
+    </head>
+    <body>
+        <!-- Your page content -->
+        {% block content %}{% endblock %}
+
+        {% block scripts %}
+            <!-- Optional JavaScript -->
+            {{ bootstrap.load_js() }}
+        {% endblock %}
+    </body>
+</html>

examples/miniapps/ghnav-flask/githubnavigator/templates/index.html

@@ -1,40 +1,55 @@
-<!DOCTYPE html>
+{% extends "base.html" %}
-<html>
+
-<head>
+{% block title %}Github Navigator{% endblock %}
-    <title>Github Navigator</title>
+
-</head>
+{% block content %}
-<body>
+<div class="container">
-<h1>Github Navigator</h1>
+    <h1 class="mb-4">Github Navigator</h1>
-<form method="get">
+
+    <form>
+      <div class="form-group form-row">
+          <label for="mySearch" class="col-form-label">Search for:</label>
+          <div class="col-10">
+              <input class="form-control" type="text" id="mySearch"
+                     placeholder="Type something to search on GitHub"
+                     name="search_term"
+                     value="{{ search_term if search_term }}">
+          </div>
+      </div>
+    </form>
+
+    {% if repositories|length == 0 %}
+    <small>No search results</small>
+    {% endif %}
+
     <p>
-        Search term: <input type="text" name="search_term" value="{{ search_term if search_term }}">
+        <small>Results found: {{ repositories|length }}</small>
-        Limit: <input type="text" name="limit" value="{{ limit }}">
-        <input type="submit">
     </p>
-</form>
+
-<h2>Search results</h2>
+    <table class="table table-striped">
-{% if repositories|length == 0 %}
+        <thead>
-<small>No search results</small>
+            <tr>
-{% endif %}
+                <th>#</th>
-{% for repository in repositories %} {{n}}
+                <th>Repository</th>
-<p>
+                <th class="text-nowrap">Repository owner</th>
-    <small>Search result # {{ loop.index }} from {{ repositories|length }}</small>
+<!--                <th class="text-nowrap">Created at</th>-->
-</p>
+                <th class="text-nowrap">Last commit</th>
-<p>
+            </tr>
-    Repository: <a href="{{ repository.url }}">{{ repository.name }}</a>
+        </thead>
-</p>
+        <tbody>
-<p>
+    {% for repository in repositories %} {{n}}
-    Repository owner:
+            <tr>
-    <a href="{{ repository.owner.url }}"><img src="{{ repository.owner.avatar_url }}" alt="avatar" height="24" width="24"/></a>
+              <th>{{ loop.index }}</th>
+              <td><a href="{{ repository.url }}">{{ repository.name }}</a></td>
+              <td><a href="{{ repository.owner.url }}"><img src="{{ repository.owner.avatar_url }}" alt="avatar" height="24" width="24"/></a>
                   <a href="{{ repository.owner.url }}">{{ repository.owner.login }}</a>
-</p>
+              </td>
-<p>
+              <td><a href="{{ repository.latest_commit.url }}">{{ repository.latest_commit.sha }}</a> {{ repository.latest_commit['message'] }} {{ repository.latest_commit.author_name }}</td>
-    Created at: {{ repository.created_at }}
+            </tr>
-</p>
+    {% endfor %}
-<p>
+
-    LastCommit: <a href="{{ repository.latest_commit.url }}">{{ repository.latest_commit.sha }}</a> {{ repository.latest_commit['message'] }} {{ repository.latest_commit.author_name }}
+        </tbody>
-</p>
+    </table>
-<hr/>
+</div>
-{% endfor %}
+
-</body>
+{% endblock %}
-</html>

examples/miniapps/ghnav-flask/githubnavigator/tests.py

@@ -25,7 +25,6 @@ def test_index(client, app):
                 html_url='owner1-url',
                 avatar_url='owner1-avatar-url',
             ),
-            created_at='repo1-created-at',
             get_commits=mock.Mock(return_value=[mock.Mock()]),
         ),
         mock.Mock(
@@ -36,7 +35,6 @@ def test_index(client, app):
                 html_url='owner2-url',
                 avatar_url='owner2-avatar-url',
             ),
-            created_at='repo2-created-at',
             get_commits=mock.Mock(return_value=[mock.Mock()]),
         ),
     ]
@@ -51,14 +49,12 @@ def test_index(client, app):
     assert b'owner1-login' in response.data
     assert b'owner1-url' in response.data
     assert b'owner1-avatar-url' in response.data
-    assert b'repo1-created-at' in response.data
 
     assert b'repo2-url' in response.data
     assert b'repo2-name' in response.data
     assert b'owner2-login' in response.data
     assert b'owner2-url' in response.data
     assert b'owner2-avatar-url' in response.data
-    assert b'repo2-created-at' in response.data
 
 
 def test_index_no_results(client, app):

examples/providers/abstract_factory/example.py

@@ -10,19 +10,27 @@ cache_client_factory = providers.AbstractFactory(cache.AbstractCacheClient)
 
 if __name__ == '__main__':
     # Override abstract factory with redis client factory:
-    cache_client_factory.override(providers.Factory(cache.RedisCacheClient,
+    cache_client_factory.override(
+        providers.Factory(
+            cache.RedisCacheClient,
             host='localhost',
             port=6379,
-                                                    db=0))
+            db=0,
+        ),
+    )
     redis_cache = cache_client_factory()
-    print(redis_cache)  # <cache.RedisCacheClient object at 0x10975bc50>
+    print(redis_cache)
+    # <cache.RedisCacheClient object at 0x10975bc50>
 
     # Override abstract factory with memcache client factory:
-    cache_client_factory.override(providers.Factory(cache.MemcacheCacheClient,
+    cache_client_factory.override(
-                                                    hosts=['10.0.1.1',
+        providers.Factory(
-                                                           '10.0.1.2',
+            cache.MemcacheCacheClient,
-                                                           '10.0.1.3'],
+            hosts=['10.0.1.1', '10.0.1.2', '10.0.1.3'],
             port=11211,
-                                                    prefix='my_app'))
+            prefix='my_app',
+        ),
+    )
     memcache_cache = cache_client_factory()
-    print(memcache_cache)  # <cache.MemcacheCacheClient object at 0x10975bc90>
+    print(memcache_cache)
+    # <cache.MemcacheCacheClient object at 0x10975bc90>

examples/providers/factory_aggregate/example.py

@@ -7,9 +7,11 @@ import dependency_injector.providers as providers
 from games import Chess, Checkers, Ludo
 
 
-game_factory = providers.FactoryAggregate(chess=providers.Factory(Chess),
+game_factory = providers.FactoryAggregate(
+    chess=providers.Factory(Chess),
     checkers=providers.Factory(Checkers),
-                                          ludo=providers.Factory(Ludo))
+    ludo=providers.Factory(Ludo),
+)
 
 if __name__ == '__main__':
     game_type = sys.argv[1].lower()

examples/providers/factory_delegation.py

@@ -26,27 +26,36 @@ class User:
 
 # Defining User and Photo factories using DelegatedFactory provider:
 photos_factory = providers.DelegatedFactory(Photo)
-users_factory = providers.DelegatedFactory(User,
+users_factory = providers.DelegatedFactory(
-                                           photos_factory=photos_factory)
+    User,
+    photos_factory=photos_factory,
+)
 
 # or using Delegate(Factory(...))
 
 photos_factory = providers.Factory(Photo)
-users_factory = providers.Factory(User,
+users_factory = providers.Factory(
-                                  photos_factory=providers.Delegate(
+    User,
-                                      photos_factory))
+    photos_factory=providers.Delegate(photos_factory),
+)
 
 
 # or using Factory(...).delegate()
 
 photos_factory = providers.Factory(Photo)
-users_factory = providers.Factory(User,
+users_factory = providers.Factory(
-                                  photos_factory=photos_factory.delegate())
+    User,
+    photos_factory=photos_factory.delegate(),
+)
 
 
 # Creating several User objects:
-user1 = users_factory()  # Same as: user1 = User(photos_factory=photos_factory)
+user1 = users_factory()
-user2 = users_factory()  # Same as: user2 = User(photos_factory=photos_factory)
+user2 = users_factory()
+
+# Same as:
+# user1 = User(photos_factory=photos_factory)
+# user2 = User(photos_factory=photos_factory)
 
 # Making some asserts:
 assert isinstance(user1.main_photo, Photo)
@@ -55,13 +64,18 @@ assert isinstance(user2.main_photo, Photo)
 # or using Factory(...).provider
 
 photos_factory = providers.Factory(Photo)
-users_factory = providers.Factory(User,
+users_factory = providers.Factory(
-                                  photos_factory=photos_factory.provider)
+    User,
-
+    photos_factory=photos_factory.provider,
+)
 
 # Creating several User objects:
-user1 = users_factory()  # Same as: user1 = User(photos_factory=photos_factory)
+user1 = users_factory()
-user2 = users_factory()  # Same as: user2 = User(photos_factory=photos_factory)
+user2 = users_factory()
+
+# Same as:
+# user1 = User(photos_factory=photos_factory)
+# user2 = User(photos_factory=photos_factory)
 
 # Making some asserts:
 assert isinstance(user1.main_photo, Photo)

examples/providers/singleton.py

@@ -7,8 +7,8 @@ import dependency_injector.providers as providers
 
 UsersService = collections.namedtuple('UsersService', [])
 
-# Singleton provider creates new instance of specified class on first call and
+# Singleton provider creates new instance of specified class on first call
-# returns same instance on every next call.
+# and returns same instance on every next call.
 users_service_provider = providers.Singleton(UsersService)
 
 # Retrieving several UserService objects:

examples/providers/singleton_thread_locals.py

@@ -18,19 +18,22 @@ thread_local_object = providers.ThreadLocalSingleton(object)
 queue_factory = providers.ThreadSafeSingleton(queue.Queue)
 
 # Create callable provider for example(), inject dependencies:
-example = providers.DelegatedCallable(example,
+example = providers.DelegatedCallable(
+    example,
     example_object=thread_local_object,
-                                      queue_object=queue_factory)
+    queue_object=queue_factory,
+)
 
-# Create factory provider for threads that are targeted to execute example():
+# Create factory for threads that are targeted to execute example():
-thread_factory = providers.Factory(threading.Thread,
+thread_factory = providers.Factory(threading.Thread, target=example)
-                                   target=example)
 
 if __name__ == '__main__':
     # Create 10 threads for concurrent execution of example():
     threads = []
     for thread_number in range(10):
-        threads.append(thread_factory(name='Thread{0}'.format(thread_number)))
+        threads.append(
+            thread_factory(name='Thread{0}'.format(thread_number)),
+        )
 
     # Start execution of all created threads:
     for thread in threads:

requirements-doc.txt

@@ -1,5 +1,5 @@
 sphinx
-sphinx_rtd_theme>=0.2.5b2
+alabaster>=0.7.12
 -e git://github.com/rmk135/sphinxcontrib-disqus.git#egg=sphinxcontrib-disqus
 
 -r requirements-ext.txt

src/dependency_injector/__init__.py

@@ -1,6 +1,6 @@
 """Dependency injector top-level package."""
 
-__version__ = '3.21.2'
+__version__ = '3.22.0'
 """Version number that follows semantic versioning.
 
 :type: str