Update coroutine provider docs

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

src/dependency_injector/providers.c

@@ -1390,7 +1390,7 @@ static struct __pyx_vtabstruct_19dependency_injector_9providers_CallableDelegate
  * 
  * 
  * cdef class Coroutine(Callable):             # <<<<<<<<<<<<<<
- *     r"""Coroutine provider calls wrapped coroutine on every call.
+ *     r"""Coroutine provider creates wrapped coroutine on every call.
  * 
  */
 
@@ -1404,7 +1404,7 @@ static struct __pyx_vtabstruct_19dependency_injector_9providers_Coroutine *__pyx
  * 
  * 
  * cdef class DelegatedCoroutine(Coroutine):             # <<<<<<<<<<<<<<
- *     """Coroutine that is injected "as is".
+ *     """Coroutine provider that is injected "as is".
  * 
  */
 
@@ -58057,7 +58057,7 @@ static PyTypeObject __pyx_type_19dependency_injector_9providers_Coroutine = {
   0, /*tp_setattro*/
   0, /*tp_as_buffer*/
   Py_TPFLAGS_DEFAULT|Py_TPFLAGS_HAVE_VERSION_TAG|Py_TPFLAGS_CHECKTYPES|Py_TPFLAGS_HAVE_NEWBUFFER|Py_TPFLAGS_BASETYPE|Py_TPFLAGS_HAVE_GC, /*tp_flags*/
-  "Coroutine provider calls wrapped coroutine on every call.\n\n    Coroutine supports positional and keyword argument injections:\n\n    .. code-block:: python\n\n        some_coroutine = Coroutine(some_coroutine,\n                                   'positional_arg1', 'positional_arg2',\n                                   keyword_argument1=3, keyword_argument=4)\n\n        # or\n\n        some_coroutine = Coroutine(some_coroutine) \\\n            .add_args('positional_arg1', 'positional_arg2') \\\n            .add_kwargs(keyword_argument1=3, keyword_argument=4)\n\n        # or\n\n        some_coroutine = Coroutine(some_coroutine)\n        some_coroutine.add_args('positional_arg1', 'positional_arg2')\n        some_coroutine.add_kwargs(keyword_argument1=3, keyword_argument=4)\n    ", /*tp_doc*/
+  "Coroutine provider creates wrapped coroutine on every call.\n\n    Coroutine supports positional and keyword argument injections:\n\n    .. code-block:: python\n\n        some_coroutine = Coroutine(some_coroutine,\n                                   'positional_arg1', 'positional_arg2',\n                                   keyword_argument1=3, keyword_argument=4)\n\n        # or\n\n        some_coroutine = Coroutine(some_coroutine) \\\n            .add_args('positional_arg1', 'positional_arg2') \\\n            .add_kwargs(keyword_argument1=3, keyword_argument=4)\n\n        # or\n\n        some_coroutine = Coroutine(some_coroutine)\n        some_coroutine.add_args('positional_arg1', 'positional_arg2')\n        some_coroutine.add_kwargs(keyword_argument1=3, keyword_argument=4)\n    ", /*tp_doc*/
   __pyx_tp_traverse_19dependency_injector_9providers_Callable, /*tp_traverse*/
   __pyx_tp_clear_19dependency_injector_9providers_Callable, /*tp_clear*/
   0, /*tp_richcompare*/
@@ -58143,7 +58143,7 @@ static PyTypeObject __pyx_type_19dependency_injector_9providers_DelegatedCorouti
   0, /*tp_setattro*/
   0, /*tp_as_buffer*/
   Py_TPFLAGS_DEFAULT|Py_TPFLAGS_HAVE_VERSION_TAG|Py_TPFLAGS_CHECKTYPES|Py_TPFLAGS_HAVE_NEWBUFFER|Py_TPFLAGS_BASETYPE|Py_TPFLAGS_HAVE_GC, /*tp_flags*/
-  "Coroutine that is injected \"as is\".\n\n    DelegatedCoroutine is a :py:class:`Coroutine`, that is injected \"as is\".\n    ", /*tp_doc*/
+  "Coroutine provider that is injected \"as is\".\n\n    DelegatedCoroutine is a :py:class:`Coroutine`, that is injected \"as is\".\n    ", /*tp_doc*/
   __pyx_tp_traverse_19dependency_injector_9providers_Callable, /*tp_traverse*/
   __pyx_tp_clear_19dependency_injector_9providers_Callable, /*tp_clear*/
   0, /*tp_richcompare*/

src/dependency_injector/providers.pyx

@@ -862,7 +862,7 @@ cdef class CallableDelegate(Delegate):
 
 
 cdef class Coroutine(Callable):
-    r"""Coroutine provider calls wrapped coroutine on every call.
+    r"""Coroutine provider creates wrapped coroutine on every call.
 
     Coroutine supports positional and keyword argument injections:
 
@@ -912,7 +912,7 @@ cdef class Coroutine(Callable):
 
 
 cdef class DelegatedCoroutine(Coroutine):
-    """Coroutine that is injected "as is".
+    """Coroutine provider that is injected "as is".
 
     DelegatedCoroutine is a :py:class:`Coroutine`, that is injected "as is".
     """