Merge branch 'release/3.29.0' into master

README.rst

@@ -52,10 +52,25 @@ What is ``Dependency Injector``?
 
 ``Dependency Injector`` is a dependency injection framework for Python.
 
-Why do I need it?
+It stands on two principles:
-=================
 
-``Dependency Injector`` helps you understand and change the structure of the application.
+- Explicit is better than implicit (PEP20).
+- Do no magic to your code.
+
+How does it 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.
+
+``Dependency Injector`` makes a simple contract with you:
+
+- You tell the framework how to build you code
+- 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.
+
+Example
+=======
 
 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
@@ -67,131 +82,143 @@ the application structure. It is **easy to understand and change** it.
 
 *The container is like a map of your application. You always know what depends on what.*
 
-``Flask`` + ``Dependency Injector`` example application container:
+Example application container:
 
 .. code-block:: python
 
-    from dependency_injector import containers, providers
+   import logging
-    from dependency_injector.ext import flask
+   import sys
-    from flask import Flask
-    from flask_bootstrap import Bootstrap
-    from github import Github
 
-    from . import views, services
+   from dependency_injector import containers, providers
+
+   from . import http, monitors, dispatcher
 
 
    class ApplicationContainer(containers.DeclarativeContainer):
-        """Application container."""
-
-        app = flask.Application(Flask, __name__)
-
-        bootstrap = flask.Extension(Bootstrap)
 
        config = providers.Configuration()
 
