From 3b7787521215ab3ff608ff9314f001dd3e6476d1 Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Thu, 13 Sep 2018 16:32:41 -0700 Subject: [PATCH 1/4] polish asyncio subprocess and sync docs --- Doc/library/asyncio-subprocess.rst | 16 ++++++++-------- Doc/library/asyncio-sync.rst | 8 ++++---- 2 files changed, 12 insertions(+), 12 deletions(-) diff --git a/Doc/library/asyncio-subprocess.rst b/Doc/library/asyncio-subprocess.rst index b05c236bb0c868..8bc856b8e39300 100644 --- a/Doc/library/asyncio-subprocess.rst +++ b/Doc/library/asyncio-subprocess.rst @@ -62,8 +62,8 @@ Creating Subprocesses The *limit* argument sets the buffer limit for :class:`StreamReader` wrappers for :attr:`Process.stdout` and :attr:`Process.stderr` - (if :attr:`subprocess.PIPE` is passed to *stdout* and *stderr* - arguments). + (if :attr:`subprocess.PIPE` (not available on Windows) is passed to + *stdout* and *stderr* arguments). Return a :class:`~asyncio.subprocess.Process` instance. @@ -78,15 +78,15 @@ Creating Subprocesses The *limit* argument sets the buffer limit for :class:`StreamReader` wrappers for :attr:`Process.stdout` and :attr:`Process.stderr` - (if :attr:`subprocess.PIPE` is passed to *stdout* and *stderr* - arguments). + (if :attr:`subprocess.PIPE` (not available on Windows) is passed to + *stdout* and *stderr* sarguments). Return a :class:`~asyncio.subprocess.Process` instance. See the documentation of :meth:`loop.subprocess_shell` for other parameters. -.. note:: +.. important:: It is the application's responsibility to ensure that all whitespace and metacharacters are quoted appropriately to avoid `shell injection @@ -206,7 +206,7 @@ communicate with them. exception is ignored. This condition occurs when the process exits before all data are written into *stdin*. - If its desired to send data to the process' *stdin*, + If it is desired to send data to the process' *stdin*, the process needs to be created with ``stdin=PIPE``. Similarly, to get anything other than ``None`` in the result tuple, the process has to be created with ``stdout=PIPE`` and/or @@ -265,8 +265,8 @@ communicate with them. Use the :meth:`communicate` method rather than :attr:`process.stdin.write() `, :attr:`await process.stdout.read() ` or - :attr:`await process.stderr.read ` - to avoid deadlocks due to streams pausing reading or writing + :attr:`await process.stderr.read `. + This avoids deadlocks due to streams pausing reading or writing and blocking the child process. .. attribute:: pid diff --git a/Doc/library/asyncio-sync.rst b/Doc/library/asyncio-sync.rst index 8e01ca944083a0..8da5aa81ab9e40 100644 --- a/Doc/library/asyncio-sync.rst +++ b/Doc/library/asyncio-sync.rst @@ -13,11 +13,11 @@ those of the :mod:`threading` module with two important caveats: be used for OS threads synchronization (use :mod:`threading` for that); -* methods of synchronization objects do not accept the *timeout* +* methods of synchronization primitives do not accept the *timeout* argument; use the :func:`asyncio.wait_for` function to perform operations with timeouts. -asyncio has the following basic primitives: +asyncio has the following basic sychronization primitives: * :class:`Lock` * :class:`Event` @@ -72,7 +72,7 @@ Lock When the lock is *locked*, reset it to *unlocked* and return. - If the lock is *unlocked* a :exc:`RuntimeError` is raised. + If the lock is *unlocked*, a :exc:`RuntimeError` is raised. .. method:: locked() @@ -97,7 +97,7 @@ Event Example:: async def waiter(event): - print('waiting ...') + print('waiting for it ...') await event.wait() print('... got it!') From 30372e05553b999ae9692b73110989302c888fdc Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Thu, 13 Sep 2018 16:56:10 -0700 Subject: [PATCH 2/4] small clarification --- Doc/library/asyncio-subprocess.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Doc/library/asyncio-subprocess.rst b/Doc/library/asyncio-subprocess.rst index 8bc856b8e39300..19ed735fb739f0 100644 --- a/Doc/library/asyncio-subprocess.rst +++ b/Doc/library/asyncio-subprocess.rst @@ -98,7 +98,8 @@ Creating Subprocesses .. note:: The default event loop that asyncio is pre-configured - to use on **Windows** does not support subprocesses. + to use on **Windows** does not support subprocesses. Subprocesses are + available for Windows if the :class:`ProactorEventLoop` is used. See :ref:`Subprocess Support on Windows ` for details. From 8de2f9dcd9e240197eb36f6b8ca0f659957a23d1 Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Thu, 13 Sep 2018 16:58:23 -0700 Subject: [PATCH 3/4] remove Windows comment --- Doc/library/asyncio-subprocess.rst | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/Doc/library/asyncio-subprocess.rst b/Doc/library/asyncio-subprocess.rst index 19ed735fb739f0..10e3dd904e2f35 100644 --- a/Doc/library/asyncio-subprocess.rst +++ b/Doc/library/asyncio-subprocess.rst @@ -62,8 +62,7 @@ Creating Subprocesses The *limit* argument sets the buffer limit for :class:`StreamReader` wrappers for :attr:`Process.stdout` and :attr:`Process.stderr` - (if :attr:`subprocess.PIPE` (not available on Windows) is passed to - *stdout* and *stderr* arguments). + (if :attr:`subprocess.PIPE` is passed to *stdout* and *stderr* arguments). Return a :class:`~asyncio.subprocess.Process` instance. @@ -78,8 +77,7 @@ Creating Subprocesses The *limit* argument sets the buffer limit for :class:`StreamReader` wrappers for :attr:`Process.stdout` and :attr:`Process.stderr` - (if :attr:`subprocess.PIPE` (not available on Windows) is passed to - *stdout* and *stderr* sarguments). + (if :attr:`subprocess.PIPE` is passed to *stdout* and *stderr* sarguments). Return a :class:`~asyncio.subprocess.Process` instance. From 015a3820ebf30aaf999a5763fce30983834d94ac Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Thu, 13 Sep 2018 17:00:14 -0700 Subject: [PATCH 4/4] fix typo --- Doc/library/asyncio-subprocess.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/asyncio-subprocess.rst b/Doc/library/asyncio-subprocess.rst index 10e3dd904e2f35..92c081b70bfccf 100644 --- a/Doc/library/asyncio-subprocess.rst +++ b/Doc/library/asyncio-subprocess.rst @@ -77,7 +77,7 @@ Creating Subprocesses The *limit* argument sets the buffer limit for :class:`StreamReader` wrappers for :attr:`Process.stdout` and :attr:`Process.stderr` - (if :attr:`subprocess.PIPE` is passed to *stdout* and *stderr* sarguments). + (if :attr:`subprocess.PIPE` is passed to *stdout* and *stderr* arguments). Return a :class:`~asyncio.subprocess.Process` instance.