From d07a2eae25f4fc2ca0c5ef660bc1457dda0bc9bf Mon Sep 17 00:00:00 2001 From: Roman Mogilatov Date: Fri, 23 Oct 2015 15:04:04 +0300 Subject: [PATCH] Update inject() decorator docs with positional argument injections example and some description --- docs/advanced_usage/index.rst | 23 +++++++++++++++++++---- docs/main/changelog.rst | 3 ++- examples/advanced_usage/inject_flask.py | 6 +++--- examples/advanced_usage/inject_simple.py | 15 +++++++++++++-- 4 files changed, 37 insertions(+), 10 deletions(-) diff --git a/docs/advanced_usage/index.rst b/docs/advanced_usage/index.rst index bc010888..c2133e63 100644 --- a/docs/advanced_usage/index.rst +++ b/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 -during every next call of decorated callback with the same name. Any Python -object will be injected *as is*, except ``di.Provider``'s, which will be -called to provide injectable values. +``di.inject()`` takes a various number of positional and keyword arguments +that are used as decorated callable injections. Every time, when +``di.inject()`` is called, positional and keyword argument injections would be +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: diff --git a/docs/main/changelog.rst b/docs/main/changelog.rst index 3a3af526..0a6ccaf2 100644 --- a/docs/main/changelog.rst +++ b/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). diff --git a/examples/advanced_usage/inject_flask.py b/examples/advanced_usage/inject_flask.py index 5b1ae58f..ecb6edc9 100644 --- a/examples/advanced_usage/inject_flask.py +++ b/examples/advanced_usage/inject_flask.py @@ -5,8 +5,8 @@ import flask import dependency_injector as di -database = di.Singleton(sqlite3.Connection, - database=':memory:', +database = di.Singleton(sqlite3.connect, + ':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] diff --git a/examples/advanced_usage/inject_simple.py b/examples/advanced_usage/inject_simple.py index 2a7fc468..dce9c9fb 100644 --- a/examples/advanced_usage/inject_simple.py +++ b/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()