From c318669566f82249f3c9f84cf61e89c02ca3733f Mon Sep 17 00:00:00 2001 From: Yury Selivanov Date: Mon, 20 Apr 2015 19:25:08 -0400 Subject: [PATCH] pep-0492: Renames; add sys.get_coroutine_wrapper() Renames: * types.async_def() -> types.coroutine() * CO_ASYNC -> CO_COROUTINE Add `sys.get_coroutine_wrapper()` --- pep-0492.txt | 43 ++++++++++++++++++++++--------------------- 1 file changed, 22 insertions(+), 21 deletions(-) diff --git a/pep-0492.txt b/pep-0492.txt index e7a8f94b2..d743da973 100644 --- a/pep-0492.txt +++ b/pep-0492.txt @@ -84,9 +84,9 @@ Key properties of coroutines: * It is a ``SyntaxError`` to have ``yield`` or ``yield from`` expressions in an ``async`` function. -* Internally, a new code object flag - ``CO_ASYNC`` - is introduced to enable - runtime detection of coroutines (and migrating existing code). - All coroutines have both ``CO_ASYNC`` and ``CO_GENERATOR`` flags set. +* Internally, a new code object flag - ``CO_COROUTINE`` - is introduced to + enable runtime detection of coroutines (and migrating existing code). All + coroutines have both ``CO_COROUTINE`` and ``CO_GENERATOR`` flags set. * Regular generators, when called, return a *generator object*; similarly, coroutines return a *coroutine object*. @@ -96,12 +96,12 @@ Key properties of coroutines: requires a future import (see PEP 479). -types.async_def() +types.coroutine() ----------------- -A new function ``async_def(gen)`` is added to the ``types`` module. It applies -``CO_ASYNC`` flag to the passed generator-function's code object, so that it -returns a *coroutine object* when called. +A new function ``coroutine(gen)`` is added to the ``types`` module. It applies +``CO_COROUTINE`` flag to the passed generator-function's code object, +making it to return a *coroutine object* when called. This feature enables an easy upgrade path for existing libraries. @@ -123,8 +123,8 @@ data. It uses the ``yield from`` implementation with an extra step of validating its argument. ``await`` only accepts an *awaitable*, which can be one of: -* A *coroutine object* returned from a coroutine or a generator decorated with - ``types.async_def()``. +* A *coroutine object* returned from a *coroutine* or a generator decorated + with ``types.coroutine()``. * An object with an ``__await__`` method returning an iterator. @@ -438,9 +438,10 @@ variable ``PYTHONASYNCIODEBUG``. This way it is possible to run asyncio programs with asyncio's own functions instrumented. ``EventLoop.set_debug``, a different debug facility, has no impact on ``@coroutine`` decorator's behavior. -With this proposal, coroutines is a native, distinct from generators, -concept. A new method ``set_coroutine_wrapper`` is added to the ``sys`` module, -with which frameworks can provide advanced debugging facilities. +With this proposal, coroutines is a native, distinct from generators, concept. +New methods ``set_coroutine_wrapper`` and ``get_coroutine_wrapper`` are added +to the ``sys`` module, with which frameworks can provide advanced debugging +facilities. It is also important to make coroutines as fast and efficient as possible, therefore there are no debug features enabled by default. @@ -464,8 +465,8 @@ Example:: # previously set wrapper assert not isinstance(debug_me(), AsyncDebugWrapper) -If ``sys.set_coroutine_wrapper()`` is called twice, the new wrapper replaces the -previous wrapper. ``sys.set_coroutine_wrapper(None)`` unsets the wrapper. +If ``sys.set_coroutine_wrapper()`` is called twice, the new wrapper replaces +the previous wrapper. ``sys.set_coroutine_wrapper(None)`` unsets the wrapper. Glossary @@ -647,7 +648,7 @@ statements. Backwards compatibility is 100% preserved. The required changes are mainly: -1. Modify ``@asyncio.coroutine`` decorator to use new ``types.async_def()`` +1. Modify ``@asyncio.coroutine`` decorator to use new ``types.coroutine()`` function. 2. Add ``__await__ = __iter__`` line to ``asyncio.Future`` class. @@ -701,7 +702,7 @@ Differences from this proposal: ``@asyncio.coroutine`` decorator to wrap all functions in an object with a ``__cocall__`` method. To call *cofunctions* from existing generator-based coroutines it would be required to use ``costart`` built-in. In this - proposal ``@asyncio.coroutine`` simply sets ``CO_ASYNC`` on the wrapped + proposal ``@asyncio.coroutine`` simply sets ``CO_COROUTINE`` on the wrapped function's code object and everything works automatically. 4. Since it is impossible to call a *cofunction* without a ``cocall`` keyword, @@ -794,8 +795,8 @@ Let's pretend that Python only has ``await`` keyword:: If ``useful()`` function is refactored and someone removes all ``await`` expressions from it, it would become a regular python function, and all code -that depends on it, including ``important()`` would be broken. To mitigate this -issue a decorator similar to ``@asyncio.coroutine`` has to be introduced. +that depends on it, including ``important()`` would be broken. To mitigate +this issue a decorator similar to ``@asyncio.coroutine`` has to be introduced. Why "async def" @@ -974,10 +975,10 @@ List of high-level changes and new protocols 5. New AST nodes: ``AsyncFunctionDef``, ``AsyncFor``, ``AsyncWith``, ``Await``. -6. New functions: ``sys.set_coroutine_wrapper(callback)`` and - ``types.async_def(gen)``. +6. New functions: ``sys.set_coroutine_wrapper(callback)``, + ``sys.get_coroutine_wrapper()``, and ``types.coroutine(gen)``. -7. New ``CO_ASYNC`` bit flag for code objects. +7. New ``CO_COROUTINE`` bit flag for code objects. While the list of changes and new things is not short, it is important to understand, that most users will not use these features directly. It is