bpo-33649: Polish asyncio subprocess and sync docs (GH-9285)
Second pass for asyncio subprocess and sync docs. https://bugs.python.org/issue33649
This commit is contained in:
parent
11194c877c
commit
4e824e9649
|
@ -62,8 +62,7 @@ Creating Subprocesses
|
||||||
|
|
||||||
The *limit* argument sets the buffer limit for :class:`StreamReader`
|
The *limit* argument sets the buffer limit for :class:`StreamReader`
|
||||||
wrappers for :attr:`Process.stdout` and :attr:`Process.stderr`
|
wrappers for :attr:`Process.stdout` and :attr:`Process.stderr`
|
||||||
(if :attr:`subprocess.PIPE` is passed to *stdout* and *stderr*
|
(if :attr:`subprocess.PIPE` is passed to *stdout* and *stderr* arguments).
|
||||||
arguments).
|
|
||||||
|
|
||||||
Return a :class:`~asyncio.subprocess.Process` instance.
|
Return a :class:`~asyncio.subprocess.Process` instance.
|
||||||
|
|
||||||
|
@ -78,15 +77,14 @@ Creating Subprocesses
|
||||||
|
|
||||||
The *limit* argument sets the buffer limit for :class:`StreamReader`
|
The *limit* argument sets the buffer limit for :class:`StreamReader`
|
||||||
wrappers for :attr:`Process.stdout` and :attr:`Process.stderr`
|
wrappers for :attr:`Process.stdout` and :attr:`Process.stderr`
|
||||||
(if :attr:`subprocess.PIPE` is passed to *stdout* and *stderr*
|
(if :attr:`subprocess.PIPE` is passed to *stdout* and *stderr* arguments).
|
||||||
arguments).
|
|
||||||
|
|
||||||
Return a :class:`~asyncio.subprocess.Process` instance.
|
Return a :class:`~asyncio.subprocess.Process` instance.
|
||||||
|
|
||||||
See the documentation of :meth:`loop.subprocess_shell` for other
|
See the documentation of :meth:`loop.subprocess_shell` for other
|
||||||
parameters.
|
parameters.
|
||||||
|
|
||||||
.. note::
|
.. important::
|
||||||
|
|
||||||
It is the application's responsibility to ensure that all whitespace and
|
It is the application's responsibility to ensure that all whitespace and
|
||||||
metacharacters are quoted appropriately to avoid `shell injection
|
metacharacters are quoted appropriately to avoid `shell injection
|
||||||
|
@ -98,7 +96,8 @@ Creating Subprocesses
|
||||||
.. note::
|
.. note::
|
||||||
|
|
||||||
The default event loop that asyncio is pre-configured
|
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 <asyncio-windows-subprocess>`
|
See :ref:`Subprocess Support on Windows <asyncio-windows-subprocess>`
|
||||||
for details.
|
for details.
|
||||||
|
|
||||||
|
@ -206,7 +205,7 @@ communicate with them.
|
||||||
exception is ignored. This condition occurs when the process
|
exception is ignored. This condition occurs when the process
|
||||||
exits before all data are written into *stdin*.
|
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,
|
the process needs to be created with ``stdin=PIPE``. Similarly,
|
||||||
to get anything other than ``None`` in the result tuple, the
|
to get anything other than ``None`` in the result tuple, the
|
||||||
process has to be created with ``stdout=PIPE`` and/or
|
process has to be created with ``stdout=PIPE`` and/or
|
||||||
|
@ -265,8 +264,8 @@ communicate with them.
|
||||||
Use the :meth:`communicate` method rather than
|
Use the :meth:`communicate` method rather than
|
||||||
:attr:`process.stdin.write() <stdin>`,
|
:attr:`process.stdin.write() <stdin>`,
|
||||||
:attr:`await process.stdout.read() <stdout>` or
|
:attr:`await process.stdout.read() <stdout>` or
|
||||||
:attr:`await process.stderr.read <stderr>`
|
:attr:`await process.stderr.read <stderr>`.
|
||||||
to avoid deadlocks due to streams pausing reading or writing
|
This avoids deadlocks due to streams pausing reading or writing
|
||||||
and blocking the child process.
|
and blocking the child process.
|
||||||
|
|
||||||
.. attribute:: pid
|
.. attribute:: pid
|
||||||
|
|
|
@ -13,11 +13,11 @@ those of the :mod:`threading` module with two important caveats:
|
||||||
be used for OS threads synchronization (use :mod:`threading` for
|
be used for OS threads synchronization (use :mod:`threading` for
|
||||||
that);
|
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
|
argument; use the :func:`asyncio.wait_for` function to perform
|
||||||
operations with timeouts.
|
operations with timeouts.
|
||||||
|
|
||||||
asyncio has the following basic primitives:
|
asyncio has the following basic sychronization primitives:
|
||||||
|
|
||||||
* :class:`Lock`
|
* :class:`Lock`
|
||||||
* :class:`Event`
|
* :class:`Event`
|
||||||
|
@ -72,7 +72,7 @@ Lock
|
||||||
|
|
||||||
When the lock is *locked*, reset it to *unlocked* and return.
|
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()
|
.. method:: locked()
|
||||||
|
|
||||||
|
@ -97,7 +97,7 @@ Event
|
||||||
Example::
|
Example::
|
||||||
|
|
||||||
async def waiter(event):
|
async def waiter(event):
|
||||||
print('waiting ...')
|
print('waiting for it ...')
|
||||||
await event.wait()
|
await event.wait()
|
||||||
print('... got it!')
|
print('... got it!')
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue