Commit | Line | Data |
---|---|---|
920dae64 AT |
1 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
2 | <html> | |
3 | <head> | |
4 | <link rel="STYLESHEET" href="whatsnew24.css" type='text/css' /> | |
5 | <link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" /> | |
6 | <link rel='start' href='../index.html' title='Python Documentation Index' /> | |
7 | <link rel="first" href="whatsnew24.html" title='What's New in Python 2.4' /> | |
8 | <link rel='contents' href='contents.html' title="Contents" /> | |
9 | <link rel='last' href='about.html' title='About this document...' /> | |
10 | <link rel='help' href='about.html' title='About this document...' /> | |
11 | <link rel="next" href="node9.html" /> | |
12 | <link rel="prev" href="node7.html" /> | |
13 | <link rel="parent" href="whatsnew24.html" /> | |
14 | <link rel="next" href="node9.html" /> | |
15 | <meta name='aesop' content='information' /> | |
16 | <title>7 PEP 324: New subprocess Module</title> | |
17 | </head> | |
18 | <body> | |
19 | <DIV CLASS="navigation"> | |
20 | <div id='top-navigation-panel' xml:id='top-navigation-panel'> | |
21 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> | |
22 | <tr> | |
23 | <td class='online-navigation'><a rel="prev" title="6 PEP 322: Reverse" | |
24 | href="node7.html"><img src='../icons/previous.png' | |
25 | border='0' height='32' alt='Previous Page' width='32' /></A></td> | |
26 | <td class='online-navigation'><a rel="parent" title="What's New in Python" | |
27 | href="whatsnew24.html"><img src='../icons/up.png' | |
28 | border='0' height='32' alt='Up One Level' width='32' /></A></td> | |
29 | <td class='online-navigation'><a rel="next" title="8 PEP 327: Decimal" | |
30 | href="node9.html"><img src='../icons/next.png' | |
31 | border='0' height='32' alt='Next Page' width='32' /></A></td> | |
32 | <td align="center" width="100%">What's New in Python 2.4</td> | |
33 | <td class='online-navigation'><a rel="contents" title="Table of Contents" | |
34 | href="contents.html"><img src='../icons/contents.png' | |
35 | border='0' height='32' alt='Contents' width='32' /></A></td> | |
36 | <td class='online-navigation'><img src='../icons/blank.png' | |
37 | border='0' height='32' alt='' width='32' /></td> | |
38 | <td class='online-navigation'><img src='../icons/blank.png' | |
39 | border='0' height='32' alt='' width='32' /></td> | |
40 | </tr></table> | |
41 | <div class='online-navigation'> | |
42 | <b class="navlabel">Previous:</b> | |
43 | <a class="sectref" rel="prev" href="node7.html">6 PEP 322: Reverse</A> | |
44 | <b class="navlabel">Up:</b> | |
45 | <a class="sectref" rel="parent" href="whatsnew24.html">What's New in Python</A> | |
46 | <b class="navlabel">Next:</b> | |
47 | <a class="sectref" rel="next" href="node9.html">8 PEP 327: Decimal</A> | |
48 | </div> | |
49 | <hr /></div> | |
50 | </DIV> | |
51 | <!--End of Navigation Panel--> | |
52 | ||
53 | <H1><A NAME="SECTION000800000000000000000"> | |
54 | 7 PEP 324: New subprocess Module</A> | |
55 | </H1> | |
56 | ||
57 | <P> | |
58 | The standard library provides a number of ways to execute a | |
59 | subprocess, offering different features and different levels of | |
60 | complexity. <tt class="function">os.system(<var>command</var>)</tt> is easy to use, but | |
61 | slow (it runs a shell process which executes the command) and | |
62 | dangerous (you have to be careful about escaping the shell's | |
63 | metacharacters). The <tt class="module">popen2</tt> module offers classes that can | |
64 | capture standard output and standard error from the subprocess, but | |
65 | the naming is confusing. The <tt class="module">subprocess</tt> module cleans | |
66 | this up, providing a unified interface that offers all the features | |
67 | you might need. | |
68 | ||
69 | <P> | |
70 | Instead of <tt class="module">popen2</tt>'s collection of classes, | |
71 | <tt class="module">subprocess</tt> contains a single class called <tt class="class">Popen</tt> | |
72 | whose constructor supports a number of different keyword arguments. | |
73 | ||
74 | <P> | |
75 | <div class="verbatim"><pre> | |
76 | class Popen(args, bufsize=0, executable=None, | |
77 | stdin=None, stdout=None, stderr=None, | |
78 | preexec_fn=None, close_fds=False, shell=False, | |
79 | cwd=None, env=None, universal_newlines=False, | |
80 | startupinfo=None, creationflags=0): | |
81 | </pre></div> | |
82 | ||
83 | <P> | |
84 | <var>args</var> is commonly a sequence of strings that will be the | |
85 | arguments to the program executed as the subprocess. (If the | |
86 | <var>shell</var> argument is true, <var>args</var> can be a string which will | |
87 | then be passed on to the shell for interpretation, just as | |
88 | <tt class="function">os.system()</tt> does.) | |
89 | ||
90 | <P> | |
91 | <var>stdin</var>, <var>stdout</var>, and <var>stderr</var> specify what the | |
92 | subprocess's input, output, and error streams will be. You can | |
93 | provide a file object or a file descriptor, or you can use the | |
94 | constant <code>subprocess.PIPE</code> to create a pipe between the | |
95 | subprocess and the parent. | |
96 | ||
97 | <P> | |
98 | The constructor has a number of handy options: | |
99 | ||
100 | <P> | |
101 | ||
102 | <UL> | |
103 | <LI><var>close_fds</var> requests that all file descriptors be closed | |
104 | before running the subprocess. | |
105 | ||
106 | <P> | |
107 | </LI> | |
108 | <LI><var>cwd</var> specifies the working directory in which the | |
109 | subprocess will be executed (defaulting to whatever the parent's | |
110 | working directory is). | |
111 | ||
112 | <P> | |
113 | </LI> | |
114 | <LI><var>env</var> is a dictionary specifying environment variables. | |
115 | ||
116 | <P> | |
117 | </LI> | |
118 | <LI><var>preexec_fn</var> is a function that gets called before the | |
119 | child is started. | |
120 | ||
121 | <P> | |
122 | </LI> | |
123 | <LI><var>universal_newlines</var> opens the child's input and output | |
124 | using Python's universal newline feature. | |
125 | ||
126 | <P> | |
127 | </LI> | |
128 | </UL> | |
129 | ||
130 | <P> | |
131 | Once you've created the <tt class="class">Popen</tt> instance, | |
132 | you can call its <tt class="method">wait()</tt> method to pause until the subprocess | |
133 | has exited, <tt class="method">poll()</tt> to check if it's exited without pausing, | |
134 | or <tt class="method">communicate(<var>data</var>)</tt> to send the string <var>data</var> to | |
135 | the subprocess's standard input. <tt class="method">communicate(<var>data</var>)</tt> | |
136 | then reads any data that the subprocess has sent to its standard output | |
137 | or standard error, returning a tuple <code>(<var>stdout_data</var>, | |
138 | <var>stderr_data</var>)</code>. | |
139 | ||
140 | <P> | |
141 | <tt class="function">call()</tt> is a shortcut that passes its arguments along to the | |
142 | <tt class="class">Popen</tt> constructor, waits for the command to complete, and | |
143 | returns the status code of the subprocess. It can serve as a safer | |
144 | analog to <tt class="function">os.system()</tt>: | |
145 | ||
146 | <P> | |
147 | <div class="verbatim"><pre> | |
148 | sts = subprocess.call(['dpkg', '-i', '/tmp/new-package.deb']) | |
149 | if sts == 0: | |
150 | # Success | |
151 | ... | |
152 | else: | |
153 | # dpkg returned an error | |
154 | ... | |
155 | </pre></div> | |
156 | ||
157 | <P> | |
158 | The command is invoked without use of the shell. If you really do want to | |
159 | use the shell, you can add <code>shell=True</code> as a keyword argument and provide | |
160 | a string instead of a sequence: | |
161 | ||
162 | <P> | |
163 | <div class="verbatim"><pre> | |
164 | sts = subprocess.call('dpkg -i /tmp/new-package.deb', shell=True) | |
165 | </pre></div> | |
166 | ||
167 | <P> | |
168 | The PEP takes various examples of shell and Python code and shows how | |
169 | they'd be translated into Python code that uses <tt class="module">subprocess</tt>. | |
170 | Reading this section of the PEP is highly recommended. | |
171 | ||
172 | <P> | |
173 | <div class="seealso"> | |
174 | <p class="heading">See Also:</p> | |
175 | ||
176 | <dl compact="compact" class="seerfc"> | |
177 | <dt><a href="http://www.python.org/peps/pep-0324.html" | |
178 | title="subprocess - New process module" | |
179 | >PEP 324, <em>subprocess - New process module</em></a> | |
180 | <dd>Written and implemented by Peter Åstrand, with assistance from Fredrik Lundh and others. | |
181 | </dl> | |
182 | </div> | |
183 | ||
184 | <P> | |
185 | ||
186 | <DIV CLASS="navigation"> | |
187 | <div class='online-navigation'> | |
188 | <p></p><hr /> | |
189 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> | |
190 | <tr> | |
191 | <td class='online-navigation'><a rel="prev" title="6 PEP 322: Reverse" | |
192 | href="node7.html"><img src='../icons/previous.png' | |
193 | border='0' height='32' alt='Previous Page' width='32' /></A></td> | |
194 | <td class='online-navigation'><a rel="parent" title="What's New in Python" | |
195 | href="whatsnew24.html"><img src='../icons/up.png' | |
196 | border='0' height='32' alt='Up One Level' width='32' /></A></td> | |
197 | <td class='online-navigation'><a rel="next" title="8 PEP 327: Decimal" | |
198 | href="node9.html"><img src='../icons/next.png' | |
199 | border='0' height='32' alt='Next Page' width='32' /></A></td> | |
200 | <td align="center" width="100%">What's New in Python 2.4</td> | |
201 | <td class='online-navigation'><a rel="contents" title="Table of Contents" | |
202 | href="contents.html"><img src='../icons/contents.png' | |
203 | border='0' height='32' alt='Contents' width='32' /></A></td> | |
204 | <td class='online-navigation'><img src='../icons/blank.png' | |
205 | border='0' height='32' alt='' width='32' /></td> | |
206 | <td class='online-navigation'><img src='../icons/blank.png' | |
207 | border='0' height='32' alt='' width='32' /></td> | |
208 | </tr></table> | |
209 | <div class='online-navigation'> | |
210 | <b class="navlabel">Previous:</b> | |
211 | <a class="sectref" rel="prev" href="node7.html">6 PEP 322: Reverse</A> | |
212 | <b class="navlabel">Up:</b> | |
213 | <a class="sectref" rel="parent" href="whatsnew24.html">What's New in Python</A> | |
214 | <b class="navlabel">Next:</b> | |
215 | <a class="sectref" rel="next" href="node9.html">8 PEP 327: Decimal</A> | |
216 | </div> | |
217 | </div> | |
218 | <hr /> | |
219 | <span class="release-info">Release 1.01.</span> | |
220 | </DIV> | |
221 | <!--End of Navigation Panel--> | |
222 | <ADDRESS> | |
223 | See <i><a href="about.html">About this document...</a></i> for information on suggesting changes. | |
224 | </ADDRESS> | |
225 | </BODY> | |
226 | </HTML> |