From 8a93d4135c4c04a93f8633b3d04d5092ea8b2c0d Mon Sep 17 00:00:00 2001 From: Roman Mogylatov Date: Thu, 18 Oct 2018 19:37:17 +0300 Subject: [PATCH] Update coroutine provider docs --- docs/providers/callable.rst | 2 +- docs/providers/coroutine.rst | 73 +++++++++++++++++++++++++++ docs/providers/factory.rst | 2 +- docs/providers/index.rst | 1 + src/dependency_injector/providers.c | 8 +-- src/dependency_injector/providers.pyx | 4 +- 6 files changed, 82 insertions(+), 8 deletions(-) create mode 100644 docs/providers/coroutine.rst diff --git a/docs/providers/callable.rst b/docs/providers/callable.rst index df0117d1..3d62ee20 100644 --- a/docs/providers/callable.rst +++ b/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: diff --git a/docs/providers/coroutine.rst b/docs/providers/coroutine.rst new file mode 100644 index 00000000..e37b286f --- /dev/null +++ b/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:: diff --git a/docs/providers/factory.rst b/docs/providers/factory.rst index f35d6dd8..ee3f6ce3 100644 --- a/docs/providers/factory.rst +++ b/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: diff --git a/docs/providers/index.rst b/docs/providers/index.rst index 9889b802..ba07862f 100644 --- a/docs/providers/index.rst +++ b/docs/providers/index.rst @@ -20,6 +20,7 @@ Providers package API docs - :py:mod:`dependency_injector.providers` factory singleton callable + coroutine object dependency overriding diff --git a/src/dependency_injector/providers.c b/src/dependency_injector/providers.c index d7fdf15b..69f16493 100644 --- a/src/dependency_injector/providers.c +++ b/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*/ diff --git a/src/dependency_injector/providers.pyx b/src/dependency_injector/providers.pyx index b2fe5634..ec2ca49d 100644 --- a/src/dependency_injector/providers.pyx +++ b/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". """