Coroutine provider (ets-labs#206)

* Add coroutine provider examples * Add coroutine provier * Update changelog * Update static analysis travis jobs to python 3.7 * Update coroutine provider implementation for python 3.4 * Update static analysis travis jobs to python 3.6 * Make pycode style happy * Add tests for coroutine providers * Make coroutine tests python 2 syntax friendly * Split tests to python2 and python3 * Refactor coroutine provider tests * Modify pypy tests running command * Update coroutine provider docs

Author: rmk135

.travis.yml

@@ -7,17 +7,17 @@ language:
  - python
 matrix:
  include:
- - python: 2.7
+ - python: 3.6
  env: TOXENV=coveralls DEPENDENCY_INJECTOR_DEBUG_MODE=1
  install:
  - pip install tox
  - pip install cython
  - make cythonize
- - python: 2.7
+ - python: 3.6
  env: TOXENV=pylint
- - python: 2.7
+ - python: 3.6
  env: TOXENV=flake8
- - python: 2.7
+ - python: 3.6
  env: TOXENV=pydocstyle
  - python: 2.7
  env: TOXENV=py27

Makefile

@@ -42,10 +42,17 @@ install: uninstall clean cythonize
 uninstall:
 - pip uninstall -y -q dependency-injector 2> /dev/null
 
-test: build
+test-py2: build
 # Unit tests with coverage report
 coverage erase
-coverage run --rcfile=./.coveragerc -m unittest2 discover tests/unit
+coverage run --rcfile=./.coveragerc -m unittest2 discover -s tests/unit/ -p test_*_py2_py3.py
+coverage report --rcfile=./.coveragerc
+coverage html --rcfile=./.coveragerc
+
+test-py3: build
+# Unit tests with coverage report
+coverage erase
+coverage run --rcfile=./.coveragerc -m unittest2 discover -s tests/unit/ -p test_*py3.py
 coverage report --rcfile=./.coveragerc
 coverage html --rcfile=./.coveragerc
 

docs/main/changelog.rst

@@ -9,6 +9,10 @@ follows `Semantic versioning`_
 
 Development version
 -------------------
+- Add ``Coroutine`` provider.
+- Add ``DelegatedCoroutine`` provider.
+- Add ``AbstractCoroutine`` provider.
+- Add ``CoroutineDelegate`` provider.
 - Regenerate C sources using Cython 0.28.5.
 
 3.13.2

docs/providers/callable.rst

@@ -11,7 +11,7 @@ Callable providers and injections
 :py:class:`Callable` provider takes a various number of positional and keyword 
 arguments that are used as wrapped callable injections. Every time, when 
 :py:class:`Callable` provider is called, positional and keyword argument 
-injections would be passed as an callable arguments.
+injections would be passed as callable arguments.
 
 Injections are done according to the next rules:
 

docs/providers/coroutine.rst

@@ -0,0 +1,73 @@
+Coroutine providers
+-------------------
+
+.. currentmodule:: dependency_injector.providers
+
+:py:class:`Coroutine` provider create wrapped coroutine on every call.
+
+:py:class:`Coroutine` provider is designed for making better integration with
+``asyncio`` coroutines. In particular, :py:class:`Coroutine` provider returns
+``True`` for ``asyncio.iscoroutinefunction()`` checks.
+
+.. note::
+
+ :py:class:`Coroutine` provider works only for Python 3.4+.
+
+Example of usage :py:class:`Coroutine` provider with ``async / await``-based
+coroutine:
+
+.. literalinclude:: ../../examples/providers/coroutine_async_await.py
+ :language: python
+ :linenos:
+
+Coroutine providers and injections
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+:py:class:`Coroutine` provider takes a various number of positional and keyword
+arguments that are used as wrapped coroutine injections. Every time, when
+:py:class:`Coroutine` provider is called, positional and keyword argument
+injections would be passed as coroutine arguments.
+
+Injections are done according to the next rules:
+
++ All providers (instances of :py:class:`Provider`) are called every time 
+ when injection needs to be done.
++ Providers could be injected "as is" (delegated), if it is defined obviously.
+ Check out :ref:`coroutine_providers_delegation`.
++ All other injectable values are provided *"as is"*.
++ Positional context arguments will be appended after :py:class:`Coroutine`
+ positional injections.
++ Keyword context arguments have priority on :py:class:`Coroutine` keyword
+ injections and will be merged over them.
+
+.. note::
+
+ Examples of making injections could be found in API docs -
+ :py:class:`Coroutine`.
+
+.. _coroutine_providers_delegation:
+
+Coroutine providers delegation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+:py:class:`Coroutine` provider could be delegated to any other provider via
+any kind of injection. 
+
+Delegation of :py:class:`Coroutine` providers is the same as
+:py:class:`Factory` providers delegation, please follow 
+:ref:`factory_providers_delegation` section for examples (with exception 
+of using :py:class:`DelegatedCoroutine` instead of
+:py:class:`DelegatedFactory`).
+
+Abstract coroutine providers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+:py:class:`AbstractCoroutine` provider is a :py:class:`Coroutine` provider that
+must be explicitly overridden before calling.
+
+Behaviour of :py:class:`AbstractCoroutine` providers is the same as of
+:py:class:`AbstractFactory`, please follow :ref:`abstract_factory_providers`
+section for examples (with exception of using :py:class:`AbstractCoroutine`
+provider instead of :py:class:`AbstractFactory`).
+
+.. disqus::

docs/providers/factory.rst

@@ -22,7 +22,7 @@ Factory providers and __init__ injections
 :py:class:`Factory` takes a various number of positional and keyword arguments 
 that are used as ``__init__()`` injections. Every time, when 
 :py:class:`Factory` creates new one instance, positional and keyword 
-argument injections would be passed as an instance's arguments.
+argument injections would be passed as instance arguments.
 
 Injections are done according to the next rules:
 

docs/providers/index.rst

@@ -20,6 +20,7 @@ Providers package API docs - :py:mod:`dependency_injector.providers`
  factory
  singleton
  callable
+ coroutine
  object
  dependency
  overriding

examples/providers/coroutine.py

@@ -0,0 +1,26 @@
+"""`Coroutine` providers example with @asyncio.coroutine decorator.
+
+Current example works only fot Python 3.4+.
+"""
+
+import asyncio
+
+import dependency_injector.providers as providers
+
+
+@asyncio.coroutine
+def coroutine_function(arg1, arg2):
+ """Sample coroutine function."""
+ yield from asyncio.sleep(0.1)
+ return arg1, arg2
+
+
+coroutine_provider = providers.Coroutine(coroutine_function, arg1=1, arg2=2)
+
+
+if __name__ == '__main__':
+ loop = asyncio.get_event_loop()
+ arg1, arg2 = loop.run_until_complete(coroutine_provider())
+
+ assert (arg1, arg2) == (1, 2)
+ assert asyncio.iscoroutinefunction(coroutine_provider)

examples/providers/coroutine_async_await.py

@@ -0,0 +1,25 @@
+"""`Coroutine` providers example with async / await syntax.
+
+Current example works only fot Python 3.5+.
+"""
+
+import asyncio
+
+import dependency_injector.providers as providers
+
+
+async def coroutine_function(arg1, arg2):
+ """Sample coroutine function."""
+ await asyncio.sleep(0.1)
+ return arg1, arg2
+
+
+coroutine_provider = providers.Coroutine(coroutine_function, arg1=1, arg2=2)
+
+
+if __name__ == '__main__':
+ loop = asyncio.get_event_loop()
+ arg1, arg2 = loop.run_until_complete(coroutine_provider())
+
+ assert (arg1, arg2) == (1, 2)
+ assert asyncio.iscoroutinefunction(coroutine_provider)