[Python-checkins] peps: pep-0492: Renames; add sys.get_coroutine_wrapper()

[yury.selivanov]

https://hg.python.org/peps/rev/4bd8ab31109c
changeset:   5778:4bd8ab31109c
user:        Yury Selivanov <yselivanov at sprymix.com>
date:        Mon Apr 20 19:25:08 2015 -0400
summary:
  pep-0492: Renames; add sys.get_coroutine_wrapper()

Renames:

* types.async_def() -> types.coroutine()

* CO_ASYNC -> CO_COROUTINE

Add `sys.get_coroutine_wrapper()`

files:
  pep-0492.txt |  43 ++++++++++++++++++++-------------------
  1 files changed, 22 insertions(+), 21 deletions(-)


diff --git a/pep-0492.txt b/pep-0492.txt
--- a/pep-0492.txt
+++ b/pep-0492.txt
@@ -84,9 +84,9 @@
 * 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 @@
   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 @@
 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 @@
 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 @@
                                     #    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 @@
 
 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 @@
    ``@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 @@
 
 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 @@
 
 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

-- 
Repository URL: https://hg.python.org/peps