Update inject() decorator docs with positional argument injections example and some description

docs/advanced_usage/index.rst

@@ -11,10 +11,25 @@ Current section of documentation describes advanced usage of
 injections.  It *patches* decorated callable in such way that dependency 
 injection will be done during every call of decorated callable.
 
-``@di.inject()`` decorator takes keyword argument, that will be injected 
+``di.inject()`` takes a various number of positional and keyword arguments 
-during every next call of decorated callback with the same name. Any Python 
+that are used as decorated callable injections. Every time, when 
-object will be injected *as is*, except ``di.Provider``'s, which will be 
+``di.inject()`` is called, positional and keyword argument injections would be 
-called to provide injectable values.
+passed as an callable arguments.
+
+Such behaviour is very similar to the standard Python ``functools.partial`` 
+object, except of one thing: all injectable values are provided 
+*"as is"*, except of providers (subclasses of ``di.Provider``). Providers 
+will be called every time, when injection needs to be done. For example, 
+if injectable value of injection is a ``di.Factory``, it will provide new one 
+instance (as a result of its call) every time, when injection needs to be done.
+
+``di.inject()`` behaviour with context positional and keyword arguments is 
+very like a standard Python ``functools.partial``:
+
+- Positional context arguments will be appended after ``di.inject()`` 
+  positional injections.
+- Keyword context arguments have priority on ``di.inject()`` keyword 
+  injections and will be merged over them.
 
 Example:
 

docs/main/changelog.rst

@@ -16,7 +16,8 @@ Development version
 - Add images for catalog "Writing catalogs" and "Operating with catalogs" 
   examples.
 - Add functionality for using positional argument injections with 
-  ``di.Factory``, ``di.Singleton`` and ``di.Callable`` providers.
+  ``di.Factory``, ``di.Singleton``, ``di.Callable`` providers and 
+  ``di.inject`` decorator.
 - Add functionality for decorating classes with ``@di.inject``.
 - Add ``di.Singleton.injections`` attribute that represents a tuple of all 
   ``di.Singleton`` injections (including args, kwargs, attributes and methods).

examples/advanced_usage/inject_flask.py

@@ -5,8 +5,8 @@ import flask
 import dependency_injector as di
 
 
-database = di.Singleton(sqlite3.Connection,
+database = di.Singleton(sqlite3.connect,
-                        database=':memory:',
+                        ':memory:',
                         timeout=30,
                         detect_types=True,
                         isolation_level='EXCLUSIVE')
@@ -15,7 +15,7 @@ app = flask.Flask(__name__)
 
 
 @app.route('/')
-@di.inject(database=database)
+@di.inject(database)
 def hello(database):
     """Example Flask view."""
     one = database.execute('SELECT 1').fetchone()[0]

examples/advanced_usage/inject_simple.py

@@ -6,11 +6,22 @@ import dependency_injector as di
 dependency_injector_factory = di.Factory(object)
 
 
+# Example of using `di.inject()` decorator keyword argument injections:
 @di.inject(new_object=dependency_injector_factory)
 @di.inject(some_setting=1334)
-def example_callback(new_object, some_setting):
+def example_callback1(new_object, some_setting):
     """Example callback that does some asserts for input args."""
     assert isinstance(new_object, object)
     assert some_setting == 1334
 
-example_callback()
+
+# Example of using `di.inject()` decorator with positional argument injections:
+@di.inject(dependency_injector_factory, 1334)
+def example_callback2(new_object, some_setting):
+    """Example callback that does some asserts for input args."""
+    assert isinstance(new_object, object)
+    assert some_setting == 1334
+
+
+example_callback1()
+example_callback2()