diff options
Diffstat (limited to 'Doc/library/subprocess.rst')
| -rw-r--r-- | Doc/library/subprocess.rst | 45 |
1 files changed, 32 insertions, 13 deletions
diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst index 347dcc3e50..cdcbe8280c 100644 --- a/Doc/library/subprocess.rst +++ b/Doc/library/subprocess.rst @@ -116,7 +116,7 @@ use cases, the underlying :class:`Popen` interface can be used directly. *timeout* was added. -.. function:: check_output(args, *, stdin=None, stderr=None, shell=False, universal_newlines=False, timeout=None) +.. function:: check_output(args, *, input=None, stdin=None, stderr=None, shell=False, universal_newlines=False, timeout=None) Run command with arguments and return its output. @@ -129,15 +129,21 @@ use cases, the underlying :class:`Popen` interface can be used directly. in :ref:`frequently-used-arguments` (hence the use of keyword-only notation in the abbreviated signature). The full function signature is largely the same as that of the :class:`Popen` constructor - this functions passes all - supplied arguments other than *timeout* directly through to that interface. - In addition, *stdout* is not permitted as an argument, as it is used - internally to collect the output from the subprocess. + supplied arguments other than *input* and *timeout* directly through to + that interface. In addition, *stdout* is not permitted as an argument, as + it is used internally to collect the output from the subprocess. The *timeout* argument is passed to :meth:`Popen.wait`. If the timeout expires, the child process will be killed and then waited for again. The :exc:`TimeoutExpired` exception will be re-raised after the child process has terminated. + The *input* argument is passed to :meth:`Popen.communicate` and thus to the + subprocess's stdin. If used it must be a byte sequence, or a string if + ``universal_newlines=True``. When used, the internal :class:`Popen` object + is automatically created with ``stdin=PIPE``, and the *stdin* argument may + not be used as well. + Examples:: >>> subprocess.check_output(["echo", "Hello World!"]) @@ -146,6 +152,10 @@ use cases, the underlying :class:`Popen` interface can be used directly. >>> subprocess.check_output(["echo", "Hello World!"], universal_newlines=True) 'Hello World!\n' + >>> subprocess.check_output(["sed", "-e", "s/foo/bar/"], + ... input=b"when in the course of fooman events\n") + b'when in the course of barman events\n' + >>> subprocess.check_output("exit 1", shell=True) Traceback (most recent call last): ... @@ -167,10 +177,6 @@ use cases, the underlying :class:`Popen` interface can be used directly. ... shell=True) 'ls: non_existent_file: No such file or directory\n' - .. versionadded:: 3.1 - - .. - .. warning:: Invoking the system shell with ``shell=True`` can be a security hazard @@ -183,9 +189,13 @@ use cases, the underlying :class:`Popen` interface can be used directly. read in the current process, the child process may block if it generates enough output to the pipe to fill up the OS pipe buffer. + .. versionadded:: 3.1 + .. versionchanged:: 3.3 *timeout* was added. + .. versionchanged:: 3.4 + *input* was added. .. data:: DEVNULL @@ -619,6 +629,12 @@ Instances of the :class:`Popen` class have the following methods: :exc:`TimeoutExpired` exception. It is safe to catch this exception and retry the wait. + .. note:: + + The function is implemented using a busy loop (non-blocking call and + short sleeps). Use the :mod:`asyncio` module for an asynchronous wait: + see :class:`asyncio.create_subprocess_exec`. + .. warning:: This will deadlock when using ``stdout=PIPE`` and/or @@ -629,6 +645,11 @@ Instances of the :class:`Popen` class have the following methods: .. versionchanged:: 3.3 *timeout* was added. + .. deprecated:: 3.4 + + Do not use the undocumented *endtime* parameter. It is was + unintentionally exposed in 3.3 but was intended to be private + for internal use. Use *timeout* instead. .. method:: Popen.communicate(input=None, timeout=None) @@ -841,8 +862,6 @@ The :mod:`subprocess` module exposes the following constants. The new process has a new console, instead of inheriting its parent's console (the default). - This flag is always set when :class:`Popen` is created with ``shell=True``. - .. data:: CREATE_NEW_PROCESS_GROUP A :class:`Popen` ``creationflags`` parameter to specify that a new process @@ -1057,9 +1076,9 @@ handling consistency are valid for these functions. Return ``(status, output)`` of executing *cmd* in a shell. - Execute the string *cmd* in a shell with :class:`Popen` and return a 2-tuple - ``(status, output)`` via :func:`Popen.communicate`. Universal newlines mode - is used; see the notes on :ref:`frequently-used-arguments` for more details. + Execute the string *cmd* in a shell with :meth:`Popen.check_output` and + return a 2-tuple ``(status, output)``. Universal newlines mode is used; + see the notes on :ref:`frequently-used-arguments` for more details. A trailing newline is stripped from the output. The exit status for the command can be interpreted |