Update coroutine provider docs

docs/main/changelog.rst

@@ -11,6 +11,7 @@ Development version
 -------------------
 - Update ``Singleton`` provider documentation and rework examples.
 - Update ``Callable`` provider documentation and rework examples.
+- Update ``Coroutine`` provider documentation and rework examples.
 
 3.34.0
 ------

docs/providers/coroutine.rst

@@ -1,72 +1,27 @@
-Coroutine providers
+Coroutine provider
--------------------
+------------------
+
+.. meta::
+   :keywords: Python,DI,Dependency injection,IoC,Inversion of Control,Coroutine,Asynchronous,
+              Asyncio,Example
+   :description: Coroutine provider creates a coroutine. This page demonstrates how to use a
+                 Coroutine provider.
 
 .. currentmodule:: dependency_injector.providers
 
-:py:class:`Coroutine` provider create wrapped coroutine on every call.
+:py:class:`Coroutine` provider creates a coroutine.
 
-:py:class:`Coroutine` provider is designed for making better integration with
+.. literalinclude:: ../../examples/providers/coroutine.py
-``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
-
+   :lines: 3-
-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::
+   The example works on Python 3.7+. For earlier versions use ``loop.run_until_complete()``.
 
-    Examples of making injections could be found in API docs -
+``Coroutine`` provider handles an injection of the dependencies the same way like a
-    :py:class:`Coroutine`.
+:ref:`factory-provider`.
 
-.. _coroutine_providers_delegation:
+.. note::
-
+   ``Coroutine`` provider returns ``True`` for ``asyncio.iscoroutinefunction()`` check.
-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::

examples/providers/coroutine.py

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

examples/providers/coroutine_async_await.py

@@ -1,25 +0,0 @@
-"""`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)