[Python-checkins] cpython (merge 3.5 -> 3.6): Issue #26240: Merge subprocess doc string from 3.5 into 3.6
martin.panter
python-checkins at python.org
Tue Oct 25 21:17:24 EDT 2016
https://hg.python.org/cpython/rev/8358c68579e9
changeset: 104730:8358c68579e9
branch: 3.6
parent: 104727:6b46c3deea2c
parent: 104729:720865fa61a4
user: Martin Panter <vadmium+py at gmail.com>
date: Tue Oct 25 23:41:42 2016 +0000
summary:
Issue #26240: Merge subprocess doc string from 3.5 into 3.6
files:
Lib/subprocess.py | 411 ++++++---------------------------
Misc/ACKS | 1 +
2 files changed, 77 insertions(+), 335 deletions(-)
diff --git a/Lib/subprocess.py b/Lib/subprocess.py
--- a/Lib/subprocess.py
+++ b/Lib/subprocess.py
@@ -7,343 +7,38 @@
# Licensed to PSF under a Contributor Agreement.
# See http://www.python.org/2.4/license for licensing details.
-r"""subprocess - Subprocesses with accessible I/O streams
+r"""Subprocesses with accessible I/O streams
This module allows you to spawn processes, connect to their
-input/output/error pipes, and obtain their return codes. This module
-intends to replace several older modules and functions:
+input/output/error pipes, and obtain their return codes.
-os.system
-os.spawn*
+For a complete description of this module see the Python documentation.
-Information about how the subprocess module can be used to replace these
-modules and functions can be found below.
+Main API
+========
+run(...): Runs a command, waits for it to complete, then returns a
+ CompletedProcess instance.
+Popen(...): A class for flexibly executing a command in a new process
+Constants
+---------
+DEVNULL: Special value that indicates that os.devnull should be used
+PIPE: Special value that indicates a pipe should be created
+STDOUT: Special value that indicates that stderr should go to stdout
-Using the subprocess module
-===========================
-This module defines one class called Popen:
-
-class Popen(args, bufsize=-1, executable=None,
- stdin=None, stdout=None, stderr=None,
- preexec_fn=None, close_fds=True, shell=False,
- cwd=None, env=None, universal_newlines=False,
- startupinfo=None, creationflags=0,
- restore_signals=True, start_new_session=False, pass_fds=(),
- *, encoding=None, errors=None):
-
-
-Arguments are:
-
-args should be a string, or a sequence of program arguments. The
-program to execute is normally the first item in the args sequence or
-string, but can be explicitly set by using the executable argument.
-
-On POSIX, with shell=False (default): In this case, the Popen class
-uses os.execvp() to execute the child program. args should normally
-be a sequence. A string will be treated as a sequence with the string
-as the only item (the program to execute).
-
-On POSIX, with shell=True: If args is a string, it specifies the
-command string to execute through the shell. If args is a sequence,
-the first item specifies the command string, and any additional items
-will be treated as additional shell arguments.
-
-On Windows: the Popen class uses CreateProcess() to execute the child
-program, which operates on strings. If args is a sequence, it will be
-converted to a string using the list2cmdline method. Please note that
-not all MS Windows applications interpret the command line the same
-way: The list2cmdline is designed for applications using the same
-rules as the MS C runtime.
-
-bufsize will be supplied as the corresponding argument to the io.open()
-function when creating the stdin/stdout/stderr pipe file objects:
-0 means unbuffered (read & write are one system call and can return short),
-1 means line buffered, any other positive value means use a buffer of
-approximately that size. A negative bufsize, the default, means the system
-default of io.DEFAULT_BUFFER_SIZE will be used.
-
-stdin, stdout and stderr specify the executed programs' standard
-input, standard output and standard error file handles, respectively.
-Valid values are PIPE, an existing file descriptor (a positive
-integer), an existing file object, and None. 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 STDOUT, which indicates that the
-stderr data from the applications should be captured into the same
-file handle as for stdout.
-
-On POSIX, if preexec_fn is set to a callable object, this object will be
-called in the child process just before the child is executed. The use
-of preexec_fn is not thread safe, using it in the presence of threads
-could lead to a deadlock in the child process before the new executable
-is executed.
-
-If close_fds is true, all file descriptors except 0, 1 and 2 will be
-closed before the child process is executed. The default for close_fds
-varies by platform: Always true on POSIX. True when stdin/stdout/stderr
-are None on Windows, false otherwise.
-
-pass_fds is an optional sequence of file descriptors to keep open between the
-parent and child. Providing any pass_fds implicitly sets close_fds to true.
-
-if shell is true, the specified command will be executed through the
-shell.
-
-If cwd is not None, the current directory will be changed to cwd
-before the child is executed.
-
-On POSIX, if restore_signals is True all signals that Python sets to
-SIG_IGN are restored to SIG_DFL in the child process before the exec.
-Currently this includes the SIGPIPE, SIGXFZ and SIGXFSZ signals. This
-parameter does nothing on Windows.
-
-On POSIX, if start_new_session is True, the setsid() system call will be made
-in the child process prior to executing the command.
-
-If env is not None, it defines the environment variables for the new
-process.
-
-If encoding or errors are specified or universal_newlines is True, the file
-objects stdout and stderr are opened in text mode. See io.TextIOWrapper for
-the interpretation of these parameters are used.
-
-If no encoding is specified and universal_newlines is False, the file
-objects stdin, stdout and stderr are opened as binary files, and no
-line ending conversion is done.
-
-The startupinfo and creationflags, if given, will be passed to the
-underlying CreateProcess() function. They can specify things such as
-appearance of the main window and priority for the new process.
-(Windows only)
-
-
-This module also defines some shortcut functions:
-
-call(*popenargs, **kwargs):
- Run command with arguments. Wait for command to complete, then
- return the returncode attribute.
-
- The arguments are the same as for the Popen constructor. Example:
-
- >>> retcode = subprocess.call(["ls", "-l"])
-
-check_call(*popenargs, **kwargs):
- Run command with arguments. Wait for command to complete. If the
- exit code was zero then return, otherwise raise
- CalledProcessError. The CalledProcessError object will have the
- return code in the returncode attribute.
-
- The arguments are the same as for the Popen constructor. Example:
-
- >>> subprocess.check_call(["ls", "-l"])
- 0
-
-getstatusoutput(cmd):
- Return (status, output) of executing cmd in a shell.
-
- Execute the string 'cmd' in a shell with 'check_output' and
- return a 2-tuple (status, output). Universal newlines mode is used,
- meaning that the result with be decoded to a string.
-
- A trailing newline is stripped from the output.
- The exit status for the command can be interpreted
- according to the rules for the function 'wait'. Example:
-
- >>> subprocess.getstatusoutput('ls /bin/ls')
- (0, '/bin/ls')
- >>> subprocess.getstatusoutput('cat /bin/junk')
- (256, 'cat: /bin/junk: No such file or directory')
- >>> subprocess.getstatusoutput('/bin/junk')
- (256, 'sh: /bin/junk: not found')
-
-getoutput(cmd):
- Return output (stdout or stderr) of executing cmd in a shell.
-
- Like getstatusoutput(), except the exit status is ignored and the return
- value is a string containing the command's output. Example:
-
- >>> subprocess.getoutput('ls /bin/ls')
- '/bin/ls'
-
-check_output(*popenargs, **kwargs):
- Run command with arguments and return its output.
-
- If the exit code was non-zero it raises a CalledProcessError. The
- CalledProcessError object will have the return code in the returncode
- attribute and output in the output attribute.
-
- The arguments are the same as for the Popen constructor. Example:
-
- >>> output = subprocess.check_output(["ls", "-l", "/dev/null"])
-
- There is an additional optional argument, "input", allowing you to
- pass a string to the subprocess's stdin. If you use this argument
- you may not also use the Popen constructor's "stdin" argument.
-
- If universal_newlines is set to True, the "input" argument must
- be a string rather than bytes, and the return value will be a string.
-
-Exceptions
-----------
-Exceptions raised in the child process, before the new program has
-started to execute, will be re-raised in the parent. Additionally,
-the exception object will have one extra attribute called
-'child_traceback', which is a string containing traceback information
-from the child's point of view.
-
-The most common exception raised is OSError. This occurs, for
-example, when trying to execute a non-existent file. Applications
-should prepare for OSErrors.
-
-A ValueError will be raised if Popen is called with invalid arguments.
-
-Exceptions defined within this module inherit from SubprocessError.
-check_call() and check_output() will raise CalledProcessError if the
-called process returns a non-zero return code. TimeoutExpired
-be raised if a timeout was specified and expired.
-
-
-Security
---------
-Unlike some other popen functions, this implementation will never call
-/bin/sh implicitly. This means that all characters, including shell
-metacharacters, can safely be passed to child processes.
-
-
-Popen objects
-=============
-Instances of the Popen class have the following methods:
-
-poll()
- Check if child process has terminated. Returns returncode
- attribute.
-
-wait()
- Wait for child process to terminate. Returns returncode attribute.
-
-communicate(input=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 data to be
- sent to the child process, or None, if no data should be sent to
- the child. If the Popen instance was constructed in text mode, the
- input argument should be a string. Otherwise, it should be bytes.
-
- communicate() returns a tuple (stdout, stderr).
-
- Note: The data read is buffered in memory, so do not use this
- method if the data size is large or unlimited.
-
-The following attributes are also available:
-
-stdin
- If the stdin argument is PIPE, this attribute is a file object
- that provides input to the child process. Otherwise, it is None.
-
-stdout
- If the stdout argument is PIPE, this attribute is a file object
- that provides output from the child process. Otherwise, it is
- None.
-
-stderr
- If the stderr argument is PIPE, this attribute is file object that
- provides error output from the child process. Otherwise, it is
- None.
-
-pid
- The process ID of the child process.
-
-returncode
- The child return code. A None value indicates that the process
- hasn't terminated yet. A negative value -N indicates that the
- child was terminated by signal N (POSIX only).
-
-
-Replacing older functions with the subprocess module
-====================================================
-In this section, "a ==> b" means that b can be used as a replacement
-for a.
-
-Note: All functions in this section fail (more or less) silently if
-the executed program cannot be found; this module raises an OSError
-exception.
-
-In the following examples, we assume that the subprocess module is
-imported with "from subprocess import *".
-
-
-Replacing /bin/sh shell backquote
----------------------------------
-output=`mycmd myarg`
-==>
-output = Popen(["mycmd", "myarg"], stdout=PIPE).communicate()[0]
-
-
-Replacing shell pipe line
--------------------------
-output=`dmesg | grep hda`
-==>
-p1 = Popen(["dmesg"], stdout=PIPE)
-p2 = Popen(["grep", "hda"], stdin=p1.stdout, stdout=PIPE)
-output = p2.communicate()[0]
-
-
-Replacing os.system()
----------------------
-sts = os.system("mycmd" + " myarg")
-==>
-p = Popen("mycmd" + " myarg", shell=True)
-pid, sts = os.waitpid(p.pid, 0)
-
-Note:
-
-* Calling the program through the shell is usually not required.
-
-* It's easier to look at the returncode attribute than the
- exitstatus.
-
-A more real-world example would look like this:
-
-try:
- retcode = call("mycmd" + " myarg", shell=True)
- if retcode < 0:
- print("Child was terminated by signal", -retcode, file=sys.stderr)
- else:
- print("Child returned", retcode, file=sys.stderr)
-except OSError as e:
- print("Execution failed:", e, file=sys.stderr)
-
-
-Replacing os.spawn*
--------------------
-P_NOWAIT example:
-
-pid = os.spawnlp(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg")
-==>
-pid = Popen(["/bin/mycmd", "myarg"]).pid
-
-
-P_WAIT example:
-
-retcode = os.spawnlp(os.P_WAIT, "/bin/mycmd", "mycmd", "myarg")
-==>
-retcode = call(["/bin/mycmd", "myarg"])
-
-
-Vector example:
-
-os.spawnvp(os.P_NOWAIT, path, args)
-==>
-Popen([path] + args[1:])
-
-
-Environment example:
-
-os.spawnlpe(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg", env)
-==>
-Popen(["/bin/mycmd", "myarg"], env={"PATH": "/usr/bin"})
+Older API
+=========
+call(...): Runs a command, waits for it to complete, then returns
+ the return code.
+check_call(...): Same as call() but raises CalledProcessError()
+ if return code is not 0
+check_output(...): Same as check_call() but returns the contents of
+ stdout instead of a return code
+getoutput(...): Runs a command in the shell, waits for it to complete,
+ then returns the output
+getstatusoutput(...): Runs a command in the shell, waits for it to complete,
+ then returns a (status, output) tuple
"""
import sys
@@ -363,12 +58,11 @@
class CalledProcessError(SubprocessError):
- """Raised when a check_call() or check_output() process returns non-zero.
+ """Raised when run() is called with check=True and the process
+ returns a non-zero exit status.
- The exit status will be stored in the returncode attribute, negative
- if it represents a signal number.
-
- check_output() will also store the output in the output attribute.
+ Attributes:
+ cmd, returncode, stdout, stderr, output
"""
def __init__(self, returncode, cmd, output=None, stderr=None):
self.returncode = returncode
@@ -403,6 +97,9 @@
class TimeoutExpired(SubprocessError):
"""This exception is raised when the timeout expires while waiting for a
child process.
+
+ Attributes:
+ cmd, output, stdout, stderr, timeout
"""
def __init__(self, cmd, timeout, output=None, stderr=None):
self.cmd = cmd
@@ -841,7 +538,49 @@
class Popen(object):
+ """ Execute a child program in a new process.
+ For a complete description of the arguments see the Python documentation.
+
+ Arguments:
+ args: A string, or a sequence of program arguments.
+
+ bufsize: supplied as the buffering argument to the open() function when
+ creating the stdin/stdout/stderr pipe file objects
+
+ executable: A replacement program to execute.
+
+ stdin, stdout and stderr: These specify the executed programs' standard
+ input, standard output and standard error file handles, respectively.
+
+ preexec_fn: (POSIX only) An object to be called in the child process
+ just before the child is executed.
+
+ close_fds: Controls closing or inheriting of file descriptors.
+
+ shell: If true, the command will be executed through the shell.
+
+ cwd: Sets the current directory before the child is executed.
+
+ env: Defines the environment variables for the new process.
+
+ universal_newlines: If true, use universal line endings for file
+ objects stdin, stdout and stderr.
+
+ startupinfo and creationflags (Windows only)
+
+ restore_signals (POSIX only)
+
+ start_new_session (POSIX only)
+
+ pass_fds (POSIX only)
+
+ encoding and errors: Text mode encoding and error handling to use for
+ file objects stdin, stdout and stderr.
+
+ Attributes:
+ stdin, stdout, stderr, pid, returncode
+ """
_child_created = False # Set here since __del__ checks it
def __init__(self, args, bufsize=-1, executable=None,
@@ -1104,6 +843,8 @@
def poll(self):
+ """Check if child process has terminated. Set and return returncode
+ attribute."""
return self._internal_poll()
diff --git a/Misc/ACKS b/Misc/ACKS
--- a/Misc/ACKS
+++ b/Misc/ACKS
@@ -1013,6 +1013,7 @@
Andrii V. Mishkovskyi
Dom Mitchell
Dustin J. Mitchell
+Tim Mitchell
Zubin Mithra
Florian Mladitsch
Doug Moen
--
Repository URL: https://hg.python.org/cpython
More information about the Python-checkins
mailing list