cpython-lru_cache-weakref: Doc/library/subprocess.rst annotate

annotate Doc/library/subprocess.rst @ 54294:dba767bc3155 legacy-trunk

remove mention of old ctypes version

author	Benjamin Peterson <benjamin@python.org>
date	Sat, 23 May 2009 20:59:09 +0000
parents	1b62bffd2ef2
children	e4745838f655

rev	line source
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2 :mod:`subprocess` --- Subprocess management
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	3 ===========================================
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	4
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	5 .. module:: subprocess
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	6 :synopsis: Subprocess management.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	7 .. moduleauthor:: Peter Åstrand <astrand@lysator.liu.se>
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	8 .. sectionauthor:: Peter Åstrand <astrand@lysator.liu.se>
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	9
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	10
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	11 .. versionadded:: 2.4
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	12
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	13 The :mod:`subprocess` module allows you to spawn new processes, connect to their
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	14 input/output/error pipes, and obtain their return codes. This module intends to
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	15 replace several other, older modules and functions, such as::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	16
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	17 os.system
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	18 os.spawn*
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	19 os.popen*
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	20 popen2.*
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	21 commands.*
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	22
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	23 Information about how the :mod:`subprocess` module can be used to replace these
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	24 modules and functions can be found in the following sections.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	25
47862 e68fe90f15ab Add a link to PEP 324. Georg Brandl <georg@python.org> parents: 47805 diff changeset	26 .. seealso::
e68fe90f15ab Add a link to PEP 324. Georg Brandl <georg@python.org> parents: 47805 diff changeset	27
e68fe90f15ab Add a link to PEP 324. Georg Brandl <georg@python.org> parents: 47805 diff changeset	28 :pep:`324` -- PEP proposing the subprocess module
e68fe90f15ab Add a link to PEP 324. Georg Brandl <georg@python.org> parents: 47805 diff changeset	29
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	30
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	31 Using the subprocess Module
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	32 ---------------------------
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	33
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	34 This module defines one class called :class:`Popen`:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	35
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	36
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	37 .. class:: Popen(args, bufsize=0, executable=None, stdin=None, stdout=None, stderr=None, preexec_fn=None, close_fds=False, shell=False, cwd=None, env=None, universal_newlines=False, startupinfo=None, creationflags=0)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	38
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	39 Arguments are:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	40
48089 e3da869de98e clarify Popen argument Benjamin Peterson <benjamin@python.org> parents: 47862 diff changeset	41 args should be a string, or a sequence of program arguments. The program
e3da869de98e clarify Popen argument Benjamin Peterson <benjamin@python.org> parents: 47862 diff changeset	42 to execute is normally the first item in the args sequence or the string if a
e3da869de98e clarify Popen argument Benjamin Peterson <benjamin@python.org> parents: 47862 diff changeset	43 string is given, but can be explicitly set by using the executable
e3da869de98e clarify Popen argument Benjamin Peterson <benjamin@python.org> parents: 47862 diff changeset	44 argument.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	45
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	46 On Unix, with shell=False (default): In this case, the Popen class uses
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	47 :meth:`os.execvp` to execute the child program. args should normally be a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	48 sequence. A string will be treated as a sequence with the string as the only
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	49 item (the program to execute).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	50
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	51 On Unix, with shell=True: If args is a string, it specifies the command string
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	52 to execute through the shell. If args is a sequence, the first item specifies
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	53 the command string, and any additional items will be treated as additional shell
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	54 arguments.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	55
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	56 On Windows: the :class:`Popen` class uses CreateProcess() to execute the child
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	57 program, which operates on strings. If args is a sequence, it will be
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	58 converted to a string using the :meth:`list2cmdline` method. Please note that
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	59 not all MS Windows applications interpret the command line the same way:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	60 :meth:`list2cmdline` is designed for applications using the same rules as the MS
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	61 C runtime.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	62
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	63 bufsize, if given, has the same meaning as the corresponding argument to the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	64 built-in open() function: :const:`0` means unbuffered, :const:`1` means line
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	65 buffered, any other positive value means use a buffer of (approximately) that
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	66 size. A negative bufsize means to use the system default, which usually means
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	67 fully buffered. The default value for bufsize is :const:`0` (unbuffered).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	68
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	69 The executable argument specifies the program to execute. It is very seldom
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	70 needed: Usually, the program to execute is defined by the args argument. If
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	71 ``shell=True``, the executable argument specifies which shell to use. On Unix,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	72 the default shell is :file:`/bin/sh`. On Windows, the default shell is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	73 specified by the :envvar:`COMSPEC` environment variable.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	74
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	75 stdin, stdout and stderr specify the executed programs' standard input,
50042 a9068203afd5 Follow-up to #4488: document PIPE and STDOUT properly. Georg Brandl <georg@python.org> parents: 49994 diff changeset	76 standard output and standard error file handles, respectively. Valid values
a9068203afd5 Follow-up to #4488: document PIPE and STDOUT properly. Georg Brandl <georg@python.org> parents: 49994 diff changeset	77 are :data:`PIPE`, an existing file descriptor (a positive integer), an
a9068203afd5 Follow-up to #4488: document PIPE and STDOUT properly. Georg Brandl <georg@python.org> parents: 49994 diff changeset	78 existing file object, and ``None``. :data:`PIPE` indicates that a new pipe
a9068203afd5 Follow-up to #4488: document PIPE and STDOUT properly. Georg Brandl <georg@python.org> parents: 49994 diff changeset	79 to the child should be created. With ``None``, no redirection will occur;
a9068203afd5 Follow-up to #4488: document PIPE and STDOUT properly. Georg Brandl <georg@python.org> parents: 49994 diff changeset	80 the child's file handles will be inherited from the parent. Additionally,
a9068203afd5 Follow-up to #4488: document PIPE and STDOUT properly. Georg Brandl <georg@python.org> parents: 49994 diff changeset	81 stderr can be :data:`STDOUT`, which indicates that the stderr data from the
a9068203afd5 Follow-up to #4488: document PIPE and STDOUT properly. Georg Brandl <georg@python.org> parents: 49994 diff changeset	82 applications should be captured into the same file handle as for stdout.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	83
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	84 If preexec_fn is set to a callable object, this object will be called in the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	85 child process just before the child is executed. (Unix only)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	86
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	87 If close_fds is true, all file descriptors except :const:`0`, :const:`1` and
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	88 :const:`2` will be closed before the child process is executed. (Unix only).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	89 Or, on Windows, if close_fds is true then no handles will be inherited by the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	90 child process. Note that on Windows, you cannot set close_fds to true and
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	91 also redirect the standard handles by setting stdin, stdout or stderr.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	92
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	93 If shell is :const:`True`, the specified command will be executed through the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	94 shell.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	95
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	96 If cwd is not ``None``, the child's current directory will be changed to cwd
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	97 before it is executed. Note that this directory is not considered when
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	98 searching the executable, so you can't specify the program's path relative to
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	99 cwd.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	100
46483 374833de570c #2633: clarify meaning of env parameter. Georg Brandl <georg@python.org> parents: 46480 diff changeset	101 If env is not ``None``, it must be a mapping that defines the environment
374833de570c #2633: clarify meaning of env parameter. Georg Brandl <georg@python.org> parents: 46480 diff changeset	102 variables for the new process; these are used instead of inheriting the current
374833de570c #2633: clarify meaning of env parameter. Georg Brandl <georg@python.org> parents: 46480 diff changeset	103 process' environment, which is the default behavior.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	104
53173 5d4729c47033 Less red ink (warning->note) and add link to def of side-by-side assembly. R. David Murray <rdmurray@bitdance.com> parents: 53163 diff changeset	105 .. note::
53163 4628217b013c Fix for issue3440: add warning to subprocess discussion of R. David Murray <rdmurray@bitdance.com> parents: 51775 diff changeset	106
53173 5d4729c47033 Less red ink (warning->note) and add link to def of side-by-side assembly. R. David Murray <rdmurray@bitdance.com> parents: 53163 diff changeset	107 If specified, env must provide any variables required
5d4729c47033 Less red ink (warning->note) and add link to def of side-by-side assembly. R. David Murray <rdmurray@bitdance.com> parents: 53163 diff changeset	108 for the program to execute. On Windows, in order to run a
5d4729c47033 Less red ink (warning->note) and add link to def of side-by-side assembly. R. David Murray <rdmurray@bitdance.com> parents: 53163 diff changeset	109 `side-by-side assembly`_ the specified env must include a valid
53163 4628217b013c Fix for issue3440: add warning to subprocess discussion of R. David Murray <rdmurray@bitdance.com> parents: 51775 diff changeset	110 :envvar:`SystemRoot`.
4628217b013c Fix for issue3440: add warning to subprocess discussion of R. David Murray <rdmurray@bitdance.com> parents: 51775 diff changeset	111
53173 5d4729c47033 Less red ink (warning->note) and add link to def of side-by-side assembly. R. David Murray <rdmurray@bitdance.com> parents: 53163 diff changeset	112 .. _side-by-side assembly: http://en.wikipedia.org/wiki/Side-by-Side_Assembly
5d4729c47033 Less red ink (warning->note) and add link to def of side-by-side assembly. R. David Murray <rdmurray@bitdance.com> parents: 53163 diff changeset	113
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	114 If universal_newlines is :const:`True`, the file objects stdout and stderr are
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	115 opened as text files, but lines may be terminated by any of ``'\n'``, the Unix
49184 59db4b3a06b0 Remove things specific to the old Macintosh, and spell "Mac OS X" consistently. Georg Brandl <georg@python.org> parents: 48170 diff changeset	116 end-of-line convention, ``'\r'``, the old Macintosh convention or ``'\r\n'``, the
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	117 Windows convention. All of these external representations are seen as ``'\n'``
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	118 by the Python program.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	119
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	120 .. note::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	121
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	122 This feature is only available if Python is built with universal newline support
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	123 (the default). Also, the newlines attribute of the file objects :attr:`stdout`,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	124 :attr:`stdin` and :attr:`stderr` are not updated by the communicate() method.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	125
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	126 The startupinfo and creationflags, if given, will be passed to the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	127 underlying CreateProcess() function. They can specify things such as appearance
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	128 of the main window and priority for the new process. (Windows only)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	129
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	130
50042 a9068203afd5 Follow-up to #4488: document PIPE and STDOUT properly. Georg Brandl <georg@python.org> parents: 49994 diff changeset	131 .. data:: PIPE
a9068203afd5 Follow-up to #4488: document PIPE and STDOUT properly. Georg Brandl <georg@python.org> parents: 49994 diff changeset	132
a9068203afd5 Follow-up to #4488: document PIPE and STDOUT properly. Georg Brandl <georg@python.org> parents: 49994 diff changeset	133 Special value that can be used as the stdin, stdout or stderr argument
a9068203afd5 Follow-up to #4488: document PIPE and STDOUT properly. Georg Brandl <georg@python.org> parents: 49994 diff changeset	134 to :class:`Popen` and indicates that a pipe to the standard stream should be
a9068203afd5 Follow-up to #4488: document PIPE and STDOUT properly. Georg Brandl <georg@python.org> parents: 49994 diff changeset	135 opened.
a9068203afd5 Follow-up to #4488: document PIPE and STDOUT properly. Georg Brandl <georg@python.org> parents: 49994 diff changeset	136
a9068203afd5 Follow-up to #4488: document PIPE and STDOUT properly. Georg Brandl <georg@python.org> parents: 49994 diff changeset	137
a9068203afd5 Follow-up to #4488: document PIPE and STDOUT properly. Georg Brandl <georg@python.org> parents: 49994 diff changeset	138 .. data:: STDOUT
a9068203afd5 Follow-up to #4488: document PIPE and STDOUT properly. Georg Brandl <georg@python.org> parents: 49994 diff changeset	139
a9068203afd5 Follow-up to #4488: document PIPE and STDOUT properly. Georg Brandl <georg@python.org> parents: 49994 diff changeset	140 Special value that can be used as the stderr argument to :class:`Popen` and
a9068203afd5 Follow-up to #4488: document PIPE and STDOUT properly. Georg Brandl <georg@python.org> parents: 49994 diff changeset	141 indicates that standard error should go into the same handle as standard
a9068203afd5 Follow-up to #4488: document PIPE and STDOUT properly. Georg Brandl <georg@python.org> parents: 49994 diff changeset	142 output.
50508 c52177f36852 Remove trailing whitespace. Georg Brandl <georg@python.org> parents: 50042 diff changeset	143
50042 a9068203afd5 Follow-up to #4488: document PIPE and STDOUT properly. Georg Brandl <georg@python.org> parents: 49994 diff changeset	144
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	145 Convenience Functions
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	146 ^^^^^^^^^^^^^^^^^^^^^
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	147
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	148 This module also defines two shortcut functions:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	149
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	150
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	151 .. function:: call(popenargs, *kwargs)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	152
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	153 Run command with arguments. Wait for command to complete, then return the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	154 :attr:`returncode` attribute.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	155
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	156 The arguments are the same as for the Popen constructor. Example::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	157
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	158 retcode = call(["ls", "-l"])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	159
54239 1b62bffd2ef2 don't use subprocess.call with PIPEs as the child can fill the pipe buf and Philip Jenvey <pjenvey@underboss.org> parents: 53583 diff changeset	160 .. warning::
1b62bffd2ef2 don't use subprocess.call with PIPEs as the child can fill the pipe buf and Philip Jenvey <pjenvey@underboss.org> parents: 53583 diff changeset	161
1b62bffd2ef2 don't use subprocess.call with PIPEs as the child can fill the pipe buf and Philip Jenvey <pjenvey@underboss.org> parents: 53583 diff changeset	162 Like :meth:`Popen.wait`, this will deadlock if the child process
1b62bffd2ef2 don't use subprocess.call with PIPEs as the child can fill the pipe buf and Philip Jenvey <pjenvey@underboss.org> parents: 53583 diff changeset	163 generates enough output to a stdout or stderr pipe such that it blocks
1b62bffd2ef2 don't use subprocess.call with PIPEs as the child can fill the pipe buf and Philip Jenvey <pjenvey@underboss.org> parents: 53583 diff changeset	164 waiting for the OS pipe buffer to accept more data.
1b62bffd2ef2 don't use subprocess.call with PIPEs as the child can fill the pipe buf and Philip Jenvey <pjenvey@underboss.org> parents: 53583 diff changeset	165
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	166
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	167 .. function:: check_call(popenargs, *kwargs)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	168
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	169 Run command with arguments. Wait for command to complete. If the exit code was
49357 6765946e1ac4 Markup fixes. (optparse.rst probably needs an entire revision pass.) Andrew M. Kuchling <amk@amk.ca> parents: 49184 diff changeset	170 zero then return, otherwise raise :exc:`CalledProcessError`. The
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	171 :exc:`CalledProcessError` object will have the return code in the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	172 :attr:`returncode` attribute.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	173
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	174 The arguments are the same as for the Popen constructor. Example::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	175
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	176 check_call(["ls", "-l"])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	177
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	178 .. versionadded:: 2.5
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	179
54239 1b62bffd2ef2 don't use subprocess.call with PIPEs as the child can fill the pipe buf and Philip Jenvey <pjenvey@underboss.org> parents: 53583 diff changeset	180 .. warning::
1b62bffd2ef2 don't use subprocess.call with PIPEs as the child can fill the pipe buf and Philip Jenvey <pjenvey@underboss.org> parents: 53583 diff changeset	181
1b62bffd2ef2 don't use subprocess.call with PIPEs as the child can fill the pipe buf and Philip Jenvey <pjenvey@underboss.org> parents: 53583 diff changeset	182 See the warning for :func:`call`.
1b62bffd2ef2 don't use subprocess.call with PIPEs as the child can fill the pipe buf and Philip Jenvey <pjenvey@underboss.org> parents: 53583 diff changeset	183
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	184
49984 589cde614b5b rename the new check_call_output to check_output. its less ugly. Gregory P. Smith <greg@mad-scientist.com> parents: 49979 diff changeset	185 .. function:: check_output(popenargs, *kwargs)
49977 4790b31d9257 Adds a subprocess.check_call_output() function to return the output from a Gregory P. Smith <greg@mad-scientist.com> parents: 49677 diff changeset	186
4790b31d9257 Adds a subprocess.check_call_output() function to return the output from a Gregory P. Smith <greg@mad-scientist.com> parents: 49677 diff changeset	187 Run command with arguments and return its output as a byte string.
4790b31d9257 Adds a subprocess.check_call_output() function to return the output from a Gregory P. Smith <greg@mad-scientist.com> parents: 49677 diff changeset	188
50963 8763cf2f7e0c Markup fixes Andrew M. Kuchling <amk@amk.ca> parents: 50508 diff changeset	189 If the exit code was non-zero it raises a :exc:`CalledProcessError`. The
8763cf2f7e0c Markup fixes Andrew M. Kuchling <amk@amk.ca> parents: 50508 diff changeset	190 :exc:`CalledProcessError` object will have the return code in the
8763cf2f7e0c Markup fixes Andrew M. Kuchling <amk@amk.ca> parents: 50508 diff changeset	191 :attr:`returncode`
8763cf2f7e0c Markup fixes Andrew M. Kuchling <amk@amk.ca> parents: 50508 diff changeset	192 attribute and output in the :attr:`output` attribute.
49977 4790b31d9257 Adds a subprocess.check_call_output() function to return the output from a Gregory P. Smith <greg@mad-scientist.com> parents: 49677 diff changeset	193
53583 7459023ff861 Make the doctests in the docs pass, except for those in the turtle module. Georg Brandl <georg@python.org> parents: 53508 diff changeset	194 The arguments are the same as for the :class:`Popen` constructor. Example::
49977 4790b31d9257 Adds a subprocess.check_call_output() function to return the output from a Gregory P. Smith <greg@mad-scientist.com> parents: 49677 diff changeset	195
49984 589cde614b5b rename the new check_call_output to check_output. its less ugly. Gregory P. Smith <greg@mad-scientist.com> parents: 49979 diff changeset	196 >>> subprocess.check_output(["ls", "-l", "/dev/null"])
49977 4790b31d9257 Adds a subprocess.check_call_output() function to return the output from a Gregory P. Smith <greg@mad-scientist.com> parents: 49677 diff changeset	197 'crw-rw-rw- 1 root root 1, 3 Oct 18 2007 /dev/null\n'
4790b31d9257 Adds a subprocess.check_call_output() function to return the output from a Gregory P. Smith <greg@mad-scientist.com> parents: 49677 diff changeset	198
4790b31d9257 Adds a subprocess.check_call_output() function to return the output from a Gregory P. Smith <greg@mad-scientist.com> parents: 49677 diff changeset	199 The stdout argument is not allowed as it is used internally.
53583 7459023ff861 Make the doctests in the docs pass, except for those in the turtle module. Georg Brandl <georg@python.org> parents: 53508 diff changeset	200 To capture standard error in the result, use ``stderr=subprocess.STDOUT``::
49977 4790b31d9257 Adds a subprocess.check_call_output() function to return the output from a Gregory P. Smith <greg@mad-scientist.com> parents: 49677 diff changeset	201
49984 589cde614b5b rename the new check_call_output to check_output. its less ugly. Gregory P. Smith <greg@mad-scientist.com> parents: 49979 diff changeset	202 >>> subprocess.check_output(
51775 af9b6c43804e Issue #5341: Fix a variety of spelling errors. Mark Dickinson <dickinsm@gmail.com> parents: 50963 diff changeset	203 ["/bin/sh", "-c", "ls non_existent_file ; exit 0"],
49977 4790b31d9257 Adds a subprocess.check_call_output() function to return the output from a Gregory P. Smith <greg@mad-scientist.com> parents: 49677 diff changeset	204 stderr=subprocess.STDOUT)
51775 af9b6c43804e Issue #5341: Fix a variety of spelling errors. Mark Dickinson <dickinsm@gmail.com> parents: 50963 diff changeset	205 'ls: non_existent_file: No such file or directory\n'
49977 4790b31d9257 Adds a subprocess.check_call_output() function to return the output from a Gregory P. Smith <greg@mad-scientist.com> parents: 49677 diff changeset	206
4790b31d9257 Adds a subprocess.check_call_output() function to return the output from a Gregory P. Smith <greg@mad-scientist.com> parents: 49677 diff changeset	207 .. versionadded:: 2.7
4790b31d9257 Adds a subprocess.check_call_output() function to return the output from a Gregory P. Smith <greg@mad-scientist.com> parents: 49677 diff changeset	208
4790b31d9257 Adds a subprocess.check_call_output() function to return the output from a Gregory P. Smith <greg@mad-scientist.com> parents: 49677 diff changeset	209
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	210 Exceptions
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	211 ^^^^^^^^^^
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	212
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	213 Exceptions raised in the child process, before the new program has started to
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	214 execute, will be re-raised in the parent. Additionally, the exception object
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	215 will have one extra attribute called :attr:`child_traceback`, which is a string
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	216 containing traceback information from the childs point of view.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	217
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	218 The most common exception raised is :exc:`OSError`. This occurs, for example,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	219 when trying to execute a non-existent file. Applications should prepare for
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	220 :exc:`OSError` exceptions.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	221
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	222 A :exc:`ValueError` will be raised if :class:`Popen` is called with invalid
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	223 arguments.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	224
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	225 check_call() will raise :exc:`CalledProcessError`, if the called process returns
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	226 a non-zero return code.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	227
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	228
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	229 Security
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	230 ^^^^^^^^
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	231
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	232 Unlike some other popen functions, this implementation will never call /bin/sh
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	233 implicitly. This means that all characters, including shell metacharacters, can
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	234 safely be passed to child processes.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	235
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	236
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	237 Popen Objects
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	238 -------------
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	239
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	240 Instances of the :class:`Popen` class have the following methods:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	241
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	242
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	243 .. method:: Popen.poll()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	244
44529 d8979e6429e5 #1727024: document that Popen.returncode is set by Popen.poll/wait. Georg Brandl <georg@python.org> parents: 44005 diff changeset	245 Check if child process has terminated. Set and return :attr:`returncode`
d8979e6429e5 #1727024: document that Popen.returncode is set by Popen.poll/wait. Georg Brandl <georg@python.org> parents: 44005 diff changeset	246 attribute.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	247
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	248
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	249 .. method:: Popen.wait()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	250
44529 d8979e6429e5 #1727024: document that Popen.returncode is set by Popen.poll/wait. Georg Brandl <georg@python.org> parents: 44005 diff changeset	251 Wait for child process to terminate. Set and return :attr:`returncode`
d8979e6429e5 #1727024: document that Popen.returncode is set by Popen.poll/wait. Georg Brandl <georg@python.org> parents: 44005 diff changeset	252 attribute.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	253
48164 c235ba70e594 Fix markup. Georg Brandl <georg@python.org> parents: 48161 diff changeset	254 .. warning::
c235ba70e594 Fix markup. Georg Brandl <georg@python.org> parents: 48161 diff changeset	255
c235ba70e594 Fix markup. Georg Brandl <georg@python.org> parents: 48161 diff changeset	256 This will deadlock if the child process generates enough output to a
48170 21745563e680 more cleanup ups of the recently added warnings in the subprocess docs. Gregory P. Smith <greg@mad-scientist.com> parents: 48164 diff changeset	257 stdout or stderr pipe such that it blocks waiting for the OS pipe buffer
21745563e680 more cleanup ups of the recently added warnings in the subprocess docs. Gregory P. Smith <greg@mad-scientist.com> parents: 48164 diff changeset	258 to accept more data. Use :meth:`communicate` to avoid that.
48161 8bd5650193c6 issue1606: Add warnings to the subprocess documentation about common pitfalls Gregory P. Smith <greg@mad-scientist.com> parents: 48089 diff changeset	259
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	260
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	261 .. method:: Popen.communicate(input=None)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	262
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	263 Interact with process: Send data to stdin. Read data from stdout and stderr,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	264 until end-of-file is reached. Wait for process to terminate. The optional
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	265 input argument should be a string to be sent to the child process, or
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	266 ``None``, if no data should be sent to the child.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	267
49979 cd5f56a81cce Clarification to avoid confusing output with file descriptors. Georg Brandl <georg@python.org> parents: 49977 diff changeset	268 :meth:`communicate` returns a tuple ``(stdoutdata, stderrdata)``.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	269
44005 d3be6e615f8c #1344: document that you need to open std{in,out,err} with PIPE if you want Georg Brandl <georg@python.org> parents: 42603 diff changeset	270 Note that if you want to send data to the process's stdin, you need to create
d3be6e615f8c #1344: document that you need to open std{in,out,err} with PIPE if you want Georg Brandl <georg@python.org> parents: 42603 diff changeset	271 the Popen object with ``stdin=PIPE``. Similarly, to get anything other than
d3be6e615f8c #1344: document that you need to open std{in,out,err} with PIPE if you want Georg Brandl <georg@python.org> parents: 42603 diff changeset	272 ``None`` in the result tuple, you need to give ``stdout=PIPE`` and/or
d3be6e615f8c #1344: document that you need to open std{in,out,err} with PIPE if you want Georg Brandl <georg@python.org> parents: 42603 diff changeset	273 ``stderr=PIPE`` too.
d3be6e615f8c #1344: document that you need to open std{in,out,err} with PIPE if you want Georg Brandl <georg@python.org> parents: 42603 diff changeset	274
44529 d8979e6429e5 #1727024: document that Popen.returncode is set by Popen.poll/wait. Georg Brandl <georg@python.org> parents: 44005 diff changeset	275 .. note::
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	276
44529 d8979e6429e5 #1727024: document that Popen.returncode is set by Popen.poll/wait. Georg Brandl <georg@python.org> parents: 44005 diff changeset	277 The data read is buffered in memory, so do not use this method if the data
d8979e6429e5 #1727024: document that Popen.returncode is set by Popen.poll/wait. Georg Brandl <georg@python.org> parents: 44005 diff changeset	278 size is large or unlimited.
d8979e6429e5 #1727024: document that Popen.returncode is set by Popen.poll/wait. Georg Brandl <georg@python.org> parents: 44005 diff changeset	279
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	280
46479 e16593da4898 Added kill, terminate and send_signal to subprocess.Popen Christian Heimes <christian@cheimes.de> parents: 44529 diff changeset	281 .. method:: Popen.send_signal(signal)
e16593da4898 Added kill, terminate and send_signal to subprocess.Popen Christian Heimes <christian@cheimes.de> parents: 44529 diff changeset	282
e16593da4898 Added kill, terminate and send_signal to subprocess.Popen Christian Heimes <christian@cheimes.de> parents: 44529 diff changeset	283 Sends the signal signal to the child.
e16593da4898 Added kill, terminate and send_signal to subprocess.Popen Christian Heimes <christian@cheimes.de> parents: 44529 diff changeset	284
e16593da4898 Added kill, terminate and send_signal to subprocess.Popen Christian Heimes <christian@cheimes.de> parents: 44529 diff changeset	285 .. note::
e16593da4898 Added kill, terminate and send_signal to subprocess.Popen Christian Heimes <christian@cheimes.de> parents: 44529 diff changeset	286
e16593da4898 Added kill, terminate and send_signal to subprocess.Popen Christian Heimes <christian@cheimes.de> parents: 44529 diff changeset	287 On Windows only SIGTERM is supported so far. It's an alias for
46480 e029d7c7de81 Fix-up docs for revision 62386. Georg Brandl <georg@python.org> parents: 46479 diff changeset	288 :meth:`terminate`.
e029d7c7de81 Fix-up docs for revision 62386. Georg Brandl <georg@python.org> parents: 46479 diff changeset	289
e029d7c7de81 Fix-up docs for revision 62386. Georg Brandl <georg@python.org> parents: 46479 diff changeset	290 .. versionadded:: 2.6
46479 e16593da4898 Added kill, terminate and send_signal to subprocess.Popen Christian Heimes <christian@cheimes.de> parents: 44529 diff changeset	291
e16593da4898 Added kill, terminate and send_signal to subprocess.Popen Christian Heimes <christian@cheimes.de> parents: 44529 diff changeset	292
e16593da4898 Added kill, terminate and send_signal to subprocess.Popen Christian Heimes <christian@cheimes.de> parents: 44529 diff changeset	293 .. method:: Popen.terminate()
e16593da4898 Added kill, terminate and send_signal to subprocess.Popen Christian Heimes <christian@cheimes.de> parents: 44529 diff changeset	294
e16593da4898 Added kill, terminate and send_signal to subprocess.Popen Christian Heimes <christian@cheimes.de> parents: 44529 diff changeset	295 Stop the child. On Posix OSs the method sends SIGTERM to the
46510 406eca2ddbbc Markup fix Andrew M. Kuchling <amk@amk.ca> parents: 46483 diff changeset	296 child. On Windows the Win32 API function :cfunc:`TerminateProcess` is called
46479 e16593da4898 Added kill, terminate and send_signal to subprocess.Popen Christian Heimes <christian@cheimes.de> parents: 44529 diff changeset	297 to stop the child.
e16593da4898 Added kill, terminate and send_signal to subprocess.Popen Christian Heimes <christian@cheimes.de> parents: 44529 diff changeset	298
46480 e029d7c7de81 Fix-up docs for revision 62386. Georg Brandl <georg@python.org> parents: 46479 diff changeset	299 .. versionadded:: 2.6
e029d7c7de81 Fix-up docs for revision 62386. Georg Brandl <georg@python.org> parents: 46479 diff changeset	300
46479 e16593da4898 Added kill, terminate and send_signal to subprocess.Popen Christian Heimes <christian@cheimes.de> parents: 44529 diff changeset	301
e16593da4898 Added kill, terminate and send_signal to subprocess.Popen Christian Heimes <christian@cheimes.de> parents: 44529 diff changeset	302 .. method:: Popen.kill()
e16593da4898 Added kill, terminate and send_signal to subprocess.Popen Christian Heimes <christian@cheimes.de> parents: 44529 diff changeset	303
e16593da4898 Added kill, terminate and send_signal to subprocess.Popen Christian Heimes <christian@cheimes.de> parents: 44529 diff changeset	304 Kills the child. On Posix OSs the function sends SIGKILL to the child.
46480 e029d7c7de81 Fix-up docs for revision 62386. Georg Brandl <georg@python.org> parents: 46479 diff changeset	305 On Windows :meth:`kill` is an alias for :meth:`terminate`.
e029d7c7de81 Fix-up docs for revision 62386. Georg Brandl <georg@python.org> parents: 46479 diff changeset	306
e029d7c7de81 Fix-up docs for revision 62386. Georg Brandl <georg@python.org> parents: 46479 diff changeset	307 .. versionadded:: 2.6
46479 e16593da4898 Added kill, terminate and send_signal to subprocess.Popen Christian Heimes <christian@cheimes.de> parents: 44529 diff changeset	308
e16593da4898 Added kill, terminate and send_signal to subprocess.Popen Christian Heimes <christian@cheimes.de> parents: 44529 diff changeset	309
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	310 The following attributes are also available:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	311
48164 c235ba70e594 Fix markup. Georg Brandl <georg@python.org> parents: 48161 diff changeset	312 .. warning::
c235ba70e594 Fix markup. Georg Brandl <georg@python.org> parents: 48161 diff changeset	313
53508 57812944c961 Demote warnings to notices where appropriate, following the goal that as few "red box" warnings Georg Brandl <georg@python.org> parents: 53173 diff changeset	314 Use :meth:`communicate` rather than :attr:`.stdin.write <stdin>`,
57812944c961 Demote warnings to notices where appropriate, following the goal that as few "red box" warnings Georg Brandl <georg@python.org> parents: 53173 diff changeset	315 :attr:`.stdout.read <stdout>` or :attr:`.stderr.read <stderr>` to avoid
57812944c961 Demote warnings to notices where appropriate, following the goal that as few "red box" warnings Georg Brandl <georg@python.org> parents: 53173 diff changeset	316 deadlocks due to any of the other OS pipe buffers filling up and blocking the
57812944c961 Demote warnings to notices where appropriate, following the goal that as few "red box" warnings Georg Brandl <georg@python.org> parents: 53173 diff changeset	317 child process.
48164 c235ba70e594 Fix markup. Georg Brandl <georg@python.org> parents: 48161 diff changeset	318
c235ba70e594 Fix markup. Georg Brandl <georg@python.org> parents: 48161 diff changeset	319
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	320 .. attribute:: Popen.stdin
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	321
50042 a9068203afd5 Follow-up to #4488: document PIPE and STDOUT properly. Georg Brandl <georg@python.org> parents: 49994 diff changeset	322 If the stdin argument was :data:`PIPE`, this attribute is a file object
a9068203afd5 Follow-up to #4488: document PIPE and STDOUT properly. Georg Brandl <georg@python.org> parents: 49994 diff changeset	323 that provides input to the child process. Otherwise, it is ``None``.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	324
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	325
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	326 .. attribute:: Popen.stdout
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	327
50042 a9068203afd5 Follow-up to #4488: document PIPE and STDOUT properly. Georg Brandl <georg@python.org> parents: 49994 diff changeset	328 If the stdout argument was :data:`PIPE`, this attribute is a file object
a9068203afd5 Follow-up to #4488: document PIPE and STDOUT properly. Georg Brandl <georg@python.org> parents: 49994 diff changeset	329 that provides output from the child process. Otherwise, it is ``None``.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	330
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	331
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	332 .. attribute:: Popen.stderr
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	333
50042 a9068203afd5 Follow-up to #4488: document PIPE and STDOUT properly. Georg Brandl <georg@python.org> parents: 49994 diff changeset	334 If the stderr argument was :data:`PIPE`, this attribute is a file object
a9068203afd5 Follow-up to #4488: document PIPE and STDOUT properly. Georg Brandl <georg@python.org> parents: 49994 diff changeset	335 that provides error output from the child process. Otherwise, it is
a9068203afd5 Follow-up to #4488: document PIPE and STDOUT properly. Georg Brandl <georg@python.org> parents: 49994 diff changeset	336 ``None``.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	337
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	338
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	339 .. attribute:: Popen.pid
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	340
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	341 The process ID of the child process.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	342
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	343
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	344 .. attribute:: Popen.returncode
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	345
44529 d8979e6429e5 #1727024: document that Popen.returncode is set by Popen.poll/wait. Georg Brandl <georg@python.org> parents: 44005 diff changeset	346 The child return code, set by :meth:`poll` and :meth:`wait` (and indirectly
d8979e6429e5 #1727024: document that Popen.returncode is set by Popen.poll/wait. Georg Brandl <georg@python.org> parents: 44005 diff changeset	347 by :meth:`communicate`). A ``None`` value indicates that the process
d8979e6429e5 #1727024: document that Popen.returncode is set by Popen.poll/wait. Georg Brandl <georg@python.org> parents: 44005 diff changeset	348 hasn't terminated yet.
50508 c52177f36852 Remove trailing whitespace. Georg Brandl <georg@python.org> parents: 50042 diff changeset	349
44529 d8979e6429e5 #1727024: document that Popen.returncode is set by Popen.poll/wait. Georg Brandl <georg@python.org> parents: 44005 diff changeset	350 A negative value ``-N`` indicates that the child was terminated by signal
d8979e6429e5 #1727024: document that Popen.returncode is set by Popen.poll/wait. Georg Brandl <georg@python.org> parents: 44005 diff changeset	351 ``N`` (Unix only).
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	352
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	353
47800 70e1a38c9805 Turn section references into proper cross-references. Georg Brandl <georg@python.org> parents: 46510 diff changeset	354 .. _subprocess-replacements:
70e1a38c9805 Turn section references into proper cross-references. Georg Brandl <georg@python.org> parents: 46510 diff changeset	355
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	356 Replacing Older Functions with the subprocess Module
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	357 ----------------------------------------------------
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	358
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	359 In this section, "a ==> b" means that b can be used as a replacement for a.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	360
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	361 .. note::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	362
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	363 All functions in this section fail (more or less) silently if the executed
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	364 program cannot be found; this module raises an :exc:`OSError` exception.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	365
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	366 In the following examples, we assume that the subprocess module is imported with
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	367 "from subprocess import \*".
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	368
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	369
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	370 Replacing /bin/sh shell backquote
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	371 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	372
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	373 ::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	374
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	375 output=`mycmd myarg`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	376 ==>
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	377 output = Popen(["mycmd", "myarg"], stdout=PIPE).communicate()[0]
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	378
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	379
49677 82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49357 diff changeset	380 Replacing shell pipeline
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49357 diff changeset	381 ^^^^^^^^^^^^^^^^^^^^^^^^
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	382
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	383 ::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	384
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	385 output=`dmesg \| grep hda`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	386 ==>
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	387 p1 = Popen(["dmesg"], stdout=PIPE)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	388 p2 = Popen(["grep", "hda"], stdin=p1.stdout, stdout=PIPE)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	389 output = p2.communicate()[0]
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	390
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	391
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	392 Replacing os.system()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	393 ^^^^^^^^^^^^^^^^^^^^^
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	394
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	395 ::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	396
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	397 sts = os.system("mycmd" + " myarg")
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	398 ==>
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	399 p = Popen("mycmd" + " myarg", shell=True)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	400 sts = os.waitpid(p.pid, 0)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	401
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	402 Notes:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	403
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	404 * Calling the program through the shell is usually not required.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	405
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	406 * It's easier to look at the :attr:`returncode` attribute than the exit status.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	407
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	408 A more realistic example would look like this::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	409
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	410 try:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	411 retcode = call("mycmd" + " myarg", shell=True)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	412 if retcode < 0:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	413 print >>sys.stderr, "Child was terminated by signal", -retcode
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	414 else:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	415 print >>sys.stderr, "Child returned", retcode
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	416 except OSError, e:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	417 print >>sys.stderr, "Execution failed:", e
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	418
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	419
49994 c319d2474f57 #4409: fix asterisks looking like footnotes. Georg Brandl <georg@python.org> parents: 49984 diff changeset	420 Replacing the os.spawn family
c319d2474f57 #4409: fix asterisks looking like footnotes. Georg Brandl <georg@python.org> parents: 49984 diff changeset	421 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	422
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	423 P_NOWAIT example::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	424
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	425 pid = os.spawnlp(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg")
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	426 ==>
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	427 pid = Popen(["/bin/mycmd", "myarg"]).pid
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	428
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	429 P_WAIT example::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	430
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	431 retcode = os.spawnlp(os.P_WAIT, "/bin/mycmd", "mycmd", "myarg")
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	432 ==>
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	433 retcode = call(["/bin/mycmd", "myarg"])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	434
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	435 Vector example::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	436
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	437 os.spawnvp(os.P_NOWAIT, path, args)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	438 ==>
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	439 Popen([path] + args[1:])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	440
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	441 Environment example::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	442
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	443 os.spawnlpe(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg", env)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	444 ==>
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	445 Popen(["/bin/mycmd", "myarg"], env={"PATH": "/usr/bin"})
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	446
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	447
49994 c319d2474f57 #4409: fix asterisks looking like footnotes. Georg Brandl <georg@python.org> parents: 49984 diff changeset	448 Replacing os.popen, os.popen2, os.popen3
c319d2474f57 #4409: fix asterisks looking like footnotes. Georg Brandl <georg@python.org> parents: 49984 diff changeset	449 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	450
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	451 ::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	452
47805 65c23663d0bd #3085: Fix syntax error. Georg Brandl <georg@python.org> parents: 47800 diff changeset	453 pipe = os.popen(cmd, 'r', bufsize)
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	454 ==>
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	455 pipe = Popen(cmd, shell=True, bufsize=bufsize, stdout=PIPE).stdout
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	456
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	457 ::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	458
47805 65c23663d0bd #3085: Fix syntax error. Georg Brandl <georg@python.org> parents: 47800 diff changeset	459 pipe = os.popen(cmd, 'w', bufsize)
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	460 ==>
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	461 pipe = Popen(cmd, shell=True, bufsize=bufsize, stdin=PIPE).stdin
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	462
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	463 ::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	464
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	465 (child_stdin, child_stdout) = os.popen2(cmd, mode, bufsize)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	466 ==>
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	467 p = Popen(cmd, shell=True, bufsize=bufsize,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	468 stdin=PIPE, stdout=PIPE, close_fds=True)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	469 (child_stdin, child_stdout) = (p.stdin, p.stdout)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	470
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	471 ::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	472
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	473 (child_stdin,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	474 child_stdout,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	475 child_stderr) = os.popen3(cmd, mode, bufsize)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	476 ==>
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	477 p = Popen(cmd, shell=True, bufsize=bufsize,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	478 stdin=PIPE, stdout=PIPE, stderr=PIPE, close_fds=True)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	479 (child_stdin,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	480 child_stdout,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	481 child_stderr) = (p.stdin, p.stdout, p.stderr)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	482
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	483 ::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	484
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	485 (child_stdin, child_stdout_and_stderr) = os.popen4(cmd, mode, bufsize)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	486 ==>
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	487 p = Popen(cmd, shell=True, bufsize=bufsize,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	488 stdin=PIPE, stdout=PIPE, stderr=STDOUT, close_fds=True)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	489 (child_stdin, child_stdout_and_stderr) = (p.stdin, p.stdout)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	490
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	491
49994 c319d2474f57 #4409: fix asterisks looking like footnotes. Georg Brandl <georg@python.org> parents: 49984 diff changeset	492 Replacing functions from the popen2 module
c319d2474f57 #4409: fix asterisks looking like footnotes. Georg Brandl <georg@python.org> parents: 49984 diff changeset	493 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	494
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	495 .. note::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	496
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	497 If the cmd argument to popen2 functions is a string, the command is executed
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	498 through /bin/sh. If it is a list, the command is directly executed.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	499
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	500 ::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	501
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	502 (child_stdout, child_stdin) = popen2.popen2("somestring", bufsize, mode)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	503 ==>
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	504 p = Popen(["somestring"], shell=True, bufsize=bufsize,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	505 stdin=PIPE, stdout=PIPE, close_fds=True)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	506 (child_stdout, child_stdin) = (p.stdout, p.stdin)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	507
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	508 ::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	509
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	510 (child_stdout, child_stdin) = popen2.popen2(["mycmd", "myarg"], bufsize, mode)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	511 ==>
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	512 p = Popen(["mycmd", "myarg"], bufsize=bufsize,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	513 stdin=PIPE, stdout=PIPE, close_fds=True)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	514 (child_stdout, child_stdin) = (p.stdout, p.stdin)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	515
50042 a9068203afd5 Follow-up to #4488: document PIPE and STDOUT properly. Georg Brandl <georg@python.org> parents: 49994 diff changeset	516 :class:`popen2.Popen3` and :class:`popen2.Popen4` basically work as
a9068203afd5 Follow-up to #4488: document PIPE and STDOUT properly. Georg Brandl <georg@python.org> parents: 49994 diff changeset	517 :class:`subprocess.Popen`, except that:
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	518
50042 a9068203afd5 Follow-up to #4488: document PIPE and STDOUT properly. Georg Brandl <georg@python.org> parents: 49994 diff changeset	519 * :class:`Popen` raises an exception if the execution fails.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	520
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	521 * the capturestderr argument is replaced with the stderr argument.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	522
50042 a9068203afd5 Follow-up to #4488: document PIPE and STDOUT properly. Georg Brandl <georg@python.org> parents: 49994 diff changeset	523 * ``stdin=PIPE`` and ``stdout=PIPE`` must be specified.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	524
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	525 * popen2 closes all file descriptors by default, but you have to specify
50042 a9068203afd5 Follow-up to #4488: document PIPE and STDOUT properly. Georg Brandl <georg@python.org> parents: 49994 diff changeset	526 ``close_fds=True`` with :class:`Popen`.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	527

Mercurial > cpython-lru_cache-weakref

annotate Doc/library/subprocess.rst @ 54294:dba767bc3155 legacy-trunk