bpo-33649: A copy-editing pass on asyncio documentation (GH-9376)
diff --git a/Doc/library/asyncio-subprocess.rst b/Doc/library/asyncio-subprocess.rst
index 57a7a37..0bcf661 100644
--- a/Doc/library/asyncio-subprocess.rst
+++ b/Doc/library/asyncio-subprocess.rst
@@ -12,7 +12,7 @@
.. _asyncio_example_subprocess_shell:
Here's an example of how asyncio can run a shell command and
-communicate its result back::
+obtain its result::
import asyncio
@@ -41,7 +41,7 @@
Because all asyncio subprocess functions are asynchronous and asyncio
provides many tools to work with such functions, it is easy to execute
and monitor multiple subprocesses in parallel. It is indeed trivial
-to modify the above example to run a few commands at once::
+to modify the above example to run several commands simultaneously::
async def main():
await asyncio.gather(
@@ -75,7 +75,7 @@
stdout=None, stderr=None, loop=None, \
limit=None, \*\*kwds)
- Run the shell command *cmd*.
+ Run the *cmd* shell command.
The *limit* argument sets the buffer limit for :class:`StreamReader`
wrappers for :attr:`Process.stdout` and :attr:`Process.stderr`
@@ -89,23 +89,23 @@
.. important::
It is the application's responsibility to ensure that all whitespace and
- metacharacters are quoted appropriately to avoid `shell injection
+ special characters are quoted appropriately to avoid `shell injection
<https://en.wikipedia.org/wiki/Shell_injection#Shell_injection>`_
vulnerabilities. The :func:`shlex.quote` function can be used to properly
- escape whitespace and shell metacharacters in strings that are going to be
- used to construct shell commands.
+ escape whitespace and special shell characters in strings that are going
+ to be used to construct shell commands.
.. note::
- The default event loop that asyncio is pre-configured
- to use on **Windows** does not support subprocesses. Subprocesses are
- available for Windows if the :class:`ProactorEventLoop` is used.
+ The default asyncio event loop implementation on **Windows** does not
+ support subprocesses. Subprocesses are available for Windows if a
+ :class:`ProactorEventLoop` is used.
See :ref:`Subprocess Support on Windows <asyncio-windows-subprocess>`
for details.
.. seealso::
- asyncio has also *low-level* APIs to work with subprocesses:
+ asyncio also has the following *low-level* APIs to work with subprocesses:
:meth:`loop.subprocess_exec`, :meth:`loop.subprocess_shell`,
:meth:`loop.connect_read_pipe`, :meth:`loop.connect_write_pipe`,
as well as the :ref:`Subprocess Transports <asyncio-subprocess-transports>`
@@ -130,22 +130,23 @@
.. data:: asyncio.subprocess.STDOUT
- Can be passed to the *stderr* parameter to redirect process'
- *stderr* to *stdout*.
+ Special value that can be used as the *stderr* argument and indicates
+ that standard error should be redirected into standard output.
.. data:: asyncio.subprocess.DEVNULL
- Can be passed as the *stdin*, *stdout* or *stderr* parameters
- to redirect the corresponding subprocess' IO to :data:`os.devnull`.
+ Special value that can be used as the *stdin*, *stdout* or *stderr* argument
+ to process creation functions. It indicates that the special file
+ :data:`os.devnull` will be used for the corresponding subprocess stream.
Interacting with Subprocesses
=============================
Both :func:`create_subprocess_exec` and :func:`create_subprocess_shell`
-functions return instances of the *Process* class. It is a high-level
-wrapper that allows to watch for subprocesses completion and
-communicate with them.
+functions return instances of the *Process* class. *Process* is a high-level
+wrapper that allows communicating with subprocesses and watching for
+their completion.
.. class:: asyncio.subprocess.Process
@@ -161,7 +162,7 @@
the :meth:`~subprocess.Popen.poll` method;
* the :meth:`~asyncio.subprocess.Process.communicate` and
- :meth:`~asyncio.subprocess.Process.wait` methods don't take a
+ :meth:`~asyncio.subprocess.Process.wait` methods don't have a
*timeout* parameter: use the :func:`wait_for` function;
* the :meth:`Process.wait() <asyncio.subprocess.Process.wait>` method
@@ -177,7 +178,7 @@
.. coroutinemethod:: wait()
- Wait for child process to terminate.
+ Wait for the child process to terminate.
Set and return the :attr:`returncode` attribute.
@@ -229,9 +230,9 @@
.. method:: terminate()
- Stop the child.
+ Stop the child process.
- On Posix OSs the method sends :py:data:`signal.SIGTERM` to the
+ On POSIX systems this method sends :py:data:`signal.SIGTERM` to the
child process.
On Windows the Win32 API function :c:func:`TerminateProcess` is
@@ -241,7 +242,7 @@
Kill the child.
- On Posix OSs the function sends :py:data:`SIGKILL` to the child
+ On POSIX systems this method sends :py:data:`SIGKILL` to the child
process.
On Windows this method is an alias for :meth:`terminate`.
@@ -284,7 +285,7 @@
A ``None`` value indicates that the process has not terminated yet.
A negative value ``-N`` indicates that the child was terminated
- by signal ``N`` (Unix only).
+ by signal ``N`` (POSIX only).
.. _asyncio-subprocess-threads:
@@ -292,17 +293,17 @@
Subprocess and Threads
----------------------
-asyncio built-in event loops support running subprocesses from
-different threads, but there are the following limitations:
+Standard asyncio event loop supports running subprocesses from
+different threads, but there are limitations:
* An event loop must run in the main thread.
-* The child watcher must be instantiated in the main thread,
+* The child watcher must be instantiated in the main thread
before executing subprocesses from other threads. Call the
:func:`get_child_watcher` function in the main thread to instantiate
the child watcher.
-Note, that alternative event loop implementations might not share
+Note that alternative event loop implementations might not share
the above limitations; please refer to their documentation.
.. seealso::
@@ -316,7 +317,7 @@
An example using the :class:`~asyncio.subprocess.Process` class to
control a subprocess and the :class:`StreamReader` class to read from
-the *stdout*.
+its standard output.
.. _asyncio_example_create_subprocess_exec: