Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libsubprocess.tex @ 39042:c02fa187e0f4 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Part of SF patch #1484695. This removes dead code. The chksum was already verified in .frombuf() on the lines above. If there was a problem an exception is raised, so there was no way this condition could have been true.
author Neal Norwitz <nnorwitz@gmail.com>
date Mon, 10 Jul 2006 00:23:17 +0000
parents 8c86ca8f2682
children 9f2c3de74856 654c380cf8b9
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
33774
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
1 \section{\module{subprocess} --- Subprocess management}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
2
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
3 \declaremodule{standard}{subprocess}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
4 \modulesynopsis{Subprocess management.}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
5 \moduleauthor{Peter \AA strand}{astrand@lysator.liu.se}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
6 \sectionauthor{Peter \AA strand}{astrand@lysator.liu.se}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
7
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
8 \versionadded{2.4}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
9
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
10 The \module{subprocess} module allows you to spawn new processes,
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
11 connect to their input/output/error pipes, and obtain their return
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
12 codes. This module intends to replace several other, older modules
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
13 and functions, such as:
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
14
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
15 % XXX Should add pointers to this module to at least the popen2
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
16 % and commands sections.
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
17
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
18 \begin{verbatim}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
19 os.system
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
20 os.spawn*
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
21 os.popen*
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
22 popen2.*
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
23 commands.*
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
24 \end{verbatim}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
25
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
26 Information about how the \module{subprocess} module can be used to
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
27 replace these modules and functions can be found in the following
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
28 sections.
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
29
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
30 \subsection{Using the subprocess Module}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
31
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
32 This module defines one class called \class{Popen}:
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
33
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
34 \begin{classdesc}{Popen}{args, bufsize=0, executable=None,
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
35 stdin=None, stdout=None, stderr=None,
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
36 preexec_fn=None, close_fds=False, shell=False,
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
37 cwd=None, env=None, universal_newlines=False,
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
38 startupinfo=None, creationflags=0}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
39
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
40 Arguments are:
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
41
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
42 \var{args} should be a string, or a sequence of program arguments. The
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
43 program to execute is normally the first item in the args sequence or
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
44 string, but can be explicitly set by using the executable argument.
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
45
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
46 On \UNIX{}, with \var{shell=False} (default): In this case, the Popen
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
47 class uses \method{os.execvp()} to execute the child program.
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
48 \var{args} should normally be a sequence. A string will be treated as a
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
49 sequence with the string as the only item (the program to execute).
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
50
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
51 On \UNIX{}, with \var{shell=True}: If args is a string, it specifies the
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
52 command string to execute through the shell. If \var{args} is a
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
53 sequence, the first item specifies the command string, and any
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
54 additional items will be treated as additional shell arguments.
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
55
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
56 On Windows: the \class{Popen} class uses CreateProcess() to execute
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
57 the child program, which operates on strings. If \var{args} is a
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
58 sequence, it will be converted to a string using the
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
59 \method{list2cmdline} method. Please note that not all MS Windows
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
60 applications interpret the command line the same way:
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
61 \method{list2cmdline} is designed for applications using the same
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
62 rules as the MS C runtime.
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
63
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
64 \var{bufsize}, if given, has the same meaning as the corresponding
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
65 argument to the built-in open() function: \constant{0} means unbuffered,
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
66 \constant{1} means line buffered, any other positive value means use a
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
67 buffer of (approximately) that size. A negative \var{bufsize} means to
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
68 use the system default, which usually means fully buffered. The default
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
69 value for \var{bufsize} is \constant{0} (unbuffered).
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
70
33934
0ae28c3a8d24 Added more documentation about the executable argument.
Peter Astrand <astrand@lysator.liu.se>
parents: 33774
diff changeset
71 The \var{executable} argument specifies the program to execute. It is
0ae28c3a8d24 Added more documentation about the executable argument.
Peter Astrand <astrand@lysator.liu.se>
parents: 33774
diff changeset
72 very seldom needed: Usually, the program to execute is defined by the
38142
8c86ca8f2682 Bug #1485447: subprocess: document that the "cwd" parameter isn't used to find the executable. Misc. other markup fixes.
Georg Brandl <georg@python.org>
parents: 37064
diff changeset
73 \var{args} argument. If \code{shell=True}, the \var{executable}
33934
0ae28c3a8d24 Added more documentation about the executable argument.
Peter Astrand <astrand@lysator.liu.se>
parents: 33774
diff changeset
74 argument specifies which shell to use. On \UNIX{}, the default shell
38142
8c86ca8f2682 Bug #1485447: subprocess: document that the "cwd" parameter isn't used to find the executable. Misc. other markup fixes.
Georg Brandl <georg@python.org>
parents: 37064
diff changeset
75 is \file{/bin/sh}. On Windows, the default shell is specified by the
8c86ca8f2682 Bug #1485447: subprocess: document that the "cwd" parameter isn't used to find the executable. Misc. other markup fixes.
Georg Brandl <georg@python.org>
parents: 37064
diff changeset
76 \envvar{COMSPEC} environment variable.
33934
0ae28c3a8d24 Added more documentation about the executable argument.
Peter Astrand <astrand@lysator.liu.se>
parents: 33774
diff changeset
77
33774
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
78 \var{stdin}, \var{stdout} and \var{stderr} specify the executed
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
79 programs' standard input, standard output and standard error file
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
80 handles, respectively. Valid values are \code{PIPE}, an existing file
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
81 descriptor (a positive integer), an existing file object, and
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
82 \code{None}. \code{PIPE} indicates that a new pipe to the child
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
83 should be created. With \code{None}, no redirection will occur; the
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
84 child's file handles will be inherited from the parent. Additionally,
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
85 \var{stderr} can be \code{STDOUT}, which indicates that the stderr
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
86 data from the applications should be captured into the same file
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
87 handle as for stdout.
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
88
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
89 If \var{preexec_fn} is set to a callable object, this object will be
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
90 called in the child process just before the child is executed.
38142
8c86ca8f2682 Bug #1485447: subprocess: document that the "cwd" parameter isn't used to find the executable. Misc. other markup fixes.
Georg Brandl <georg@python.org>
parents: 37064
diff changeset
91 (\UNIX{} only)
33774
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
92
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
93 If \var{close_fds} is true, all file descriptors except \constant{0},
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
94 \constant{1} and \constant{2} will be closed before the child process is
38142
8c86ca8f2682 Bug #1485447: subprocess: document that the "cwd" parameter isn't used to find the executable. Misc. other markup fixes.
Georg Brandl <georg@python.org>
parents: 37064
diff changeset
95 executed. (\UNIX{} only)
33774
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
96
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
97 If \var{shell} is \constant{True}, the specified command will be
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
98 executed through the shell.
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
99
38142
8c86ca8f2682 Bug #1485447: subprocess: document that the "cwd" parameter isn't used to find the executable. Misc. other markup fixes.
Georg Brandl <georg@python.org>
parents: 37064
diff changeset
100 If \var{cwd} is not \code{None}, the child's current directory will be
8c86ca8f2682 Bug #1485447: subprocess: document that the "cwd" parameter isn't used to find the executable. Misc. other markup fixes.
Georg Brandl <georg@python.org>
parents: 37064
diff changeset
101 changed to \var{cwd} before it is executed. Note that this directory
8c86ca8f2682 Bug #1485447: subprocess: document that the "cwd" parameter isn't used to find the executable. Misc. other markup fixes.
Georg Brandl <georg@python.org>
parents: 37064
diff changeset
102 is not considered when searching the executable, so you can't specify
8c86ca8f2682 Bug #1485447: subprocess: document that the "cwd" parameter isn't used to find the executable. Misc. other markup fixes.
Georg Brandl <georg@python.org>
parents: 37064
diff changeset
103 the program's path relative to \var{cwd}.
33774
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
104
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
105 If \var{env} is not \code{None}, it defines the environment variables
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
106 for the new process.
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
107
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
108 If \var{universal_newlines} is \constant{True}, the file objects stdout
36166
6f25029de9db Bug #1394868: doc typos
Georg Brandl <georg@python.org>
parents: 34906
diff changeset
109 and stderr are opened as text files, but lines may be terminated by
33774
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
110 any of \code{'\e n'}, the Unix end-of-line convention, \code{'\e r'},
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
111 the Macintosh convention or \code{'\e r\e n'}, the Windows convention.
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
112 All of these external representations are seen as \code{'\e n'} by the
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
113 Python program. \note{This feature is only available if Python is built
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
114 with universal newline support (the default). Also, the newlines
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
115 attribute of the file objects \member{stdout}, \member{stdin} and
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
116 \member{stderr} are not updated by the communicate() method.}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
117
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
118 The \var{startupinfo} and \var{creationflags}, if given, will be
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
119 passed to the underlying CreateProcess() function. They can specify
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
120 things such as appearance of the main window and priority for the new
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
121 process. (Windows only)
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
122 \end{classdesc}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
123
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
124 \subsubsection{Convenience Functions}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
125
34302
998fb1e1c8e9 New subprocess utility function: check_call. Closes #1071764.
Peter Astrand <astrand@lysator.liu.se>
parents: 34111
diff changeset
126 This module also defines two shortcut functions:
33774
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
127
34111
73b09c2b788b Changed signature of call function to avoid confusion: this 'args' is not the same as the one to the Popen constructor
Peter Astrand <astrand@lysator.liu.se>
parents: 34050
diff changeset
128 \begin{funcdesc}{call}{*popenargs, **kwargs}
33774
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
129 Run command with arguments. Wait for command to complete, then
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
130 return the \member{returncode} attribute.
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
131
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
132 The arguments are the same as for the Popen constructor. Example:
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
133
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
134 \begin{verbatim}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
135 retcode = call(["ls", "-l"])
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
136 \end{verbatim}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
137 \end{funcdesc}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
138
34302
998fb1e1c8e9 New subprocess utility function: check_call. Closes #1071764.
Peter Astrand <astrand@lysator.liu.se>
parents: 34111
diff changeset
139 \begin{funcdesc}{check_call}{*popenargs, **kwargs}
998fb1e1c8e9 New subprocess utility function: check_call. Closes #1071764.
Peter Astrand <astrand@lysator.liu.se>
parents: 34111
diff changeset
140 Run command with arguments. Wait for command to complete. If the exit
37064
64c83e0f683e More \exception fixes.
Georg Brandl <georg@python.org>
parents: 36440
diff changeset
141 code was zero then return, otherwise raise \exception{CalledProcessError.}
64c83e0f683e More \exception fixes.
Georg Brandl <georg@python.org>
parents: 36440
diff changeset
142 The \exception{CalledProcessError} object will have the return code in the
34302
998fb1e1c8e9 New subprocess utility function: check_call. Closes #1071764.
Peter Astrand <astrand@lysator.liu.se>
parents: 34111
diff changeset
143 \member{errno} attribute.
998fb1e1c8e9 New subprocess utility function: check_call. Closes #1071764.
Peter Astrand <astrand@lysator.liu.se>
parents: 34111
diff changeset
144
998fb1e1c8e9 New subprocess utility function: check_call. Closes #1071764.
Peter Astrand <astrand@lysator.liu.se>
parents: 34111
diff changeset
145 The arguments are the same as for the Popen constructor. Example:
998fb1e1c8e9 New subprocess utility function: check_call. Closes #1071764.
Peter Astrand <astrand@lysator.liu.se>
parents: 34111
diff changeset
146
998fb1e1c8e9 New subprocess utility function: check_call. Closes #1071764.
Peter Astrand <astrand@lysator.liu.se>
parents: 34111
diff changeset
147 \begin{verbatim}
998fb1e1c8e9 New subprocess utility function: check_call. Closes #1071764.
Peter Astrand <astrand@lysator.liu.se>
parents: 34111
diff changeset
148 check_call(["ls", "-l"])
998fb1e1c8e9 New subprocess utility function: check_call. Closes #1071764.
Peter Astrand <astrand@lysator.liu.se>
parents: 34111
diff changeset
149 \end{verbatim}
998fb1e1c8e9 New subprocess utility function: check_call. Closes #1071764.
Peter Astrand <astrand@lysator.liu.se>
parents: 34111
diff changeset
150 \end{funcdesc}
33774
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
151
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
152 \subsubsection{Exceptions}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
153
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
154 Exceptions raised in the child process, before the new program has
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
155 started to execute, will be re-raised in the parent. Additionally,
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
156 the exception object will have one extra attribute called
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
157 \member{child_traceback}, which is a string containing traceback
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
158 information from the childs point of view.
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
159
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
160 The most common exception raised is \exception{OSError}. This occurs,
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
161 for example, when trying to execute a non-existent file. Applications
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
162 should prepare for \exception{OSError} exceptions.
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
163
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
164 A \exception{ValueError} will be raised if \class{Popen} is called
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
165 with invalid arguments.
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
166
34302
998fb1e1c8e9 New subprocess utility function: check_call. Closes #1071764.
Peter Astrand <astrand@lysator.liu.se>
parents: 34111
diff changeset
167 check_call() will raise \exception{CalledProcessError}, which is a
998fb1e1c8e9 New subprocess utility function: check_call. Closes #1071764.
Peter Astrand <astrand@lysator.liu.se>
parents: 34111
diff changeset
168 subclass of \exception{OSError}, if the called process returns a
998fb1e1c8e9 New subprocess utility function: check_call. Closes #1071764.
Peter Astrand <astrand@lysator.liu.se>
parents: 34111
diff changeset
169 non-zero return code.
998fb1e1c8e9 New subprocess utility function: check_call. Closes #1071764.
Peter Astrand <astrand@lysator.liu.se>
parents: 34111
diff changeset
170
33774
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
171
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
172 \subsubsection{Security}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
173
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
174 Unlike some other popen functions, this implementation will never call
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
175 /bin/sh implicitly. This means that all characters, including shell
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
176 metacharacters, can safely be passed to child processes.
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
177
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
178
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
179 \subsection{Popen Objects}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
180
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
181 Instances of the \class{Popen} class have the following methods:
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
182
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
183 \begin{methoddesc}{poll}{}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
184 Check if child process has terminated. Returns returncode
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
185 attribute.
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
186 \end{methoddesc}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
187
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
188 \begin{methoddesc}{wait}{}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
189 Wait for child process to terminate. Returns returncode attribute.
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
190 \end{methoddesc}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
191
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
192 \begin{methoddesc}{communicate}{input=None}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
193 Interact with process: Send data to stdin. Read data from stdout and
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
194 stderr, until end-of-file is reached. Wait for process to terminate.
34906
fc442c2eb0cf SF patch #1180062 by George Yoshida:
Walter Dörwald <walter@livinglogic.de>
parents: 34302
diff changeset
195 The optional \var{input} argument should be a string to be sent to the
33774
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
196 child process, or \code{None}, if no data should be sent to the child.
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
197
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
198 communicate() returns a tuple (stdout, stderr).
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
199
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
200 \note{The data read is buffered in memory, so do not use this method
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
201 if the data size is large or unlimited.}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
202 \end{methoddesc}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
203
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
204 The following attributes are also available:
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
205
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
206 \begin{memberdesc}{stdin}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
207 If the \var{stdin} argument is \code{PIPE}, this attribute is a file
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
208 object that provides input to the child process. Otherwise, it is
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
209 \code{None}.
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
210 \end{memberdesc}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
211
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
212 \begin{memberdesc}{stdout}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
213 If the \var{stdout} argument is \code{PIPE}, this attribute is a file
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
214 object that provides output from the child process. Otherwise, it is
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
215 \code{None}.
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
216 \end{memberdesc}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
217
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
218 \begin{memberdesc}{stderr}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
219 If the \var{stderr} argument is \code{PIPE}, this attribute is file
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
220 object that provides error output from the child process. Otherwise,
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
221 it is \code{None}.
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
222 \end{memberdesc}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
223
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
224 \begin{memberdesc}{pid}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
225 The process ID of the child process.
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
226 \end{memberdesc}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
227
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
228 \begin{memberdesc}{returncode}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
229 The child return code. A \code{None} value indicates that the process
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
230 hasn't terminated yet. A negative value -N indicates that the child
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
231 was terminated by signal N (\UNIX{} only).
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
232 \end{memberdesc}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
233
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
234
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
235 \subsection{Replacing Older Functions with the subprocess Module}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
236
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
237 In this section, "a ==> b" means that b can be used as a replacement
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
238 for a.
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
239
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
240 \note{All functions in this section fail (more or less) silently if
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
241 the executed program cannot be found; this module raises an
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
242 \exception{OSError} exception.}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
243
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
244 In the following examples, we assume that the subprocess module is
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
245 imported with "from subprocess import *".
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
246
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
247 \subsubsection{Replacing /bin/sh shell backquote}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
248
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
249 \begin{verbatim}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
250 output=`mycmd myarg`
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
251 ==>
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
252 output = Popen(["mycmd", "myarg"], stdout=PIPE).communicate()[0]
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
253 \end{verbatim}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
254
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
255 \subsubsection{Replacing shell pipe line}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
256
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
257 \begin{verbatim}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
258 output=`dmesg | grep hda`
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
259 ==>
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
260 p1 = Popen(["dmesg"], stdout=PIPE)
34050
fd1be494c31b Corrected example for replacing shell pipeline. Fixes bug 1073790.
Peter Astrand <astrand@lysator.liu.se>
parents: 33934
diff changeset
261 p2 = Popen(["grep", "hda"], stdin=p1.stdout, stdout=PIPE)
33774
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
262 output = p2.communicate()[0]
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
263 \end{verbatim}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
264
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
265 \subsubsection{Replacing os.system()}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
266
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
267 \begin{verbatim}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
268 sts = os.system("mycmd" + " myarg")
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
269 ==>
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
270 p = Popen("mycmd" + " myarg", shell=True)
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
271 sts = os.waitpid(p.pid, 0)
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
272 \end{verbatim}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
273
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
274 Notes:
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
275
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
276 \begin{itemize}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
277 \item Calling the program through the shell is usually not required.
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
278 \item It's easier to look at the \member{returncode} attribute than
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
279 the exit status.
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
280 \end{itemize}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
281
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
282 A more realistic example would look like this:
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
283
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
284 \begin{verbatim}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
285 try:
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
286 retcode = call("mycmd" + " myarg", shell=True)
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
287 if retcode < 0:
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
288 print >>sys.stderr, "Child was terminated by signal", -retcode
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
289 else:
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
290 print >>sys.stderr, "Child returned", retcode
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
291 except OSError, e:
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
292 print >>sys.stderr, "Execution failed:", e
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
293 \end{verbatim}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
294
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
295 \subsubsection{Replacing os.spawn*}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
296
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
297 P_NOWAIT example:
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
298
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
299 \begin{verbatim}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
300 pid = os.spawnlp(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg")
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
301 ==>
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
302 pid = Popen(["/bin/mycmd", "myarg"]).pid
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
303 \end{verbatim}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
304
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
305 P_WAIT example:
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
306
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
307 \begin{verbatim}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
308 retcode = os.spawnlp(os.P_WAIT, "/bin/mycmd", "mycmd", "myarg")
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
309 ==>
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
310 retcode = call(["/bin/mycmd", "myarg"])
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
311 \end{verbatim}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
312
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
313 Vector example:
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
314
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
315 \begin{verbatim}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
316 os.spawnvp(os.P_NOWAIT, path, args)
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
317 ==>
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
318 Popen([path] + args[1:])
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
319 \end{verbatim}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
320
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
321 Environment example:
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
322
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
323 \begin{verbatim}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
324 os.spawnlpe(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg", env)
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
325 ==>
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
326 Popen(["/bin/mycmd", "myarg"], env={"PATH": "/usr/bin"})
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
327 \end{verbatim}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
328
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
329 \subsubsection{Replacing os.popen*}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
330
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
331 \begin{verbatim}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
332 pipe = os.popen(cmd, mode='r', bufsize)
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
333 ==>
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
334 pipe = Popen(cmd, shell=True, bufsize=bufsize, stdout=PIPE).stdout
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
335 \end{verbatim}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
336
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
337 \begin{verbatim}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
338 pipe = os.popen(cmd, mode='w', bufsize)
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
339 ==>
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
340 pipe = Popen(cmd, shell=True, bufsize=bufsize, stdin=PIPE).stdin
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
341 \end{verbatim}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
342
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
343 \begin{verbatim}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
344 (child_stdin, child_stdout) = os.popen2(cmd, mode, bufsize)
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
345 ==>
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
346 p = Popen(cmd, shell=True, bufsize=bufsize,
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
347 stdin=PIPE, stdout=PIPE, close_fds=True)
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
348 (child_stdin, child_stdout) = (p.stdin, p.stdout)
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
349 \end{verbatim}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
350
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
351 \begin{verbatim}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
352 (child_stdin,
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
353 child_stdout,
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
354 child_stderr) = os.popen3(cmd, mode, bufsize)
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
355 ==>
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
356 p = Popen(cmd, shell=True, bufsize=bufsize,
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
357 stdin=PIPE, stdout=PIPE, stderr=PIPE, close_fds=True)
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
358 (child_stdin,
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
359 child_stdout,
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
360 child_stderr) = (p.stdin, p.stdout, p.stderr)
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
361 \end{verbatim}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
362
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
363 \begin{verbatim}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
364 (child_stdin, child_stdout_and_stderr) = os.popen4(cmd, mode, bufsize)
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
365 ==>
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
366 p = Popen(cmd, shell=True, bufsize=bufsize,
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
367 stdin=PIPE, stdout=PIPE, stderr=STDOUT, close_fds=True)
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
368 (child_stdin, child_stdout_and_stderr) = (p.stdin, p.stdout)
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
369 \end{verbatim}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
370
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
371 \subsubsection{Replacing popen2.*}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
372
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
373 \note{If the cmd argument to popen2 functions is a string, the command
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
374 is executed through /bin/sh. If it is a list, the command is directly
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
375 executed.}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
376
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
377 \begin{verbatim}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
378 (child_stdout, child_stdin) = popen2.popen2("somestring", bufsize, mode)
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
379 ==>
34906
fc442c2eb0cf SF patch #1180062 by George Yoshida:
Walter Dörwald <walter@livinglogic.de>
parents: 34302
diff changeset
380 p = Popen(["somestring"], shell=True, bufsize=bufsize,
33774
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
381 stdin=PIPE, stdout=PIPE, close_fds=True)
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
382 (child_stdout, child_stdin) = (p.stdout, p.stdin)
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
383 \end{verbatim}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
384
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
385 \begin{verbatim}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
386 (child_stdout, child_stdin) = popen2.popen2(["mycmd", "myarg"], bufsize, mode)
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
387 ==>
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
388 p = Popen(["mycmd", "myarg"], bufsize=bufsize,
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
389 stdin=PIPE, stdout=PIPE, close_fds=True)
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
390 (child_stdout, child_stdin) = (p.stdout, p.stdin)
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
391 \end{verbatim}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
392
36440
5e2acf7441bd SF bug 1415455, fix typo in module name
Neal Norwitz <nnorwitz@gmail.com>
parents: 36166
diff changeset
393 The popen2.Popen3 and popen2.Popen4 basically works as subprocess.Popen,
33774
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
394 except that:
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
395
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
396 \begin{itemize}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
397 \item subprocess.Popen raises an exception if the execution fails
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
398
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
399 \item the \var{capturestderr} argument is replaced with the \var{stderr}
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
400 argument.
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
401
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
402 \item stdin=PIPE and stdout=PIPE must be specified.
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
403
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
404 \item popen2 closes all file descriptors by default, but you have to
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
405 specify close_fds=True with subprocess.Popen.
fbacbb262789 SF Patch #1048341: subprocess documentation, based on PEP/docstring by
Fredrik Lundh <fredrik@pythonware.com>
parents:
diff changeset
406 \end{itemize}