diff options
Diffstat (limited to 'Doc/library/subprocess.rst')
| -rw-r--r-- | Doc/library/subprocess.rst | 110 |
1 files changed, 90 insertions, 20 deletions
diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst index 4c0edb3..a0d8471 100644 --- a/Doc/library/subprocess.rst +++ b/Doc/library/subprocess.rst @@ -123,12 +123,14 @@ This module defines one class called :class:`Popen`: *stdin*, *stdout* and *stderr* specify the executed programs' standard input, standard output and standard error file handles, respectively. Valid values - are :data:`PIPE`, an existing file descriptor (a positive integer), an - existing :term:`file object`, and ``None``. :data:`PIPE` indicates that a - new pipe to the child should be created. With ``None``, no redirection will - occur; the child's file handles will be inherited from the parent. Additionally, - *stderr* can be :data:`STDOUT`, which indicates that the stderr data from the - applications should be captured into the same file handle as for stdout. + are :data:`PIPE`, :data:`DEVNULL`, an existing file descriptor (a positive + integer), an existing :term:`file object`, and ``None``. :data:`PIPE` + indicates that a new pipe to the child should be created. :data:`DEVNULL` + indicates that the special file :data:`os.devnull` will be used. With ``None``, + no redirection will occur; the child's file handles will be inherited from + the parent. Additionally, *stderr* can be :data:`STDOUT`, which indicates + that the stderr data from the applications should be captured into the same + file handle as for stdout. If *preexec_fn* is set to a callable object, this object will be called in the child process just before the child is executed. @@ -228,6 +230,15 @@ This module defines one class called :class:`Popen`: Added context manager support. +.. data:: DEVNULL + + Special value that can be used as the *stdin*, *stdout* or *stderr* argument + to :class:`Popen` and indicates that the special file :data:`os.devnull` + will be used. + + .. versionadded:: 3.3 + + .. data:: PIPE Special value that can be used as the *stdin*, *stdout* or *stderr* argument @@ -248,15 +259,21 @@ Convenience Functions This module also defines the following shortcut functions: -.. function:: call(*popenargs, **kwargs) +.. function:: call(*popenargs, timeout=None, **kwargs) Run command with arguments. Wait for command to complete, then return the :attr:`returncode` attribute. - The arguments are the same as for the :class:`Popen` constructor. Example:: + The arguments are the same as for the :class:`Popen` constructor, with the + exception of the *timeout* argument, which is given to :meth:`Popen.wait`. + Example:: >>> retcode = subprocess.call(["ls", "-l"]) + 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. + .. warning:: Like :meth:`Popen.wait`, this will deadlock when using @@ -264,34 +281,43 @@ This module also defines the following shortcut functions: generates enough output to a pipe such that it blocks waiting for the OS pipe buffer to accept more data. + .. versionchanged:: 3.3 + *timeout* was added. + -.. function:: check_call(*popenargs, **kwargs) +.. function:: check_call(*popenargs, timeout=None, **kwargs) Run command with arguments. Wait for command to complete. If the exit code was zero then return, otherwise raise :exc:`CalledProcessError`. The :exc:`CalledProcessError` object will have the return code in the :attr:`returncode` attribute. - The arguments are the same as for the :class:`Popen` constructor. Example:: + The arguments are the same as for the :func:`call` function. Example:: >>> subprocess.check_call(["ls", "-l"]) 0 + As in the :func:`call` function, if the timeout expires, the child process + will be killed and the wait retried. The :exc:`TimeoutExpired` exception + will be re-raised after the child process has terminated. + .. warning:: See the warning for :func:`call`. + .. versionchanged:: 3.3 + *timeout* was added. -.. function:: check_output(*popenargs, **kwargs) - Run command with arguments and return its output as a byte string. +.. function:: check_output(*popenargs, timeout=None, **kwargs) + + Run command with arguments and return its output as a bytes object. If the exit code was non-zero it raises a :exc:`CalledProcessError`. The :exc:`CalledProcessError` object will have the return code in the - :attr:`returncode` - attribute and output in the :attr:`output` attribute. + :attr:`returncode` attribute and output in the :attr:`output` attribute. - The arguments are the same as for the :class:`Popen` constructor. Example:: + The arguments are the same as for the :func:`call` function. Example:: >>> subprocess.check_output(["ls", "-l", "/dev/null"]) b'crw-rw-rw- 1 root root 1, 3 Oct 18 2007 /dev/null\n' @@ -304,8 +330,17 @@ This module also defines the following shortcut functions: ... stderr=subprocess.STDOUT) b'ls: non_existent_file: No such file or directory\n' + As in the :func:`call` function, if the timeout expires, the child process + will be killed and the wait retried. The :exc:`TimeoutExpired` exception + will be re-raised after the child process has terminated. The output from + the child process so far will be in the :attr:`output` attribute of the + exception. + .. versionadded:: 3.1 + .. versionchanged:: 3.3 + *timeout* was added. + .. function:: getstatusoutput(cmd) @@ -358,6 +393,15 @@ arguments. check_call() will raise :exc:`CalledProcessError`, if the called process returns a non-zero return code. +All of the functions and methods that accept a *timeout* parameter, such as +:func:`call` and :meth:`Popen.communicate` will raise :exc:`TimeoutExpired` if +the timeout expires before the process exits. + +Exceptions defined in this module all inherit from :exc:`SubprocessError`. + + .. versionadded:: 3.3 + The :exc:`SubprocessError` base class was added. + Security ^^^^^^^^ @@ -379,11 +423,15 @@ Instances of the :class:`Popen` class have the following methods: attribute. -.. method:: Popen.wait() +.. method:: Popen.wait(timeout=None) Wait for child process to terminate. Set and return :attr:`returncode` attribute. + If the process does not terminate after *timeout* seconds, raise a + :exc:`TimeoutExpired` exception. It is safe to catch this exception and + retry the wait. + .. warning:: This will deadlock when using ``stdout=PIPE`` and/or @@ -391,13 +439,17 @@ Instances of the :class:`Popen` class have the following methods: a pipe such that it blocks waiting for the OS pipe buffer to accept more data. Use :meth:`communicate` to avoid that. + .. versionchanged:: 3.3 + *timeout* was added. -.. method:: Popen.communicate(input=None) + +.. method:: Popen.communicate(input=None, timeout=None) Interact with process: Send data to stdin. Read data from stdout and stderr, - until end-of-file is reached. Wait for process to terminate. The optional - *input* argument should be a byte string to be sent to the child process, or - ``None``, if no data should be sent to the child. + until end-of-file is reached. Wait for process to terminate. The optional + *input* argument should be data to be sent to the child process, or + ``None``, if no data should be sent to the child. The type of *input* + must be bytes or, if *universal_newlines* was ``True``, a string. :meth:`communicate` returns a tuple ``(stdoutdata, stderrdata)``. @@ -406,11 +458,29 @@ Instances of the :class:`Popen` class have the following methods: ``None`` in the result tuple, you need to give ``stdout=PIPE`` and/or ``stderr=PIPE`` too. + If the process does not terminate after *timeout* seconds, a + :exc:`TimeoutExpired` exception will be raised. Catching this exception and + retrying communication will not lose any output. + + The child process is not killed if the timeout expires, so in order to + cleanup properly a well-behaved application should kill the child process and + finish communication:: + + proc = subprocess.Popen(...) + try: + outs, errs = proc.communicate(timeout=15) + except TimeoutExpired: + proc.kill() + outs, errs = proc.communicate() + .. note:: The data read is buffered in memory, so do not use this method if the data size is large or unlimited. + .. versionchanged:: 3.3 + *timeout* was added. + .. method:: Popen.send_signal(signal) |