-        github_client = providers.Factory(
+       configure_logging = providers.Callable(
-            Github,
+           logging.basicConfig,
-            login_or_token=config.github.auth_token,
+           stream=sys.stdout,
-            timeout=config.github.request_timeout,
+           level=config.log.level,
+           format=config.log.format,
        )
 
-        search_service = providers.Factory(
+       http_client = providers.Factory(http.HttpClient)
-            services.SearchService,
+
-            github_client=github_client,
+       example_monitor = providers.Factory(
+           monitors.HttpMonitor,
+           http_client=http_client,
+           options=config.monitors.example,
        )
 
-        index_view = flask.View(
+       httpbin_monitor = providers.Factory(
-            views.index,
+           monitors.HttpMonitor,
-            search_service=search_service,
+           http_client=http_client,
-            default_query=config.search.default_query,
+           options=config.monitors.httpbin,
-            default_limit=config.search.default_limit,
        )
 
-Running such container looks like this:
+       dispatcher = providers.Factory(
+           dispatcher.Dispatcher,
+           monitors=providers.List(
+               example_monitor,
+               httpbin_monitor,
+           ),
+       )
+
+Example of running of such application:
 
 .. code-block:: python
 
    from .containers import ApplicationContainer
 
 
-    def create_app():
+   def main() -> None:
-        """Create and return Flask application."""
        container = ApplicationContainer()
+
        container.config.from_yaml('config.yml')
-        container.config.github.auth_token.from_env('GITHUB_TOKEN')
+       container.configure_logging()
 
-        app = container.app()
+       dispatcher = container.dispatcher()
-        app.container = container
+       dispatcher.run()
-
-        bootstrap = container.bootstrap()
-        bootstrap.init_app(app)
-
-        app.add_url_rule('/', view_func=container.index_view.as_view())
-
-        return app
-
-And testing looks like:
-
-.. code-block:: python
-
-    from unittest import mock
-
-    import pytest
-    from github import Github
-    from flask import url_for
-
-    from .application import create_app
 
 
-    @pytest.fixture
+   if __name__ == '__main__':
-    def app():
+       main()
-        return create_app()
 
+Tutorials
+=========
 
-    def test_index(client, app):
+Tutorial is a good point to start.
-        github_client_mock = mock.Mock(spec=Github)
-        # Configure mock
 
-        with app.container.github_client.override(github_client_mock):
+Choose one of the following:
-            response = client.get(url_for('index'))
 
-        assert response.status_code == 200
+- `Flask web application tutorial <http://python-dependency-injector.ets-labs.org/tutorials/flask.html>`_
-        # Do more asserts
+- `Aiohttp REST API tutorial <http://python-dependency-injector.ets-labs.org/tutorials/aiohttp.html>`_
+- `Asyncio monitoring daemon tutorial <http://python-dependency-injector.ets-labs.org/tutorials/asyncio-daemon.html>`_
 
-See complete example here - `Flask + Dependency Injector Example <https://github.com/ets-labs/python-dependency-injector/tree/master/examples/miniapps/ghnav-flask>`_
+Installation
-
+============
-How to install?
----------------
 
 - The package is available on the `PyPi`_::
 
     pip install dependency-injector
 
-Where is the docs?
+Documentation
-------------------
+=============
 
 - The documentation is available on the `Read The Docs <http://python-dependency-injector.ets-labs.org/>`_
 
-Have a question?
+Frequently asked questions
-----------------
+==========================
 
+What is the dependency injection?
+ - dependency injection is a principle that decreases coupling and increases cohesion
+
+Why should I do the dependency injection?
+ - your code becomes more flexible, testable and clear
+ - you have no problems when you need to understand how it works or change it 😎 
+
+How do I start doing the dependency injection?
+ - you start writing the code following the dependency injection principle
+ - you register all of your application components and their dependencies in the container
+ - when you need a component, you get it from the container
+
+Why do I need a framework for this?
+ - you need the framework for this to not create it by your own
+ - this framework gives you the container and the providers
+ - the container is like a dictionary with the batteries 🔋 
+ - the providers manage the lifetime of your components, you will need factories, singletons, smart config object etc
+
+What price do I pay and what do I get?
+ - you need to explicitly specify the dependencies in the container
+ - it will be extra work in the beginning
+ - it will payoff when project grows or in two weeks 😊 (when you forget what project was about)
+
+What features does the framework have?
+ - building objects graph
+ - smart configuration object
+ - providers: factory, singleton, thread locals registers, etc
+ - positional and keyword context injections
+ - overriding of the objects in any part of the graph
+
+What features the framework does NOT have?
+ - autowiring / autoresolving of the dependencies
+ - the annotations and ``@inject``-like decorators
+
+Have a question?
  - Open a `Github Issue <https://github.com/ets-labs/python-dependency-injector/issues>`_
 
 Found a bug?
-------------
-
  - Open a `Github Issue <https://github.com/ets-labs/python-dependency-injector/issues>`_
 
 Want to help?
--------------
-
  - |star| Star the ``Dependency Injector`` on the `Github <https://github.com/ets-labs/python-dependency-injector/>`_
  - |new| Start a new project with the ``Dependency Injector``
  - |tell| Tell your friend about the ``Dependency Injector``
 
 Want to contribute?
--------------------
-
  - |fork| Fork the project
  - |pull| Open a pull request to the ``develop`` branch
 

docs/index.rst

@@ -64,7 +64,22 @@ Dependency Injector --- Dependency injection framework for Python
 
 ``Dependency Injector`` is a dependency injection framework for Python.
 
-It helps you understand and change the structure of the application.
+It stands on two principles:
+
+- Explicit is better than implicit (PEP20).
+- Do no magic to your code.
+
+How does it 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.
+
+``Dependency Injector`` makes a simple contract with you:
+
+- You tell the framework how to build you code
+- 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.
 
 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

docs/introduction/key_features.rst

@@ -13,6 +13,23 @@ 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.
 
+It stands on two principles:
+
+- Explicit is better than implicit (PEP20).
+- Do no magic to your code.
+
+How does it 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.
+
+``Dependency Injector`` makes a simple contract with you:
+
+- You tell the framework how to build you code
+- 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.
+
 The key features of the ``Dependency Injector`` framework are:
 
 + Easy, smart, and Pythonic style.

docs/main/changelog.rst

@@ -7,6 +7,14 @@ that were made in every particular version.
 From version 0.7.6 *Dependency Injector* framework strictly 
 follows `Semantic versioning`_
 
+3.29.0
+------
+- Update README with the more direct message on what is ``Dependency Injector`` and how is it
+  different from the other frameworks.
+- Change the example code in the README.
+- Add FAQ to the README.
+- Update documentation key features and index pages.
+
 3.28.1
 ------
 - Fix typos in the ``asyncio`` + ``Dependency Injector`` monitoring daemon tutorial.

src/dependency_injector/__init__.py

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