blob: 96720e41ef81b5ec1643cfd6fc9840ececdc0a77 [file] [log] [blame]
Georg Brandlbde4ad42006-01-20 21:36:02 +00001r"""OS routines for Mac, NT, or Posix depending on what system we're on.
Guido van Rossum31104f41992-01-14 18:28:36 +00002
Guido van Rossum54f22ed2000-02-04 15:10:34 +00003This exports:
Jesus Cea4791a242012-10-05 03:15:39 +02004 - all functions from posix, nt or ce, e.g. unlink, stat, etc.
Alexandre Vassalottieca20b62008-05-16 02:54:33 +00005 - os.path is either posixpath or ntpath
Jesus Cea4791a242012-10-05 03:15:39 +02006 - os.name is either 'posix', 'nt' or 'ce'.
Guido van Rossum54f22ed2000-02-04 15:10:34 +00007 - os.curdir is a string representing the current directory ('.' or ':')
8 - os.pardir is a string representing the parent directory ('..' or '::')
9 - os.sep is the (or a most common) pathname separator ('/' or ':' or '\\')
Georg Brandled5b9b32008-12-05 07:45:54 +000010 - os.extsep is the extension separator (always '.')
Guido van Rossum4b8c6ea2000-02-04 15:39:30 +000011 - os.altsep is the alternate pathname separator (None or '/')
Guido van Rossum54f22ed2000-02-04 15:10:34 +000012 - os.pathsep is the component separator used in $PATH etc
Guido van Rossum4b8c6ea2000-02-04 15:39:30 +000013 - os.linesep is the line separator in text files ('\r' or '\n' or '\r\n')
Guido van Rossum54f22ed2000-02-04 15:10:34 +000014 - os.defpath is the default search path for executables
Martin v. Löwisbdec50f2004-06-08 08:29:33 +000015 - os.devnull is the file path of the null device ('/dev/null', etc.)
Guido van Rossum31104f41992-01-14 18:28:36 +000016
Guido van Rossum54f22ed2000-02-04 15:10:34 +000017Programs that import and use 'os' stand a better chance of being
18portable between different platforms. Of course, they must then
19only use functions that are defined by all platforms (e.g., unlink
20and opendir), and leave all pathname manipulation to os.path
21(e.g., split and join).
22"""
Guido van Rossum31104f41992-01-14 18:28:36 +000023
Skip Montanaro269b83b2001-02-06 01:07:02 +000024#'
25
Christian Heimes45f9af32007-11-27 21:50:00 +000026import sys, errno
Charles-François Natali7372b062012-02-05 15:15:38 +010027import stat as st
Guido van Rossuma28dab51997-08-29 22:36:47 +000028
29_names = sys.builtin_module_names
30
Tim Petersc4e09402003-04-25 07:11:48 +000031# Note: more names are added to __all__ later.
Brett Cannon13962fc2008-08-18 01:45:29 +000032__all__ = ["altsep", "curdir", "pardir", "sep", "pathsep", "linesep",
Petri Lehtinen3bc37f22012-05-23 21:36:16 +030033 "defpath", "name", "path", "devnull", "SEEK_SET", "SEEK_CUR",
34 "SEEK_END", "fsencode", "fsdecode", "get_exec_path", "fdopen",
35 "popen", "extsep"]
Skip Montanaro269b83b2001-02-06 01:07:02 +000036
Charles-François Natali7372b062012-02-05 15:15:38 +010037def _exists(name):
38 return name in globals()
39
Skip Montanaro269b83b2001-02-06 01:07:02 +000040def _get_exports_list(module):
41 try:
42 return list(module.__all__)
43 except AttributeError:
44 return [n for n in dir(module) if n[0] != '_']
45
Brett Cannonfd074152012-04-14 14:10:13 -040046# Any new dependencies of the os module and/or changes in path separator
47# requires updating importlib as well.
Guido van Rossuma28dab51997-08-29 22:36:47 +000048if 'posix' in _names:
Guido van Rossum61de0ac1997-12-05 21:24:30 +000049 name = 'posix'
Guido van Rossume9387ea1998-05-22 15:26:04 +000050 linesep = '\n'
Guido van Rossum61de0ac1997-12-05 21:24:30 +000051 from posix import *
52 try:
53 from posix import _exit
Petri Lehtinen3bc37f22012-05-23 21:36:16 +030054 __all__.append('_exit')
Guido van Rossum61de0ac1997-12-05 21:24:30 +000055 except ImportError:
56 pass
Skip Montanaro117910d2003-02-14 19:35:31 +000057 import posixpath as path
Tim Petersf2715e02003-02-19 02:35:07 +000058
Larry Hastings9cf065c2012-06-22 16:30:09 -070059 try:
60 from posix import _have_functions
61 except ImportError:
62 pass
Skip Montanaro269b83b2001-02-06 01:07:02 +000063
Guido van Rossuma28dab51997-08-29 22:36:47 +000064elif 'nt' in _names:
Guido van Rossum61de0ac1997-12-05 21:24:30 +000065 name = 'nt'
Guido van Rossume9387ea1998-05-22 15:26:04 +000066 linesep = '\r\n'
Guido van Rossum61de0ac1997-12-05 21:24:30 +000067 from nt import *
Tim Peters6757c1e2003-01-08 21:20:57 +000068 try:
69 from nt import _exit
Petri Lehtinen3bc37f22012-05-23 21:36:16 +030070 __all__.append('_exit')
Tim Peters6757c1e2003-01-08 21:20:57 +000071 except ImportError:
72 pass
Skip Montanaro117910d2003-02-14 19:35:31 +000073 import ntpath as path
Tim Petersf2715e02003-02-19 02:35:07 +000074
Skip Montanaro269b83b2001-02-06 01:07:02 +000075 import nt
76 __all__.extend(_get_exports_list(nt))
77 del nt
78
Larry Hastings9cf065c2012-06-22 16:30:09 -070079 try:
80 from nt import _have_functions
81 except ImportError:
82 pass
83
Guido van Rossum18df5d41999-06-11 01:37:27 +000084elif 'ce' in _names:
85 name = 'ce'
86 linesep = '\r\n'
Guido van Rossum18df5d41999-06-11 01:37:27 +000087 from ce import *
Tim Peters6757c1e2003-01-08 21:20:57 +000088 try:
89 from ce import _exit
Petri Lehtinen3bc37f22012-05-23 21:36:16 +030090 __all__.append('_exit')
Tim Peters6757c1e2003-01-08 21:20:57 +000091 except ImportError:
92 pass
Guido van Rossum18df5d41999-06-11 01:37:27 +000093 # We can use the standard Windows path.
Skip Montanaro117910d2003-02-14 19:35:31 +000094 import ntpath as path
Tim Petersf2715e02003-02-19 02:35:07 +000095
Skip Montanaro269b83b2001-02-06 01:07:02 +000096 import ce
97 __all__.extend(_get_exports_list(ce))
98 del ce
99
Larry Hastings9cf065c2012-06-22 16:30:09 -0700100 try:
101 from ce import _have_functions
102 except ImportError:
103 pass
104
Guido van Rossum2979b011994-08-01 11:18:30 +0000105else:
Collin Winter828f04a2007-08-31 00:04:24 +0000106 raise ImportError('no os specific module found')
Guido van Rossume65cce51993-11-08 15:05:21 +0000107
Skip Montanaro117910d2003-02-14 19:35:31 +0000108sys.modules['os.path'] = path
Georg Brandled5b9b32008-12-05 07:45:54 +0000109from os.path import (curdir, pardir, sep, pathsep, defpath, extsep, altsep,
110 devnull)
Skip Montanaro269b83b2001-02-06 01:07:02 +0000111
Guido van Rossuma28dab51997-08-29 22:36:47 +0000112del _names
113
Larry Hastings9cf065c2012-06-22 16:30:09 -0700114
115if _exists("_have_functions"):
116 _globals = globals()
117 def _add(str, fn):
118 if (fn in _globals) and (str in _have_functions):
119 _set.add(_globals[fn])
120
121 _set = set()
122 _add("HAVE_FACCESSAT", "access")
123 _add("HAVE_FCHMODAT", "chmod")
124 _add("HAVE_FCHOWNAT", "chown")
125 _add("HAVE_FSTATAT", "stat")
126 _add("HAVE_FUTIMESAT", "utime")
127 _add("HAVE_LINKAT", "link")
128 _add("HAVE_MKDIRAT", "mkdir")
129 _add("HAVE_MKFIFOAT", "mkfifo")
130 _add("HAVE_MKNODAT", "mknod")
131 _add("HAVE_OPENAT", "open")
132 _add("HAVE_READLINKAT", "readlink")
133 _add("HAVE_RENAMEAT", "rename")
134 _add("HAVE_SYMLINKAT", "symlink")
135 _add("HAVE_UNLINKAT", "unlink")
Larry Hastingsb698d8e2012-06-23 16:55:07 -0700136 _add("HAVE_UNLINKAT", "rmdir")
Larry Hastings9cf065c2012-06-22 16:30:09 -0700137 _add("HAVE_UTIMENSAT", "utime")
138 supports_dir_fd = _set
139
140 _set = set()
141 _add("HAVE_FACCESSAT", "access")
142 supports_effective_ids = _set
143
144 _set = set()
145 _add("HAVE_FCHDIR", "chdir")
146 _add("HAVE_FCHMOD", "chmod")
147 _add("HAVE_FCHOWN", "chown")
148 _add("HAVE_FDOPENDIR", "listdir")
149 _add("HAVE_FEXECVE", "execve")
150 _set.add(stat) # fstat always works
Georg Brandl306336b2012-06-24 12:55:33 +0200151 _add("HAVE_FTRUNCATE", "truncate")
Larry Hastings9cf065c2012-06-22 16:30:09 -0700152 _add("HAVE_FUTIMENS", "utime")
153 _add("HAVE_FUTIMES", "utime")
Georg Brandl306336b2012-06-24 12:55:33 +0200154 _add("HAVE_FPATHCONF", "pathconf")
Larry Hastings9cf065c2012-06-22 16:30:09 -0700155 if _exists("statvfs") and _exists("fstatvfs"): # mac os x10.3
156 _add("HAVE_FSTATVFS", "statvfs")
157 supports_fd = _set
158
159 _set = set()
160 _add("HAVE_FACCESSAT", "access")
Larry Hastingsdbbc0c82012-06-22 19:50:21 -0700161 # Some platforms don't support lchmod(). Often the function exists
162 # anyway, as a stub that always returns ENOSUP or perhaps EOPNOTSUPP.
163 # (No, I don't know why that's a good design.) ./configure will detect
164 # this and reject it--so HAVE_LCHMOD still won't be defined on such
165 # platforms. This is Very Helpful.
166 #
167 # However, sometimes platforms without a working lchmod() *do* have
168 # fchmodat(). (Examples: Linux kernel 3.2 with glibc 2.15,
169 # OpenIndiana 3.x.) And fchmodat() has a flag that theoretically makes
170 # it behave like lchmod(). So in theory it would be a suitable
171 # replacement for lchmod(). But when lchmod() doesn't work, fchmodat()'s
172 # flag doesn't work *either*. Sadly ./configure isn't sophisticated
173 # enough to detect this condition--it only determines whether or not
174 # fchmodat() minimally works.
175 #
176 # Therefore we simply ignore fchmodat() when deciding whether or not
177 # os.chmod supports follow_symlinks. Just checking lchmod() is
178 # sufficient. After all--if you have a working fchmodat(), your
179 # lchmod() almost certainly works too.
180 #
181 # _add("HAVE_FCHMODAT", "chmod")
Larry Hastings9cf065c2012-06-22 16:30:09 -0700182 _add("HAVE_FCHOWNAT", "chown")
183 _add("HAVE_FSTATAT", "stat")
184 _add("HAVE_LCHFLAGS", "chflags")
185 _add("HAVE_LCHMOD", "chmod")
186 if _exists("lchown"): # mac os x10.3
187 _add("HAVE_LCHOWN", "chown")
188 _add("HAVE_LINKAT", "link")
189 _add("HAVE_LUTIMES", "utime")
190 _add("HAVE_LSTAT", "stat")
191 _add("HAVE_FSTATAT", "stat")
192 _add("HAVE_UTIMENSAT", "utime")
193 _add("MS_WINDOWS", "stat")
194 supports_follow_symlinks = _set
195
Larry Hastings9cf065c2012-06-22 16:30:09 -0700196 del _set
197 del _have_functions
198 del _globals
199 del _add
200
201
Martin v. Löwis22b457e2005-01-16 08:40:58 +0000202# Python uses fixed values for the SEEK_ constants; they are mapped
203# to native constants if necessary in posixmodule.c
Jesus Cea94363612012-06-22 18:32:07 +0200204# Other possible SEEK values are directly imported from posixmodule.c
Martin v. Löwis22b457e2005-01-16 08:40:58 +0000205SEEK_SET = 0
206SEEK_CUR = 1
207SEEK_END = 2
208
Terry Reedy5a22b652010-12-02 07:05:56 +0000209
210def _get_masked_mode(mode):
211 mask = umask(0)
212 umask(mask)
213 return mode & ~mask
214
Guido van Rossum4def7de1998-07-24 20:48:03 +0000215# Super directory utilities.
216# (Inspired by Eric Raymond; the doc strings are mostly his)
217
Terry Reedy5a22b652010-12-02 07:05:56 +0000218def makedirs(name, mode=0o777, exist_ok=False):
219 """makedirs(path [, mode=0o777][, exist_ok=False])
Guido van Rossum4def7de1998-07-24 20:48:03 +0000220
221 Super-mkdir; create a leaf directory and all intermediate ones.
222 Works like mkdir, except that any intermediate path segment (not
Terry Reedy5a22b652010-12-02 07:05:56 +0000223 just the rightmost) will be created if it does not exist. If the
224 target directory with the same mode as we specified already exists,
225 raises an OSError if exist_ok is False, otherwise no exception is
226 raised. This is recursive.
Guido van Rossum4def7de1998-07-24 20:48:03 +0000227
228 """
229 head, tail = path.split(name)
Fred Drake9f2550f2000-07-25 15:16:40 +0000230 if not tail:
231 head, tail = path.split(head)
Guido van Rossum4def7de1998-07-24 20:48:03 +0000232 if head and tail and not path.exists(head):
Thomas Wouters89f507f2006-12-13 04:49:30 +0000233 try:
Terry Reedy5a22b652010-12-02 07:05:56 +0000234 makedirs(head, mode, exist_ok)
Giampaolo Rodola'0166a282013-02-12 15:14:17 +0100235 except FileExistsError:
Thomas Wouters89f507f2006-12-13 04:49:30 +0000236 # be happy if someone already created the path
Giampaolo Rodola'0166a282013-02-12 15:14:17 +0100237 pass
Serhiy Storchaka4ab23bf2013-01-08 11:32:58 +0200238 cdir = curdir
239 if isinstance(tail, bytes):
240 cdir = bytes(curdir, 'ASCII')
241 if tail == cdir: # xxx/newdir/. exists if xxx/newdir exists
Andrew M. Kuchling6fccc8a2003-12-23 16:33:28 +0000242 return
Terry Reedy5a22b652010-12-02 07:05:56 +0000243 try:
244 mkdir(name, mode)
245 except OSError as e:
Gregory P. Smitha81c8562012-06-03 14:30:44 -0700246 dir_exists = path.isdir(name)
247 expected_mode = _get_masked_mode(mode)
248 if dir_exists:
249 # S_ISGID is automatically copied by the OS from parent to child
250 # directories on mkdir. Don't consider it being set to be a mode
251 # mismatch as mkdir does not unset it when not specified in mode.
252 actual_mode = st.S_IMODE(lstat(name).st_mode) & ~st.S_ISGID
253 else:
254 actual_mode = -1
255 if not (e.errno == errno.EEXIST and exist_ok and dir_exists and
256 actual_mode == expected_mode):
257 if dir_exists and actual_mode != expected_mode:
258 e.strerror += ' (mode %o != expected mode %o)' % (
259 actual_mode, expected_mode)
Terry Reedy5a22b652010-12-02 07:05:56 +0000260 raise
Guido van Rossum4def7de1998-07-24 20:48:03 +0000261
262def removedirs(name):
Fred Drakecadb9eb2002-07-02 21:28:04 +0000263 """removedirs(path)
Guido van Rossum4def7de1998-07-24 20:48:03 +0000264
Fredrik Lundh96c1c7a2005-11-12 15:55:04 +0000265 Super-rmdir; remove a leaf directory and all empty intermediate
Guido van Rossum4def7de1998-07-24 20:48:03 +0000266 ones. Works like rmdir except that, if the leaf directory is
267 successfully removed, directories corresponding to rightmost path
Tim Petersc4e09402003-04-25 07:11:48 +0000268 segments will be pruned away until either the whole path is
Guido van Rossum4def7de1998-07-24 20:48:03 +0000269 consumed or an error occurs. Errors during this latter phase are
270 ignored -- they generally mean that a directory was not empty.
271
272 """
273 rmdir(name)
274 head, tail = path.split(name)
Fred Drake9f2550f2000-07-25 15:16:40 +0000275 if not tail:
276 head, tail = path.split(head)
Guido van Rossum4def7de1998-07-24 20:48:03 +0000277 while head and tail:
278 try:
279 rmdir(head)
Andrew Svetlov2552bc02012-12-24 21:47:24 +0200280 except OSError:
Guido van Rossum4def7de1998-07-24 20:48:03 +0000281 break
282 head, tail = path.split(head)
283
284def renames(old, new):
Fred Drakecadb9eb2002-07-02 21:28:04 +0000285 """renames(old, new)
Guido van Rossum4def7de1998-07-24 20:48:03 +0000286
287 Super-rename; create directories as necessary and delete any left
288 empty. Works like rename, except creation of any intermediate
289 directories needed to make the new pathname good is attempted
290 first. After the rename, directories corresponding to rightmost
291 path segments of the old name will be pruned way until either the
292 whole path is consumed or a nonempty directory is found.
293
294 Note: this function can fail with the new directory structure made
295 if you lack permissions needed to unlink the leaf directory or
296 file.
297
298 """
299 head, tail = path.split(new)
300 if head and tail and not path.exists(head):
301 makedirs(head)
302 rename(old, new)
303 head, tail = path.split(old)
304 if head and tail:
305 try:
306 removedirs(head)
Andrew Svetlov8b33dd82012-12-24 19:58:48 +0200307 except OSError:
Guido van Rossum4def7de1998-07-24 20:48:03 +0000308 pass
309
Skip Montanaro269b83b2001-02-06 01:07:02 +0000310__all__.extend(["makedirs", "removedirs", "renames"])
311
Guido van Rossumd8faa362007-04-27 19:54:29 +0000312def walk(top, topdown=True, onerror=None, followlinks=False):
Tim Petersc4e09402003-04-25 07:11:48 +0000313 """Directory tree generator.
314
315 For each directory in the directory tree rooted at top (including top
316 itself, but excluding '.' and '..'), yields a 3-tuple
317
318 dirpath, dirnames, filenames
319
320 dirpath is a string, the path to the directory. dirnames is a list of
321 the names of the subdirectories in dirpath (excluding '.' and '..').
322 filenames is a list of the names of the non-directory files in dirpath.
323 Note that the names in the lists are just names, with no path components.
324 To get a full path (which begins with top) to a file or directory in
325 dirpath, do os.path.join(dirpath, name).
326
327 If optional arg 'topdown' is true or not specified, the triple for a
328 directory is generated before the triples for any of its subdirectories
329 (directories are generated top down). If topdown is false, the triple
330 for a directory is generated after the triples for all of its
331 subdirectories (directories are generated bottom up).
332
333 When topdown is true, the caller can modify the dirnames list in-place
334 (e.g., via del or slice assignment), and walk will only recurse into the
335 subdirectories whose names remain in dirnames; this can be used to prune
336 the search, or to impose a specific order of visiting. Modifying
337 dirnames when topdown is false is ineffective, since the directories in
338 dirnames have already been generated by the time dirnames itself is
339 generated.
340
Guido van Rossumbf1bef82003-05-13 18:01:19 +0000341 By default errors from the os.listdir() call are ignored. If
342 optional arg 'onerror' is specified, it should be a function; it
Andrew Svetlovad28c7f2012-12-18 22:02:39 +0200343 will be called with one argument, an OSError instance. It can
Guido van Rossumbf1bef82003-05-13 18:01:19 +0000344 report the error to continue with the walk, or raise the exception
345 to abort the walk. Note that the filename is available as the
346 filename attribute of the exception object.
347
Guido van Rossumd8faa362007-04-27 19:54:29 +0000348 By default, os.walk does not follow symbolic links to subdirectories on
349 systems that support them. In order to get this functionality, set the
350 optional argument 'followlinks' to true.
351
Tim Petersc4e09402003-04-25 07:11:48 +0000352 Caution: if you pass a relative pathname for top, don't change the
353 current working directory between resumptions of walk. walk never
354 changes the current directory, and assumes that the client doesn't
355 either.
356
357 Example:
358
Christian Heimes5d8da202008-05-06 13:58:24 +0000359 import os
Tim Petersc4e09402003-04-25 07:11:48 +0000360 from os.path import join, getsize
Christian Heimes5d8da202008-05-06 13:58:24 +0000361 for root, dirs, files in os.walk('python/Lib/email'):
Neal Norwitz752abd02008-05-13 04:55:24 +0000362 print(root, "consumes", end="")
363 print(sum([getsize(join(root, name)) for name in files]), end="")
364 print("bytes in", len(files), "non-directory files")
Tim Petersc4e09402003-04-25 07:11:48 +0000365 if 'CVS' in dirs:
366 dirs.remove('CVS') # don't visit CVS directories
367 """
368
Benjamin Petersonf6489f92009-11-25 17:46:26 +0000369 islink, join, isdir = path.islink, path.join, path.isdir
Tim Petersc4e09402003-04-25 07:11:48 +0000370
371 # We may not have read permission for top, in which case we can't
Alexandre Vassalotti4e6531e2008-05-09 20:00:17 +0000372 # get a list of the files the directory contains. os.walk
Tim Petersc4e09402003-04-25 07:11:48 +0000373 # always suppressed the exception then, rather than blow up for a
374 # minor reason when (say) a thousand readable directories are still
375 # left to visit. That logic is copied here.
376 try:
Andrew Svetlov8b33dd82012-12-24 19:58:48 +0200377 # Note that listdir is global in this module due
Tim Petersc4e09402003-04-25 07:11:48 +0000378 # to earlier import-*.
379 names = listdir(top)
Andrew Svetlov8b33dd82012-12-24 19:58:48 +0200380 except OSError as err:
Guido van Rossumbf1bef82003-05-13 18:01:19 +0000381 if onerror is not None:
382 onerror(err)
Tim Petersc4e09402003-04-25 07:11:48 +0000383 return
384
385 dirs, nondirs = [], []
386 for name in names:
387 if isdir(join(top, name)):
388 dirs.append(name)
389 else:
390 nondirs.append(name)
391
392 if topdown:
393 yield top, dirs, nondirs
394 for name in dirs:
Benjamin Petersonf6489f92009-11-25 17:46:26 +0000395 new_path = join(top, name)
396 if followlinks or not islink(new_path):
Benjamin Peterson569d0872012-05-10 16:17:35 -0500397 yield from walk(new_path, topdown, onerror, followlinks)
Tim Petersc4e09402003-04-25 07:11:48 +0000398 if not topdown:
399 yield top, dirs, nondirs
400
401__all__.append("walk")
402
Larry Hastingsc48fe982012-06-25 04:49:05 -0700403if {open, stat} <= supports_dir_fd and {listdir, stat} <= supports_fd:
Charles-François Natali7372b062012-02-05 15:15:38 +0100404
Larry Hastingsb4038062012-07-15 10:57:38 -0700405 def fwalk(top=".", topdown=True, onerror=None, *, follow_symlinks=False, dir_fd=None):
Charles-François Natali7372b062012-02-05 15:15:38 +0100406 """Directory tree generator.
407
408 This behaves exactly like walk(), except that it yields a 4-tuple
409
410 dirpath, dirnames, filenames, dirfd
411
412 `dirpath`, `dirnames` and `filenames` are identical to walk() output,
413 and `dirfd` is a file descriptor referring to the directory `dirpath`.
414
Larry Hastingsc48fe982012-06-25 04:49:05 -0700415 The advantage of fwalk() over walk() is that it's safe against symlink
Larry Hastingsb4038062012-07-15 10:57:38 -0700416 races (when follow_symlinks is False).
Charles-François Natali7372b062012-02-05 15:15:38 +0100417
Larry Hastingsc48fe982012-06-25 04:49:05 -0700418 If dir_fd is not None, it should be a file descriptor open to a directory,
419 and top should be relative; top will then be relative to that directory.
420 (dir_fd is always supported for fwalk.)
421
Charles-François Natali7372b062012-02-05 15:15:38 +0100422 Caution:
423 Since fwalk() yields file descriptors, those are only valid until the
424 next iteration step, so you should dup() them if you want to keep them
425 for a longer period.
426
427 Example:
428
429 import os
430 for root, dirs, files, rootfd in os.fwalk('python/Lib/email'):
431 print(root, "consumes", end="")
Larry Hastings9cf065c2012-06-22 16:30:09 -0700432 print(sum([os.stat(name, dir_fd=rootfd).st_size for name in files]),
Charles-François Natali7372b062012-02-05 15:15:38 +0100433 end="")
434 print("bytes in", len(files), "non-directory files")
435 if 'CVS' in dirs:
436 dirs.remove('CVS') # don't visit CVS directories
437 """
438 # Note: To guard against symlink races, we use the standard
439 # lstat()/open()/fstat() trick.
Larry Hastingsc48fe982012-06-25 04:49:05 -0700440 orig_st = stat(top, follow_symlinks=False, dir_fd=dir_fd)
441 topfd = open(top, O_RDONLY, dir_fd=dir_fd)
Charles-François Natali7372b062012-02-05 15:15:38 +0100442 try:
Larry Hastingsb4038062012-07-15 10:57:38 -0700443 if (follow_symlinks or (st.S_ISDIR(orig_st.st_mode) and
444 path.samestat(orig_st, stat(topfd)))):
445 yield from _fwalk(topfd, top, topdown, onerror, follow_symlinks)
Charles-François Natali7372b062012-02-05 15:15:38 +0100446 finally:
447 close(topfd)
448
Larry Hastingsb4038062012-07-15 10:57:38 -0700449 def _fwalk(topfd, toppath, topdown, onerror, follow_symlinks):
Charles-François Natali7372b062012-02-05 15:15:38 +0100450 # Note: This uses O(depth of the directory tree) file descriptors: if
451 # necessary, it can be adapted to only require O(1) FDs, see issue
452 # #13734.
453
Larry Hastings9cf065c2012-06-22 16:30:09 -0700454 names = listdir(topfd)
Charles-François Natali7372b062012-02-05 15:15:38 +0100455 dirs, nondirs = [], []
456 for name in names:
Hynek Schlawack66bfcc12012-05-15 16:32:21 +0200457 try:
458 # Here, we don't use AT_SYMLINK_NOFOLLOW to be consistent with
459 # walk() which reports symlinks to directories as directories.
460 # We do however check for symlinks before recursing into
461 # a subdirectory.
Larry Hastings9cf065c2012-06-22 16:30:09 -0700462 if st.S_ISDIR(stat(name, dir_fd=topfd).st_mode):
Hynek Schlawack66bfcc12012-05-15 16:32:21 +0200463 dirs.append(name)
464 else:
465 nondirs.append(name)
466 except FileNotFoundError:
467 try:
468 # Add dangling symlinks, ignore disappeared files
Larry Hastings9cf065c2012-06-22 16:30:09 -0700469 if st.S_ISLNK(stat(name, dir_fd=topfd, follow_symlinks=False)
Hynek Schlawack66bfcc12012-05-15 16:32:21 +0200470 .st_mode):
471 nondirs.append(name)
472 except FileNotFoundError:
473 continue
Charles-François Natali7372b062012-02-05 15:15:38 +0100474
475 if topdown:
476 yield toppath, dirs, nondirs, topfd
477
478 for name in dirs:
479 try:
Larry Hastingsb4038062012-07-15 10:57:38 -0700480 orig_st = stat(name, dir_fd=topfd, follow_symlinks=follow_symlinks)
Larry Hastings9cf065c2012-06-22 16:30:09 -0700481 dirfd = open(name, O_RDONLY, dir_fd=topfd)
Andrew Svetlov8b33dd82012-12-24 19:58:48 +0200482 except OSError as err:
Charles-François Natali7372b062012-02-05 15:15:38 +0100483 if onerror is not None:
484 onerror(err)
485 return
486 try:
Larry Hastingsb4038062012-07-15 10:57:38 -0700487 if follow_symlinks or path.samestat(orig_st, stat(dirfd)):
Charles-François Natali7372b062012-02-05 15:15:38 +0100488 dirpath = path.join(toppath, name)
Larry Hastingsb4038062012-07-15 10:57:38 -0700489 yield from _fwalk(dirfd, dirpath, topdown, onerror, follow_symlinks)
Charles-François Natali7372b062012-02-05 15:15:38 +0100490 finally:
491 close(dirfd)
492
493 if not topdown:
494 yield toppath, dirs, nondirs, topfd
495
496 __all__.append("fwalk")
497
Guido van Rossuma28dab51997-08-29 22:36:47 +0000498# Make sure os.environ exists, at least
499try:
Guido van Rossum61de0ac1997-12-05 21:24:30 +0000500 environ
Guido van Rossuma28dab51997-08-29 22:36:47 +0000501except NameError:
Guido van Rossum61de0ac1997-12-05 21:24:30 +0000502 environ = {}
Guido van Rossuma28dab51997-08-29 22:36:47 +0000503
Guido van Rossume65cce51993-11-08 15:05:21 +0000504def execl(file, *args):
Guido van Rossum7da3cc52000-04-25 10:53:22 +0000505 """execl(file, *args)
506
507 Execute the executable file with argument list args, replacing the
508 current process. """
Guido van Rossum61de0ac1997-12-05 21:24:30 +0000509 execv(file, args)
Guido van Rossume65cce51993-11-08 15:05:21 +0000510
511def execle(file, *args):
Guido van Rossum7da3cc52000-04-25 10:53:22 +0000512 """execle(file, *args, env)
513
514 Execute the executable file with argument list args and
515 environment env, replacing the current process. """
Guido van Rossum61de0ac1997-12-05 21:24:30 +0000516 env = args[-1]
517 execve(file, args[:-1], env)
Guido van Rossume65cce51993-11-08 15:05:21 +0000518
519def execlp(file, *args):
Guido van Rossum7da3cc52000-04-25 10:53:22 +0000520 """execlp(file, *args)
521
522 Execute the executable file (which is searched for along $PATH)
523 with argument list args, replacing the current process. """
Guido van Rossum61de0ac1997-12-05 21:24:30 +0000524 execvp(file, args)
Guido van Rossume65cce51993-11-08 15:05:21 +0000525
Guido van Rossum030afb11995-03-14 17:27:18 +0000526def execlpe(file, *args):
Guido van Rossum7da3cc52000-04-25 10:53:22 +0000527 """execlpe(file, *args, env)
528
529 Execute the executable file (which is searched for along $PATH)
530 with argument list args and environment env, replacing the current
Tim Peters2344fae2001-01-15 00:50:52 +0000531 process. """
Guido van Rossum61de0ac1997-12-05 21:24:30 +0000532 env = args[-1]
533 execvpe(file, args[:-1], env)
Guido van Rossum030afb11995-03-14 17:27:18 +0000534
Guido van Rossume65cce51993-11-08 15:05:21 +0000535def execvp(file, args):
Matthias Klosea09c54f2010-01-31 16:48:44 +0000536 """execvp(file, args)
Guido van Rossum7da3cc52000-04-25 10:53:22 +0000537
538 Execute the executable file (which is searched for along $PATH)
539 with argument list args, replacing the current process.
Thomas Wouters7e474022000-07-16 12:04:32 +0000540 args may be a list or tuple of strings. """
Guido van Rossum61de0ac1997-12-05 21:24:30 +0000541 _execvpe(file, args)
Guido van Rossum030afb11995-03-14 17:27:18 +0000542
543def execvpe(file, args, env):
Guido van Rossum683c0fe2002-09-03 16:36:17 +0000544 """execvpe(file, args, env)
Guido van Rossum7da3cc52000-04-25 10:53:22 +0000545
546 Execute the executable file (which is searched for along $PATH)
547 with argument list args and environment env , replacing the
548 current process.
Tim Peters2344fae2001-01-15 00:50:52 +0000549 args may be a list or tuple of strings. """
Guido van Rossum61de0ac1997-12-05 21:24:30 +0000550 _execvpe(file, args, env)
Guido van Rossum030afb11995-03-14 17:27:18 +0000551
Skip Montanaro269b83b2001-02-06 01:07:02 +0000552__all__.extend(["execl","execle","execlp","execlpe","execvp","execvpe"])
553
Guido van Rossum5a2ca931999-11-02 13:27:32 +0000554def _execvpe(file, args, env=None):
555 if env is not None:
Gregory P. Smithb6e8c7e2010-02-27 07:22:22 +0000556 exec_func = execve
Guido van Rossum61de0ac1997-12-05 21:24:30 +0000557 argrest = (args, env)
558 else:
Gregory P. Smithb6e8c7e2010-02-27 07:22:22 +0000559 exec_func = execv
Guido van Rossum61de0ac1997-12-05 21:24:30 +0000560 argrest = (args,)
561 env = environ
Guido van Rossumaed51d82002-08-05 16:13:24 +0000562
Guido van Rossum61de0ac1997-12-05 21:24:30 +0000563 head, tail = path.split(file)
564 if head:
Gregory P. Smithb6e8c7e2010-02-27 07:22:22 +0000565 exec_func(file, *argrest)
Guido van Rossum61de0ac1997-12-05 21:24:30 +0000566 return
Guido van Rossume7ba4952007-06-06 23:52:48 +0000567 last_exc = saved_exc = None
Guido van Rossum683c0fe2002-09-03 16:36:17 +0000568 saved_tb = None
Victor Stinnerb745a742010-05-18 17:17:23 +0000569 path_list = get_exec_path(env)
570 if name != 'nt':
571 file = fsencode(file)
572 path_list = map(fsencode, path_list)
573 for dir in path_list:
Guido van Rossum61de0ac1997-12-05 21:24:30 +0000574 fullname = path.join(dir, file)
575 try:
Gregory P. Smithb6e8c7e2010-02-27 07:22:22 +0000576 exec_func(fullname, *argrest)
Andrew Svetlov8b33dd82012-12-24 19:58:48 +0200577 except OSError as e:
Guido van Rossume7ba4952007-06-06 23:52:48 +0000578 last_exc = e
Guido van Rossum683c0fe2002-09-03 16:36:17 +0000579 tb = sys.exc_info()[2]
Christian Heimes45f9af32007-11-27 21:50:00 +0000580 if (e.errno != errno.ENOENT and e.errno != errno.ENOTDIR
Guido van Rossum683c0fe2002-09-03 16:36:17 +0000581 and saved_exc is None):
582 saved_exc = e
583 saved_tb = tb
584 if saved_exc:
Benjamin Peterson4b068192009-02-20 03:19:25 +0000585 raise saved_exc.with_traceback(saved_tb)
586 raise last_exc.with_traceback(tb)
Guido van Rossumd74fb6b2001-03-02 06:43:49 +0000587
Guido van Rossumcd16bf62007-06-13 18:07:49 +0000588
Gregory P. Smithb6e8c7e2010-02-27 07:22:22 +0000589def get_exec_path(env=None):
590 """Returns the sequence of directories that will be searched for the
591 named executable (similar to a shell) when launching a process.
592
593 *env* must be an environment variable dict or None. If *env* is None,
594 os.environ will be used.
595 """
Victor Stinner273b7662010-11-06 12:59:33 +0000596 # Use a local import instead of a global import to limit the number of
597 # modules loaded at startup: the os module is always loaded at startup by
598 # Python. It may also avoid a bootstrap issue.
Victor Stinner6f35eda2010-10-29 00:38:58 +0000599 import warnings
600
Gregory P. Smithb6e8c7e2010-02-27 07:22:22 +0000601 if env is None:
602 env = environ
Victor Stinnerb745a742010-05-18 17:17:23 +0000603
Victor Stinnerbb4f2182010-11-07 15:43:39 +0000604 # {b'PATH': ...}.get('PATH') and {'PATH': ...}.get(b'PATH') emit a
605 # BytesWarning when using python -b or python -bb: ignore the warning
Victor Stinner273b7662010-11-06 12:59:33 +0000606 with warnings.catch_warnings():
607 warnings.simplefilter("ignore", BytesWarning)
Victor Stinnerb745a742010-05-18 17:17:23 +0000608
Victor Stinnerb745a742010-05-18 17:17:23 +0000609 try:
Victor Stinner273b7662010-11-06 12:59:33 +0000610 path_list = env.get('PATH')
611 except TypeError:
612 path_list = None
Victor Stinnerb745a742010-05-18 17:17:23 +0000613
Victor Stinner273b7662010-11-06 12:59:33 +0000614 if supports_bytes_environ:
615 try:
616 path_listb = env[b'PATH']
617 except (KeyError, TypeError):
618 pass
619 else:
620 if path_list is not None:
621 raise ValueError(
622 "env cannot contain 'PATH' and b'PATH' keys")
623 path_list = path_listb
624
625 if path_list is not None and isinstance(path_list, bytes):
626 path_list = fsdecode(path_list)
Victor Stinnerb745a742010-05-18 17:17:23 +0000627
628 if path_list is None:
629 path_list = defpath
630 return path_list.split(pathsep)
Gregory P. Smithb6e8c7e2010-02-27 07:22:22 +0000631
632
Skip Montanaro289bc052007-08-17 02:30:27 +0000633# Change environ to automatically call putenv(), unsetenv if they exist.
Raymond Hettinger158c9c22011-02-22 00:41:50 +0000634from collections.abc import MutableMapping
Skip Montanaro289bc052007-08-17 02:30:27 +0000635
636class _Environ(MutableMapping):
Victor Stinner84ae1182010-05-06 22:05:07 +0000637 def __init__(self, data, encodekey, decodekey, encodevalue, decodevalue, putenv, unsetenv):
638 self.encodekey = encodekey
639 self.decodekey = decodekey
640 self.encodevalue = encodevalue
641 self.decodevalue = decodevalue
Skip Montanaro289bc052007-08-17 02:30:27 +0000642 self.putenv = putenv
643 self.unsetenv = unsetenv
Victor Stinner3d75d0c2010-09-10 22:18:16 +0000644 self._data = data
Ezio Melotti19e4acf2010-02-22 15:59:01 +0000645
Skip Montanaro289bc052007-08-17 02:30:27 +0000646 def __getitem__(self, key):
Victor Stinner6d101392013-04-14 16:35:04 +0200647 try:
648 value = self._data[self.encodekey(key)]
649 except KeyError:
650 # raise KeyError with the original key value
651 raise KeyError(key)
Victor Stinner84ae1182010-05-06 22:05:07 +0000652 return self.decodevalue(value)
Ezio Melotti19e4acf2010-02-22 15:59:01 +0000653
Skip Montanaro289bc052007-08-17 02:30:27 +0000654 def __setitem__(self, key, value):
Victor Stinner84ae1182010-05-06 22:05:07 +0000655 key = self.encodekey(key)
656 value = self.encodevalue(value)
Skip Montanaro289bc052007-08-17 02:30:27 +0000657 self.putenv(key, value)
Victor Stinner3d75d0c2010-09-10 22:18:16 +0000658 self._data[key] = value
Ezio Melotti19e4acf2010-02-22 15:59:01 +0000659
Skip Montanaro289bc052007-08-17 02:30:27 +0000660 def __delitem__(self, key):
Victor Stinner6d101392013-04-14 16:35:04 +0200661 encodedkey = self.encodekey(key)
662 self.unsetenv(encodedkey)
663 try:
664 del self._data[encodedkey]
665 except KeyError:
666 # raise KeyError with the original key value
667 raise KeyError(key)
Ezio Melotti19e4acf2010-02-22 15:59:01 +0000668
Skip Montanaro289bc052007-08-17 02:30:27 +0000669 def __iter__(self):
Victor Stinner3d75d0c2010-09-10 22:18:16 +0000670 for key in self._data:
Victor Stinner84ae1182010-05-06 22:05:07 +0000671 yield self.decodekey(key)
Ezio Melotti19e4acf2010-02-22 15:59:01 +0000672
Skip Montanaro289bc052007-08-17 02:30:27 +0000673 def __len__(self):
Victor Stinner3d75d0c2010-09-10 22:18:16 +0000674 return len(self._data)
Ezio Melotti19e4acf2010-02-22 15:59:01 +0000675
676 def __repr__(self):
Victor Stinnerbed71172010-07-28 21:25:42 +0000677 return 'environ({{{}}})'.format(', '.join(
Victor Stinnerd73c1a32010-07-28 21:23:23 +0000678 ('{!r}: {!r}'.format(self.decodekey(key), self.decodevalue(value))
Victor Stinner3d75d0c2010-09-10 22:18:16 +0000679 for key, value in self._data.items())))
Ezio Melotti19e4acf2010-02-22 15:59:01 +0000680
Skip Montanaro289bc052007-08-17 02:30:27 +0000681 def copy(self):
682 return dict(self)
Ezio Melotti19e4acf2010-02-22 15:59:01 +0000683
Skip Montanaro289bc052007-08-17 02:30:27 +0000684 def setdefault(self, key, value):
685 if key not in self:
686 self[key] = value
687 return self[key]
688
689try:
690 _putenv = putenv
691except NameError:
692 _putenv = lambda key, value: None
Richard Oudkerkc41917f2013-05-07 14:36:51 +0100693else:
694 if "putenv" not in __all__:
695 __all__.append("putenv")
Guido van Rossum3b8e20d1996-07-24 00:55:17 +0000696
Skip Montanaro289bc052007-08-17 02:30:27 +0000697try:
698 _unsetenv = unsetenv
699except NameError:
700 _unsetenv = lambda key: _putenv(key, "")
Richard Oudkerkc41917f2013-05-07 14:36:51 +0100701else:
702 if "unsetenv" not in __all__:
703 __all__.append("unsetenv")
Guido van Rossumc524d952001-10-19 01:31:59 +0000704
Victor Stinner84ae1182010-05-06 22:05:07 +0000705def _createenviron():
Jesus Cea4791a242012-10-05 03:15:39 +0200706 if name == 'nt':
Victor Stinner84ae1182010-05-06 22:05:07 +0000707 # Where Env Var Names Must Be UPPERCASE
708 def check_str(value):
709 if not isinstance(value, str):
710 raise TypeError("str expected, not %s" % type(value).__name__)
711 return value
712 encode = check_str
713 decode = str
714 def encodekey(key):
715 return encode(key).upper()
716 data = {}
717 for key, value in environ.items():
718 data[encodekey(key)] = value
719 else:
720 # Where Env Var Names Can Be Mixed Case
Victor Stinnerdf6d6cb2010-10-24 20:32:26 +0000721 encoding = sys.getfilesystemencoding()
Victor Stinner84ae1182010-05-06 22:05:07 +0000722 def encode(value):
723 if not isinstance(value, str):
724 raise TypeError("str expected, not %s" % type(value).__name__)
Victor Stinnerdf6d6cb2010-10-24 20:32:26 +0000725 return value.encode(encoding, 'surrogateescape')
Victor Stinner84ae1182010-05-06 22:05:07 +0000726 def decode(value):
Victor Stinnerdf6d6cb2010-10-24 20:32:26 +0000727 return value.decode(encoding, 'surrogateescape')
Victor Stinner84ae1182010-05-06 22:05:07 +0000728 encodekey = encode
729 data = environ
730 return _Environ(data,
731 encodekey, decode,
732 encode, decode,
733 _putenv, _unsetenv)
Guido van Rossumc524d952001-10-19 01:31:59 +0000734
Victor Stinner84ae1182010-05-06 22:05:07 +0000735# unicode environ
736environ = _createenviron()
737del _createenviron
Guido van Rossum61de0ac1997-12-05 21:24:30 +0000738
Guido van Rossum5a2ca931999-11-02 13:27:32 +0000739
Jack Jansenb11ce9b2003-01-08 16:33:40 +0000740def getenv(key, default=None):
Tim Peters2c60f7a2003-01-29 03:49:43 +0000741 """Get an environment variable, return None if it doesn't exist.
Victor Stinner84ae1182010-05-06 22:05:07 +0000742 The optional second argument can specify an alternate default.
743 key, default and the result are str."""
Tim Peters2c60f7a2003-01-29 03:49:43 +0000744 return environ.get(key, default)
Guido van Rossum5a2ca931999-11-02 13:27:32 +0000745
Jesus Cea4791a242012-10-05 03:15:39 +0200746supports_bytes_environ = (name != 'nt')
Victor Stinnerb745a742010-05-18 17:17:23 +0000747__all__.extend(("getenv", "supports_bytes_environ"))
748
749if supports_bytes_environ:
Victor Stinner84ae1182010-05-06 22:05:07 +0000750 def _check_bytes(value):
751 if not isinstance(value, bytes):
752 raise TypeError("bytes expected, not %s" % type(value).__name__)
753 return value
754
755 # bytes environ
Victor Stinner3d75d0c2010-09-10 22:18:16 +0000756 environb = _Environ(environ._data,
Victor Stinner84ae1182010-05-06 22:05:07 +0000757 _check_bytes, bytes,
758 _check_bytes, bytes,
759 _putenv, _unsetenv)
760 del _check_bytes
761
762 def getenvb(key, default=None):
763 """Get an environment variable, return None if it doesn't exist.
764 The optional second argument can specify an alternate default.
765 key, default and the result are bytes."""
766 return environb.get(key, default)
Victor Stinner70120e22010-07-29 17:19:38 +0000767
768 __all__.extend(("environb", "getenvb"))
Victor Stinner84ae1182010-05-06 22:05:07 +0000769
Victor Stinnerdf6d6cb2010-10-24 20:32:26 +0000770def _fscodec():
771 encoding = sys.getfilesystemencoding()
772 if encoding == 'mbcs':
Victor Stinnere882aac2010-10-24 21:12:26 +0000773 errors = 'strict'
Victor Stinner313a1202010-06-11 23:56:51 +0000774 else:
Victor Stinnerdf6d6cb2010-10-24 20:32:26 +0000775 errors = 'surrogateescape'
Victor Stinnere8d51452010-08-19 01:05:19 +0000776
Victor Stinnerdf6d6cb2010-10-24 20:32:26 +0000777 def fsencode(filename):
778 """
779 Encode filename to the filesystem encoding with 'surrogateescape' error
780 handler, return bytes unchanged. On Windows, use 'strict' error handler if
781 the file system encoding is 'mbcs' (which is the default encoding).
782 """
783 if isinstance(filename, bytes):
784 return filename
785 elif isinstance(filename, str):
786 return filename.encode(encoding, errors)
Victor Stinnere8d51452010-08-19 01:05:19 +0000787 else:
Victor Stinnerdf6d6cb2010-10-24 20:32:26 +0000788 raise TypeError("expect bytes or str, not %s" % type(filename).__name__)
789
790 def fsdecode(filename):
791 """
792 Decode filename from the filesystem encoding with 'surrogateescape' error
793 handler, return str unchanged. On Windows, use 'strict' error handler if
794 the file system encoding is 'mbcs' (which is the default encoding).
795 """
796 if isinstance(filename, str):
797 return filename
798 elif isinstance(filename, bytes):
799 return filename.decode(encoding, errors)
800 else:
801 raise TypeError("expect bytes or str, not %s" % type(filename).__name__)
802
803 return fsencode, fsdecode
804
805fsencode, fsdecode = _fscodec()
806del _fscodec
Victor Stinner449c4662010-05-08 11:10:09 +0000807
Guido van Rossum5a2ca931999-11-02 13:27:32 +0000808# Supply spawn*() (probably only for Unix)
809if _exists("fork") and not _exists("spawnv") and _exists("execv"):
810
811 P_WAIT = 0
812 P_NOWAIT = P_NOWAITO = 1
813
Petri Lehtinen3bc37f22012-05-23 21:36:16 +0300814 __all__.extend(["P_WAIT", "P_NOWAIT", "P_NOWAITO"])
815
Guido van Rossum5a2ca931999-11-02 13:27:32 +0000816 # XXX Should we support P_DETACH? I suppose it could fork()**2
817 # and close the std I/O streams. Also, P_OVERLAY is the same
818 # as execv*()?
819
820 def _spawnvef(mode, file, args, env, func):
821 # Internal helper; func is the exec*() function to use
822 pid = fork()
823 if not pid:
824 # Child
825 try:
826 if env is None:
827 func(file, args)
828 else:
829 func(file, args, env)
830 except:
831 _exit(127)
832 else:
833 # Parent
834 if mode == P_NOWAIT:
835 return pid # Caller is responsible for waiting!
836 while 1:
837 wpid, sts = waitpid(pid, 0)
838 if WIFSTOPPED(sts):
839 continue
840 elif WIFSIGNALED(sts):
841 return -WTERMSIG(sts)
842 elif WIFEXITED(sts):
843 return WEXITSTATUS(sts)
844 else:
Andrew Svetlov8b33dd82012-12-24 19:58:48 +0200845 raise OSError("Not stopped, signaled or exited???")
Guido van Rossum5a2ca931999-11-02 13:27:32 +0000846
847 def spawnv(mode, file, args):
Guido van Rossume0cd2912000-04-21 18:35:36 +0000848 """spawnv(mode, file, args) -> integer
849
850Execute file with arguments from args in a subprocess.
851If mode == P_NOWAIT return the pid of the process.
852If mode == P_WAIT return the process's exit code if it exits normally;
Tim Peters2344fae2001-01-15 00:50:52 +0000853otherwise return -SIG, where SIG is the signal that killed it. """
Guido van Rossum5a2ca931999-11-02 13:27:32 +0000854 return _spawnvef(mode, file, args, None, execv)
855
856 def spawnve(mode, file, args, env):
Guido van Rossume0cd2912000-04-21 18:35:36 +0000857 """spawnve(mode, file, args, env) -> integer
858
859Execute file with arguments from args in a subprocess with the
860specified environment.
861If mode == P_NOWAIT return the pid of the process.
862If mode == P_WAIT return the process's exit code if it exits normally;
863otherwise return -SIG, where SIG is the signal that killed it. """
Guido van Rossum5a2ca931999-11-02 13:27:32 +0000864 return _spawnvef(mode, file, args, env, execve)
865
Guido van Rossumdd7cbbf1999-11-02 20:44:07 +0000866 # Note: spawnvp[e] is't currently supported on Windows
867
868 def spawnvp(mode, file, args):
Guido van Rossume0cd2912000-04-21 18:35:36 +0000869 """spawnvp(mode, file, args) -> integer
870
871Execute file (which is looked for along $PATH) with arguments from
872args in a subprocess.
873If mode == P_NOWAIT return the pid of the process.
874If mode == P_WAIT return the process's exit code if it exits normally;
875otherwise return -SIG, where SIG is the signal that killed it. """
Guido van Rossumdd7cbbf1999-11-02 20:44:07 +0000876 return _spawnvef(mode, file, args, None, execvp)
877
878 def spawnvpe(mode, file, args, env):
Guido van Rossume0cd2912000-04-21 18:35:36 +0000879 """spawnvpe(mode, file, args, env) -> integer
880
881Execute file (which is looked for along $PATH) with arguments from
882args in a subprocess with the supplied environment.
883If mode == P_NOWAIT return the pid of the process.
884If mode == P_WAIT return the process's exit code if it exits normally;
885otherwise return -SIG, where SIG is the signal that killed it. """
Guido van Rossumdd7cbbf1999-11-02 20:44:07 +0000886 return _spawnvef(mode, file, args, env, execvpe)
887
Richard Oudkerkad34ef82013-05-07 14:23:42 +0100888
889 __all__.extend(["spawnv", "spawnve", "spawnvp", "spawnvpe"])
890
891
Guido van Rossumdd7cbbf1999-11-02 20:44:07 +0000892if _exists("spawnv"):
893 # These aren't supplied by the basic Windows code
894 # but can be easily implemented in Python
Guido van Rossum5a2ca931999-11-02 13:27:32 +0000895
896 def spawnl(mode, file, *args):
Guido van Rossume0cd2912000-04-21 18:35:36 +0000897 """spawnl(mode, file, *args) -> integer
898
899Execute file with arguments from args in a subprocess.
900If mode == P_NOWAIT return the pid of the process.
901If mode == P_WAIT return the process's exit code if it exits normally;
902otherwise return -SIG, where SIG is the signal that killed it. """
Guido van Rossum5a2ca931999-11-02 13:27:32 +0000903 return spawnv(mode, file, args)
904
905 def spawnle(mode, file, *args):
Guido van Rossume0cd2912000-04-21 18:35:36 +0000906 """spawnle(mode, file, *args, env) -> integer
907
908Execute file with arguments from args in a subprocess with the
909supplied environment.
910If mode == P_NOWAIT return the pid of the process.
911If mode == P_WAIT return the process's exit code if it exits normally;
912otherwise return -SIG, where SIG is the signal that killed it. """
Guido van Rossum5a2ca931999-11-02 13:27:32 +0000913 env = args[-1]
914 return spawnve(mode, file, args[:-1], env)
915
Andrew MacIntyre69e18c92004-04-04 07:11:43 +0000916
Richard Oudkerkad34ef82013-05-07 14:23:42 +0100917 __all__.extend(["spawnl", "spawnle"])
Andrew MacIntyre69e18c92004-04-04 07:11:43 +0000918
919
Guido van Rossumdd7cbbf1999-11-02 20:44:07 +0000920if _exists("spawnvp"):
921 # At the moment, Windows doesn't implement spawnvp[e],
922 # so it won't have spawnlp[e] either.
Guido van Rossum5a2ca931999-11-02 13:27:32 +0000923 def spawnlp(mode, file, *args):
Neal Norwitzb7f68102003-07-02 02:49:33 +0000924 """spawnlp(mode, file, *args) -> integer
Guido van Rossume0cd2912000-04-21 18:35:36 +0000925
926Execute file (which is looked for along $PATH) with arguments from
927args in a subprocess with the supplied environment.
928If mode == P_NOWAIT return the pid of the process.
929If mode == P_WAIT return the process's exit code if it exits normally;
930otherwise return -SIG, where SIG is the signal that killed it. """
Guido van Rossum5a2ca931999-11-02 13:27:32 +0000931 return spawnvp(mode, file, args)
932
933 def spawnlpe(mode, file, *args):
Guido van Rossume0cd2912000-04-21 18:35:36 +0000934 """spawnlpe(mode, file, *args, env) -> integer
935
936Execute file (which is looked for along $PATH) with arguments from
937args in a subprocess with the supplied environment.
938If mode == P_NOWAIT return the pid of the process.
939If mode == P_WAIT return the process's exit code if it exits normally;
940otherwise return -SIG, where SIG is the signal that killed it. """
Guido van Rossum5a2ca931999-11-02 13:27:32 +0000941 env = args[-1]
942 return spawnvpe(mode, file, args[:-1], env)
Guido van Rossume0cd2912000-04-21 18:35:36 +0000943
944
Richard Oudkerkad34ef82013-05-07 14:23:42 +0100945 __all__.extend(["spawnlp", "spawnlpe"])
946
Skip Montanaro269b83b2001-02-06 01:07:02 +0000947
Alexandre Vassalottif7fa63d2008-05-11 08:55:36 +0000948import copyreg as _copyreg
Michael W. Hudson0e025302002-03-06 17:11:18 +0000949
950def _make_stat_result(tup, dict):
951 return stat_result(tup, dict)
952
953def _pickle_stat_result(sr):
954 (type, args) = sr.__reduce__()
955 return (_make_stat_result, args)
956
Michael W. Hudsonce00b732002-03-15 10:18:58 +0000957try:
Alexandre Vassalottif7fa63d2008-05-11 08:55:36 +0000958 _copyreg.pickle(stat_result, _pickle_stat_result, _make_stat_result)
Michael W. Hudsonce00b732002-03-15 10:18:58 +0000959except NameError: # stat_result may not exist
960 pass
Michael W. Hudson0e025302002-03-06 17:11:18 +0000961
962def _make_statvfs_result(tup, dict):
963 return statvfs_result(tup, dict)
964
965def _pickle_statvfs_result(sr):
966 (type, args) = sr.__reduce__()
967 return (_make_statvfs_result, args)
968
Michael W. Hudsonce00b732002-03-15 10:18:58 +0000969try:
Alexandre Vassalottif7fa63d2008-05-11 08:55:36 +0000970 _copyreg.pickle(statvfs_result, _pickle_statvfs_result,
Michael W. Hudsonce00b732002-03-15 10:18:58 +0000971 _make_statvfs_result)
Michael W. Hudsone5363b72002-03-15 10:21:59 +0000972except NameError: # statvfs_result may not exist
Michael W. Hudsonce00b732002-03-15 10:18:58 +0000973 pass
Martin v. Löwisdc3883f2004-08-29 15:46:35 +0000974
Guido van Rossumc2f93dc2007-05-24 00:50:02 +0000975# Supply os.popen()
Antoine Pitrou877766d2011-03-19 17:00:37 +0100976def popen(cmd, mode="r", buffering=-1):
Guido van Rossum3172c5d2007-10-16 18:12:55 +0000977 if not isinstance(cmd, str):
Guido van Rossumc2f93dc2007-05-24 00:50:02 +0000978 raise TypeError("invalid cmd type (%s, expected string)" % type(cmd))
979 if mode not in ("r", "w"):
980 raise ValueError("invalid mode %r" % mode)
Benjamin Petersonb29614e2012-10-09 11:16:03 -0400981 if buffering == 0 or buffering is None:
Antoine Pitrou877766d2011-03-19 17:00:37 +0100982 raise ValueError("popen() does not support unbuffered streams")
Guido van Rossumc2f93dc2007-05-24 00:50:02 +0000983 import subprocess, io
984 if mode == "r":
985 proc = subprocess.Popen(cmd,
986 shell=True,
987 stdout=subprocess.PIPE,
988 bufsize=buffering)
989 return _wrap_close(io.TextIOWrapper(proc.stdout), proc)
990 else:
991 proc = subprocess.Popen(cmd,
992 shell=True,
993 stdin=subprocess.PIPE,
994 bufsize=buffering)
995 return _wrap_close(io.TextIOWrapper(proc.stdin), proc)
996
997# Helper for popen() -- a proxy for a file whose close waits for the process
998class _wrap_close:
999 def __init__(self, stream, proc):
1000 self._stream = stream
1001 self._proc = proc
1002 def close(self):
1003 self._stream.close()
Amaury Forgeot d'Arc97e5f282009-07-11 09:35:13 +00001004 returncode = self._proc.wait()
1005 if returncode == 0:
1006 return None
1007 if name == 'nt':
1008 return returncode
1009 else:
1010 return returncode << 8 # Shift left to match old behavior
Antoine Pitrouac625352009-12-09 00:01:27 +00001011 def __enter__(self):
1012 return self
1013 def __exit__(self, *args):
1014 self.close()
Guido van Rossumc2f93dc2007-05-24 00:50:02 +00001015 def __getattr__(self, name):
1016 return getattr(self._stream, name)
Thomas Heller476157b2007-09-04 11:27:47 +00001017 def __iter__(self):
1018 return iter(self._stream)
Guido van Rossumc2f93dc2007-05-24 00:50:02 +00001019
Amaury Forgeot d'Arcbdbddf82008-08-01 00:06:49 +00001020# Supply os.fdopen()
1021def fdopen(fd, *args, **kwargs):
Guido van Rossumc2f93dc2007-05-24 00:50:02 +00001022 if not isinstance(fd, int):
1023 raise TypeError("invalid fd type (%s, expected integer)" % type(fd))
1024 import io
Amaury Forgeot d'Arcbdbddf82008-08-01 00:06:49 +00001025 return io.open(fd, *args, **kwargs)