From aef7c1d0df11982cac9207d5c05526b14ba6a138 Mon Sep 17 00:00:00 2001 From: Roman Mogylatov Date: Tue, 1 Sep 2020 16:48:09 -0400 Subject: [PATCH] Update coroutine provider docs --- docs/main/changelog.rst | 1 + docs/providers/coroutine.rst | 77 +++++---------------- examples/providers/coroutine.py | 19 ++--- examples/providers/coroutine_async_await.py | 25 ------- 4 files changed, 23 insertions(+), 99 deletions(-) delete mode 100644 examples/providers/coroutine_async_await.py diff --git a/docs/main/changelog.rst b/docs/main/changelog.rst index 60bb4e70..531b44ac 100644 --- a/docs/main/changelog.rst +++ b/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 ------ diff --git a/docs/providers/coroutine.rst b/docs/providers/coroutine.rst index 303e420e..3db7846a 100644 --- a/docs/providers/coroutine.rst +++ b/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 -``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 +.. literalinclude:: ../../examples/providers/coroutine.py :language: python - -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. + :lines: 3- .. 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 - - :py:class:`Coroutine`. +``Coroutine`` provider handles an injection of the dependencies the same way like a +:ref:`factory-provider`. -.. _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`). +.. note:: + ``Coroutine`` provider returns ``True`` for ``asyncio.iscoroutinefunction()`` check. .. disqus:: diff --git a/examples/providers/coroutine.py b/examples/providers/coroutine.py index 054173ca..98767295 100644 --- a/examples/providers/coroutine.py +++ b/examples/providers/coroutine.py @@ -1,26 +1,19 @@ -"""`Coroutine` providers example with @asyncio.coroutine decorator. - -Current example works only fot Python 3.4+. -""" +"""`Coroutine` providers example with async / await syntax.""" import asyncio -import dependency_injector.providers as providers +from dependency_injector import providers -@asyncio.coroutine -def coroutine_function(arg1, arg2): - """Sample coroutine function.""" - yield from asyncio.sleep(0.1) +async def coroutine(arg1, arg2): + await 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 = loop.run_until_complete(coroutine_provider()) - + arg1, arg2 = asyncio.run(coroutine_provider()) assert (arg1, arg2) == (1, 2) assert asyncio.iscoroutinefunction(coroutine_provider) diff --git a/examples/providers/coroutine_async_await.py b/examples/providers/coroutine_async_await.py deleted file mode 100644 index cca13c26..00000000 --- a/examples/providers/coroutine_async_await.py +++ /dev/null @@ -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)