Update README.rst (#279)

* Make the message direct
* Emphasise the differences
* Change example code
* Add FAQ

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,133 +82,145 @@ 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):
+   class ApplicationContainer(containers.DeclarativeContainer):
-        """Application container."""
 
-        app = flask.Application(Flask, __name__)
+       config = providers.Configuration()
 
-        bootstrap = flask.Extension(Bootstrap)
+       configure_logging = providers.Callable(
+           logging.basicConfig,
+           stream=sys.stdout,
+           level=config.log.level,
+           format=config.log.format,
+       )
 
-        config = providers.Configuration()
+       http_client = providers.Factory(http.HttpClient)
 
-        github_client = providers.Factory(
+       example_monitor = providers.Factory(
-            Github,
+           monitors.HttpMonitor,
-            login_or_token=config.github.auth_token,
+           http_client=http_client,
-            timeout=config.github.request_timeout,
+           options=config.monitors.example,
-        )
+       )
 
-        search_service = providers.Factory(
+       httpbin_monitor = providers.Factory(
-            services.SearchService,
+           monitors.HttpMonitor,
-            github_client=github_client,
+           http_client=http_client,
-        )
+           options=config.monitors.httpbin,
+       )
 
-        index_view = flask.View(
+       dispatcher = providers.Factory(
-            views.index,
+           dispatcher.Dispatcher,
-            search_service=search_service,
+           monitors=providers.List(
-            default_query=config.search.default_query,
+               example_monitor,
-            default_limit=config.search.default_limit,
+               httpbin_monitor,
-        )
+           ),
+       )
 
-Running such container looks like this:
+Example of running of such application:
 
 .. code-block:: python
 
-    from .containers import ApplicationContainer
+   from .containers import ApplicationContainer
 
 
-    def create_app():
+   def main() -> None:
-        """Create and return Flask application."""
+       container = ApplicationContainer()
-        container = ApplicationContainer()
-        container.config.from_yaml('config.yml')
-        container.config.github.auth_token.from_env('GITHUB_TOKEN')
 
-        app = container.app()
+       container.config.from_yaml('config.yml')
-        app.container = container
+       container.configure_logging()
 
-        bootstrap = container.bootstrap()
+       dispatcher = container.dispatcher()
-        bootstrap.init_app(app)
+       dispatcher.run()
-
-        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
-----------------
+==========================
 
-- Open a `Github Issue <https://github.com/ets-labs/python-dependency-injector/issues>`_
+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>`_
-
-- 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``
-- |star| Star the ``Dependency Injector`` on the `Github <https://github.com/ets-labs/python-dependency-injector/>`_
+ - |tell| Tell your friend about the ``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
-- |fork| Fork the project
-- |pull| Open a pull request to the ``develop`` branch
 
 .. _PyPi: https://pypi.org/project/dependency-injector/