Google Git
Sign in
chromium / external / github.com / python / cpython / refs/tags/3.3 / . / Lib / os.py
blob: b42ccbab38196a210a3f6f342624892a82b160bb [file] [log] [blame]
Georg Brandlbde4ad42006-01-20 21:36:02[diff] [blame]1r"""OS routines for Mac, NT, or Posix depending on what system we're on.
Guido van Rossum31104f41992-01-14 18:28:36[diff] [blame]2
Guido van Rossum54f22ed2000-02-04 15:10:34[diff] [blame]3This exports:
Alexandre Vassalottieca20b62008-05-16 02:54:33[diff] [blame]4 - all functions from posix, nt, os2, or ce, e.g. unlink, stat, etc.
5 - os.path is either posixpath or ntpath
6 - os.name is either 'posix', 'nt', 'os2' or 'ce'.
Guido van Rossum54f22ed2000-02-04 15:10:34[diff] [blame]7 - 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[diff] [blame]10 - os.extsep is the extension separator (always '.')
Guido van Rossum4b8c6ea2000-02-04 15:39:30[diff] [blame]11 - os.altsep is the alternate pathname separator (None or '/')
Guido van Rossum54f22ed2000-02-04 15:10:34[diff] [blame]12 - os.pathsep is the component separator used in $PATH etc
Guido van Rossum4b8c6ea2000-02-04 15:39:30[diff] [blame]13 - os.linesep is the line separator in text files ('\r' or '\n' or '\r\n')
Guido van Rossum54f22ed2000-02-04 15:10:34[diff] [blame]14 - os.defpath is the default search path for executables
Martin v. Löwisbdec50f2004-06-08 08:29:33[diff] [blame]15 - os.devnull is the file path of the null device ('/dev/null', etc.)
Guido van Rossum31104f41992-01-14 18:28:36[diff] [blame]16
Guido van Rossum54f22ed2000-02-04 15:10:34[diff] [blame]17Programs 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[diff] [blame]23
Skip Montanaro269b83b2001-02-06 01:07:02[diff] [blame]24#'
25
Christian Heimes45f9af32007-11-27 21:50:00[diff] [blame]26import sys, errno
Charles-François Natali7372b062012-02-05 14:15:38[diff] [blame]27import stat as st
Guido van Rossuma28dab51997-08-29 22:36:47[diff] [blame]28
29_names = sys.builtin_module_names
30
Tim Petersc4e09402003-04-25 07:11:48[diff] [blame]31# Note: more names are added to __all__ later.
Brett Cannon13962fc2008-08-18 01:45:29[diff] [blame]32__all__ = ["altsep", "curdir", "pardir", "sep", "pathsep", "linesep",
Petri Lehtinen3bc37f22012-05-23 18:36:16[diff] [blame]33 "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[diff] [blame]36
Charles-François Natali7372b062012-02-05 14:15:38[diff] [blame]37def _exists(name):
38 return name in globals()
39
Skip Montanaro269b83b2001-02-06 01:07:02[diff] [blame]40def _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 18:10:13[diff] [blame]46# 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[diff] [blame]48if 'posix' in _names:
Guido van Rossum61de0ac1997-12-05 21:24:30[diff] [blame]49 name = 'posix'
Guido van Rossume9387ea1998-05-22 15:26:04[diff] [blame]50 linesep = '\n'
Guido van Rossum61de0ac1997-12-05 21:24:30[diff] [blame]51 from posix import *
52 try:
53 from posix import _exit
Petri Lehtinen3bc37f22012-05-23 18:36:16[diff] [blame]54 __all__.append('_exit')
Guido van Rossum61de0ac1997-12-05 21:24:30[diff] [blame]55 except ImportError:
56 pass
Skip Montanaro117910d2003-02-14 19:35:31[diff] [blame]57 import posixpath as path
Tim Petersf2715e02003-02-19 02:35:07[diff] [blame]58
Larry Hastings9cf065c2012-06-22 23:30:09[diff] [blame]59 try:
60 from posix import _have_functions
61 except ImportError:
62 pass
Skip Montanaro269b83b2001-02-06 01:07:02[diff] [blame]63
Guido van Rossuma28dab51997-08-29 22:36:47[diff] [blame]64elif 'nt' in _names:
Guido van Rossum61de0ac1997-12-05 21:24:30[diff] [blame]65 name = 'nt'
Guido van Rossume9387ea1998-05-22 15:26:04[diff] [blame]66 linesep = '\r\n'
Guido van Rossum61de0ac1997-12-05 21:24:30[diff] [blame]67 from nt import *
Tim Peters6757c1e2003-01-08 21:20:57[diff] [blame]68 try:
69 from nt import _exit
Petri Lehtinen3bc37f22012-05-23 18:36:16[diff] [blame]70 __all__.append('_exit')
Tim Peters6757c1e2003-01-08 21:20:57[diff] [blame]71 except ImportError:
72 pass
Skip Montanaro117910d2003-02-14 19:35:31[diff] [blame]73 import ntpath as path
Tim Petersf2715e02003-02-19 02:35:07[diff] [blame]74
Skip Montanaro269b83b2001-02-06 01:07:02[diff] [blame]75 import nt
76 __all__.extend(_get_exports_list(nt))
77 del nt
78
Larry Hastings9cf065c2012-06-22 23:30:09[diff] [blame]79 try:
80 from nt import _have_functions
81 except ImportError:
82 pass
83
Guido van Rossum8e9ebfd1997-11-22 21:53:48[diff] [blame]84elif 'os2' in _names:
Guido van Rossum61de0ac1997-12-05 21:24:30[diff] [blame]85 name = 'os2'
Guido van Rossume9387ea1998-05-22 15:26:04[diff] [blame]86 linesep = '\r\n'
Guido van Rossum61de0ac1997-12-05 21:24:30[diff] [blame]87 from os2 import *
88 try:
89 from os2 import _exit
Petri Lehtinen3bc37f22012-05-23 18:36:16[diff] [blame]90 __all__.append('_exit')
Guido van Rossum61de0ac1997-12-05 21:24:30[diff] [blame]91 except ImportError:
92 pass
Andrew MacIntyre5cef5712002-02-24 05:32:32[diff] [blame]93 if sys.version.find('EMX GCC') == -1:
Skip Montanaro117910d2003-02-14 19:35:31[diff] [blame]94 import ntpath as path
Andrew MacIntyre5cef5712002-02-24 05:32:32[diff] [blame]95 else:
Skip Montanaro117910d2003-02-14 19:35:31[diff] [blame]96 import os2emxpath as path
Andrew MacIntyre89f98652003-12-02 12:33:01[diff] [blame]97 from _emx_link import link
Tim Petersf2715e02003-02-19 02:35:07[diff] [blame]98
Skip Montanaro269b83b2001-02-06 01:07:02[diff] [blame]99 import os2
100 __all__.extend(_get_exports_list(os2))
101 del os2
102
Larry Hastings9cf065c2012-06-22 23:30:09[diff] [blame]103 try:
104 from os2 import _have_functions
105 except ImportError:
106 pass
107
Guido van Rossum18df5d41999-06-11 01:37:27[diff] [blame]108elif 'ce' in _names:
109 name = 'ce'
110 linesep = '\r\n'
Guido van Rossum18df5d41999-06-11 01:37:27[diff] [blame]111 from ce import *
Tim Peters6757c1e2003-01-08 21:20:57[diff] [blame]112 try:
113 from ce import _exit
Petri Lehtinen3bc37f22012-05-23 18:36:16[diff] [blame]114 __all__.append('_exit')
Tim Peters6757c1e2003-01-08 21:20:57[diff] [blame]115 except ImportError:
116 pass
Guido van Rossum18df5d41999-06-11 01:37:27[diff] [blame]117 # We can use the standard Windows path.
Skip Montanaro117910d2003-02-14 19:35:31[diff] [blame]118 import ntpath as path
Tim Petersf2715e02003-02-19 02:35:07[diff] [blame]119
Skip Montanaro269b83b2001-02-06 01:07:02[diff] [blame]120 import ce
121 __all__.extend(_get_exports_list(ce))
122 del ce
123
Larry Hastings9cf065c2012-06-22 23:30:09[diff] [blame]124 try:
125 from ce import _have_functions
126 except ImportError:
127 pass
128
Guido van Rossum2979b011994-08-01 11:18:30[diff] [blame]129else:
Collin Winter828f04a2007-08-31 00:04:24[diff] [blame]130 raise ImportError('no os specific module found')
Guido van Rossume65cce51993-11-08 15:05:21[diff] [blame]131
Skip Montanaro117910d2003-02-14 19:35:31[diff] [blame]132sys.modules['os.path'] = path
Georg Brandled5b9b32008-12-05 07:45:54[diff] [blame]133from os.path import (curdir, pardir, sep, pathsep, defpath, extsep, altsep,
134 devnull)
Skip Montanaro269b83b2001-02-06 01:07:02[diff] [blame]135
Guido van Rossuma28dab51997-08-29 22:36:47[diff] [blame]136del _names
137
Larry Hastings9cf065c2012-06-22 23:30:09[diff] [blame]138
139if _exists("_have_functions"):
140 _globals = globals()
141 def _add(str, fn):
142 if (fn in _globals) and (str in _have_functions):
143 _set.add(_globals[fn])
144
145 _set = set()
146 _add("HAVE_FACCESSAT", "access")
147 _add("HAVE_FCHMODAT", "chmod")
148 _add("HAVE_FCHOWNAT", "chown")
149 _add("HAVE_FSTATAT", "stat")
150 _add("HAVE_FUTIMESAT", "utime")
151 _add("HAVE_LINKAT", "link")
152 _add("HAVE_MKDIRAT", "mkdir")
153 _add("HAVE_MKFIFOAT", "mkfifo")
154 _add("HAVE_MKNODAT", "mknod")
155 _add("HAVE_OPENAT", "open")
156 _add("HAVE_READLINKAT", "readlink")
157 _add("HAVE_RENAMEAT", "rename")
158 _add("HAVE_SYMLINKAT", "symlink")
159 _add("HAVE_UNLINKAT", "unlink")
Larry Hastingsb698d8e2012-06-23 23:55:07[diff] [blame]160 _add("HAVE_UNLINKAT", "rmdir")
Larry Hastings9cf065c2012-06-22 23:30:09[diff] [blame]161 _add("HAVE_UTIMENSAT", "utime")
162 supports_dir_fd = _set
163
164 _set = set()
165 _add("HAVE_FACCESSAT", "access")
166 supports_effective_ids = _set
167
168 _set = set()
169 _add("HAVE_FCHDIR", "chdir")
170 _add("HAVE_FCHMOD", "chmod")
171 _add("HAVE_FCHOWN", "chown")
172 _add("HAVE_FDOPENDIR", "listdir")
173 _add("HAVE_FEXECVE", "execve")
174 _set.add(stat) # fstat always works
Georg Brandl306336b2012-06-24 10:55:33[diff] [blame]175 _add("HAVE_FTRUNCATE", "truncate")
Larry Hastings9cf065c2012-06-22 23:30:09[diff] [blame]176 _add("HAVE_FUTIMENS", "utime")
177 _add("HAVE_FUTIMES", "utime")
Georg Brandl306336b2012-06-24 10:55:33[diff] [blame]178 _add("HAVE_FPATHCONF", "pathconf")
Larry Hastings9cf065c2012-06-22 23:30:09[diff] [blame]179 if _exists("statvfs") and _exists("fstatvfs"): # mac os x10.3
180 _add("HAVE_FSTATVFS", "statvfs")
181 supports_fd = _set
182
183 _set = set()
184 _add("HAVE_FACCESSAT", "access")
Larry Hastingsdbbc0c82012-06-23 02:50:21[diff] [blame]185 # Some platforms don't support lchmod(). Often the function exists
186 # anyway, as a stub that always returns ENOSUP or perhaps EOPNOTSUPP.
187 # (No, I don't know why that's a good design.) ./configure will detect
188 # this and reject it--so HAVE_LCHMOD still won't be defined on such
189 # platforms. This is Very Helpful.
190 #
191 # However, sometimes platforms without a working lchmod() *do* have
192 # fchmodat(). (Examples: Linux kernel 3.2 with glibc 2.15,
193 # OpenIndiana 3.x.) And fchmodat() has a flag that theoretically makes
194 # it behave like lchmod(). So in theory it would be a suitable
195 # replacement for lchmod(). But when lchmod() doesn't work, fchmodat()'s
196 # flag doesn't work *either*. Sadly ./configure isn't sophisticated
197 # enough to detect this condition--it only determines whether or not
198 # fchmodat() minimally works.
199 #
200 # Therefore we simply ignore fchmodat() when deciding whether or not
201 # os.chmod supports follow_symlinks. Just checking lchmod() is
202 # sufficient. After all--if you have a working fchmodat(), your
203 # lchmod() almost certainly works too.
204 #
205 # _add("HAVE_FCHMODAT", "chmod")
Larry Hastings9cf065c2012-06-22 23:30:09[diff] [blame]206 _add("HAVE_FCHOWNAT", "chown")
207 _add("HAVE_FSTATAT", "stat")
208 _add("HAVE_LCHFLAGS", "chflags")
209 _add("HAVE_LCHMOD", "chmod")
210 if _exists("lchown"): # mac os x10.3
211 _add("HAVE_LCHOWN", "chown")
212 _add("HAVE_LINKAT", "link")
213 _add("HAVE_LUTIMES", "utime")
214 _add("HAVE_LSTAT", "stat")
215 _add("HAVE_FSTATAT", "stat")
216 _add("HAVE_UTIMENSAT", "utime")
217 _add("MS_WINDOWS", "stat")
218 supports_follow_symlinks = _set
219
Larry Hastings9cf065c2012-06-22 23:30:09[diff] [blame]220 del _set
221 del _have_functions
222 del _globals
223 del _add
224
225
Martin v. Löwis22b457e2005-01-16 08:40:58[diff] [blame]226# Python uses fixed values for the SEEK_ constants; they are mapped
227# to native constants if necessary in posixmodule.c
Jesus Cea94363612012-06-22 16:32:07[diff] [blame]228# Other possible SEEK values are directly imported from posixmodule.c
Martin v. Löwis22b457e2005-01-16 08:40:58[diff] [blame]229SEEK_SET = 0
230SEEK_CUR = 1
231SEEK_END = 2
232
Guido van Rossum4def7de1998-07-24 20:48:03[diff] [blame]233# Super directory utilities.
234# (Inspired by Eric Raymond; the doc strings are mostly his)
235
Terry Reedy5a22b652010-12-02 07:05:56[diff] [blame]236def makedirs(name, mode=0o777, exist_ok=False):
237 """makedirs(path [, mode=0o777][, exist_ok=False])
Guido van Rossum4def7de1998-07-24 20:48:03[diff] [blame]238
Benjamin Petersonee5f1c12014-04-01 23:13:18[diff] [blame]239 Super-mkdir; create a leaf directory and all intermediate ones. Works like
240 mkdir, except that any intermediate path segment (not just the rightmost)
241 will be created if it does not exist. If the target directory already
242 exists, raise an OSError if exist_ok is False. Otherwise no exception is
Terry Reedy5a22b652010-12-02 07:05:56[diff] [blame]243 raised. This is recursive.
Guido van Rossum4def7de1998-07-24 20:48:03[diff] [blame]244
245 """
246 head, tail = path.split(name)
Fred Drake9f2550f2000-07-25 15:16:40[diff] [blame]247 if not tail:
248 head, tail = path.split(head)
Guido van Rossum4def7de1998-07-24 20:48:03[diff] [blame]249 if head and tail and not path.exists(head):
Thomas Wouters89f507f2006-12-13 04:49:30[diff] [blame]250 try:
Terry Reedy5a22b652010-12-02 07:05:56[diff] [blame]251 makedirs(head, mode, exist_ok)
Guido van Rossumb940e112007-01-10 16:19:56[diff] [blame]252 except OSError as e:
Thomas Wouters89f507f2006-12-13 04:49:30[diff] [blame]253 # be happy if someone already created the path
Christian Heimes45f9af32007-11-27 21:50:00[diff] [blame]254 if e.errno != errno.EEXIST:
Thomas Wouters89f507f2006-12-13 04:49:30[diff] [blame]255 raise
Serhiy Storchaka4ab23bf2013-01-08 09:32:58[diff] [blame]256 cdir = curdir
257 if isinstance(tail, bytes):
258 cdir = bytes(curdir, 'ASCII')
259 if tail == cdir: # xxx/newdir/. exists if xxx/newdir exists
Andrew M. Kuchling6fccc8a2003-12-23 16:33:28[diff] [blame]260 return
Terry Reedy5a22b652010-12-02 07:05:56[diff] [blame]261 try:
262 mkdir(name, mode)
263 except OSError as e:
Benjamin Petersonee5f1c12014-04-01 23:13:18[diff] [blame]264 if not exist_ok or e.errno != errno.EEXIST or not path.isdir(name):
Terry Reedy5a22b652010-12-02 07:05:56[diff] [blame]265 raise
Guido van Rossum4def7de1998-07-24 20:48:03[diff] [blame]266
267def removedirs(name):
Fred Drakecadb9eb2002-07-02 21:28:04[diff] [blame]268 """removedirs(path)
Guido van Rossum4def7de1998-07-24 20:48:03[diff] [blame]269
Fredrik Lundh96c1c7a2005-11-12 15:55:04[diff] [blame]270 Super-rmdir; remove a leaf directory and all empty intermediate
Guido van Rossum4def7de1998-07-24 20:48:03[diff] [blame]271 ones. Works like rmdir except that, if the leaf directory is
272 successfully removed, directories corresponding to rightmost path
Tim Petersc4e09402003-04-25 07:11:48[diff] [blame]273 segments will be pruned away until either the whole path is
Guido van Rossum4def7de1998-07-24 20:48:03[diff] [blame]274 consumed or an error occurs. Errors during this latter phase are
275 ignored -- they generally mean that a directory was not empty.
276
277 """
278 rmdir(name)
279 head, tail = path.split(name)
Fred Drake9f2550f2000-07-25 15:16:40[diff] [blame]280 if not tail:
281 head, tail = path.split(head)
Guido van Rossum4def7de1998-07-24 20:48:03[diff] [blame]282 while head and tail:
283 try:
284 rmdir(head)
285 except error:
286 break
287 head, tail = path.split(head)
288
289def renames(old, new):
Fred Drakecadb9eb2002-07-02 21:28:04[diff] [blame]290 """renames(old, new)
Guido van Rossum4def7de1998-07-24 20:48:03[diff] [blame]291
292 Super-rename; create directories as necessary and delete any left
293 empty. Works like rename, except creation of any intermediate
294 directories needed to make the new pathname good is attempted
295 first. After the rename, directories corresponding to rightmost
296 path segments of the old name will be pruned way until either the
297 whole path is consumed or a nonempty directory is found.
298
299 Note: this function can fail with the new directory structure made
300 if you lack permissions needed to unlink the leaf directory or
301 file.
302
303 """
304 head, tail = path.split(new)
305 if head and tail and not path.exists(head):
306 makedirs(head)
307 rename(old, new)
308 head, tail = path.split(old)
309 if head and tail:
310 try:
311 removedirs(head)
312 except error:
313 pass
314
Skip Montanaro269b83b2001-02-06 01:07:02[diff] [blame]315__all__.extend(["makedirs", "removedirs", "renames"])
316
Guido van Rossumd8faa362007-04-27 19:54:29[diff] [blame]317def walk(top, topdown=True, onerror=None, followlinks=False):
Tim Petersc4e09402003-04-25 07:11:48[diff] [blame]318 """Directory tree generator.
319
320 For each directory in the directory tree rooted at top (including top
321 itself, but excluding '.' and '..'), yields a 3-tuple
322
323 dirpath, dirnames, filenames
324
325 dirpath is a string, the path to the directory. dirnames is a list of
326 the names of the subdirectories in dirpath (excluding '.' and '..').
327 filenames is a list of the names of the non-directory files in dirpath.
328 Note that the names in the lists are just names, with no path components.
329 To get a full path (which begins with top) to a file or directory in
330 dirpath, do os.path.join(dirpath, name).
331
332 If optional arg 'topdown' is true or not specified, the triple for a
333 directory is generated before the triples for any of its subdirectories
334 (directories are generated top down). If topdown is false, the triple
335 for a directory is generated after the triples for all of its
336 subdirectories (directories are generated bottom up).
337
338 When topdown is true, the caller can modify the dirnames list in-place
339 (e.g., via del or slice assignment), and walk will only recurse into the
340 subdirectories whose names remain in dirnames; this can be used to prune
341 the search, or to impose a specific order of visiting. Modifying
342 dirnames when topdown is false is ineffective, since the directories in
343 dirnames have already been generated by the time dirnames itself is
344 generated.
345
Guido van Rossumbf1bef82003-05-13 18:01:19[diff] [blame]346 By default errors from the os.listdir() call are ignored. If
347 optional arg 'onerror' is specified, it should be a function; it
348 will be called with one argument, an os.error instance. It can
349 report the error to continue with the walk, or raise the exception
350 to abort the walk. Note that the filename is available as the
351 filename attribute of the exception object.
352
Guido van Rossumd8faa362007-04-27 19:54:29[diff] [blame]353 By default, os.walk does not follow symbolic links to subdirectories on
354 systems that support them. In order to get this functionality, set the
355 optional argument 'followlinks' to true.
356
Tim Petersc4e09402003-04-25 07:11:48[diff] [blame]357 Caution: if you pass a relative pathname for top, don't change the
358 current working directory between resumptions of walk. walk never
359 changes the current directory, and assumes that the client doesn't
360 either.
361
362 Example:
363
Christian Heimes5d8da202008-05-06 13:58:24[diff] [blame]364 import os
Tim Petersc4e09402003-04-25 07:11:48[diff] [blame]365 from os.path import join, getsize
Christian Heimes5d8da202008-05-06 13:58:24[diff] [blame]366 for root, dirs, files in os.walk('python/Lib/email'):
Neal Norwitz752abd02008-05-13 04:55:24[diff] [blame]367 print(root, "consumes", end="")
368 print(sum([getsize(join(root, name)) for name in files]), end="")
369 print("bytes in", len(files), "non-directory files")
Tim Petersc4e09402003-04-25 07:11:48[diff] [blame]370 if 'CVS' in dirs:
371 dirs.remove('CVS') # don't visit CVS directories
372 """
373
Benjamin Petersonf6489f92009-11-25 17:46:26[diff] [blame]374 islink, join, isdir = path.islink, path.join, path.isdir
Tim Petersc4e09402003-04-25 07:11:48[diff] [blame]375
376 # We may not have read permission for top, in which case we can't
Alexandre Vassalotti4e6531e2008-05-09 20:00:17[diff] [blame]377 # get a list of the files the directory contains. os.walk
Tim Petersc4e09402003-04-25 07:11:48[diff] [blame]378 # always suppressed the exception then, rather than blow up for a
379 # minor reason when (say) a thousand readable directories are still
380 # left to visit. That logic is copied here.
381 try:
382 # Note that listdir and error are globals in this module due
383 # to earlier import-*.
384 names = listdir(top)
Guido van Rossumb940e112007-01-10 16:19:56[diff] [blame]385 except error as err:
Guido van Rossumbf1bef82003-05-13 18:01:19[diff] [blame]386 if onerror is not None:
387 onerror(err)
Tim Petersc4e09402003-04-25 07:11:48[diff] [blame]388 return
389
390 dirs, nondirs = [], []
391 for name in names:
392 if isdir(join(top, name)):
393 dirs.append(name)
394 else:
395 nondirs.append(name)
396
397 if topdown:
398 yield top, dirs, nondirs
399 for name in dirs:
Benjamin Petersonf6489f92009-11-25 17:46:26[diff] [blame]400 new_path = join(top, name)
401 if followlinks or not islink(new_path):
Benjamin Peterson569d0872012-05-10 21:17:35[diff] [blame]402 yield from walk(new_path, topdown, onerror, followlinks)
Tim Petersc4e09402003-04-25 07:11:48[diff] [blame]403 if not topdown:
404 yield top, dirs, nondirs
405
406__all__.append("walk")
407
Larry Hastingsc48fe982012-06-25 11:49:05[diff] [blame]408if {open, stat} <= supports_dir_fd and {listdir, stat} <= supports_fd:
Charles-François Natali7372b062012-02-05 14:15:38[diff] [blame]409
Larry Hastingsb4038062012-07-15 17:57:38[diff] [blame]410 def fwalk(top=".", topdown=True, onerror=None, *, follow_symlinks=False, dir_fd=None):
Charles-François Natali7372b062012-02-05 14:15:38[diff] [blame]411 """Directory tree generator.
412
413 This behaves exactly like walk(), except that it yields a 4-tuple
414
415 dirpath, dirnames, filenames, dirfd
416
417 `dirpath`, `dirnames` and `filenames` are identical to walk() output,
418 and `dirfd` is a file descriptor referring to the directory `dirpath`.
419
Larry Hastingsc48fe982012-06-25 11:49:05[diff] [blame]420 The advantage of fwalk() over walk() is that it's safe against symlink
Larry Hastingsb4038062012-07-15 17:57:38[diff] [blame]421 races (when follow_symlinks is False).
Charles-François Natali7372b062012-02-05 14:15:38[diff] [blame]422
Larry Hastingsc48fe982012-06-25 11:49:05[diff] [blame]423 If dir_fd is not None, it should be a file descriptor open to a directory,
424 and top should be relative; top will then be relative to that directory.
425 (dir_fd is always supported for fwalk.)
426
Charles-François Natali7372b062012-02-05 14:15:38[diff] [blame]427 Caution:
428 Since fwalk() yields file descriptors, those are only valid until the
429 next iteration step, so you should dup() them if you want to keep them
430 for a longer period.
431
432 Example:
433
434 import os
435 for root, dirs, files, rootfd in os.fwalk('python/Lib/email'):
436 print(root, "consumes", end="")
Larry Hastings9cf065c2012-06-22 23:30:09[diff] [blame]437 print(sum([os.stat(name, dir_fd=rootfd).st_size for name in files]),
Charles-François Natali7372b062012-02-05 14:15:38[diff] [blame]438 end="")
439 print("bytes in", len(files), "non-directory files")
440 if 'CVS' in dirs:
441 dirs.remove('CVS') # don't visit CVS directories
442 """
443 # Note: To guard against symlink races, we use the standard
444 # lstat()/open()/fstat() trick.
Larry Hastingsc48fe982012-06-25 11:49:05[diff] [blame]445 orig_st = stat(top, follow_symlinks=False, dir_fd=dir_fd)
446 topfd = open(top, O_RDONLY, dir_fd=dir_fd)
Charles-François Natali7372b062012-02-05 14:15:38[diff] [blame]447 try:
Larry Hastingsb4038062012-07-15 17:57:38[diff] [blame]448 if (follow_symlinks or (st.S_ISDIR(orig_st.st_mode) and
449 path.samestat(orig_st, stat(topfd)))):
450 yield from _fwalk(topfd, top, topdown, onerror, follow_symlinks)
Charles-François Natali7372b062012-02-05 14:15:38[diff] [blame]451 finally:
452 close(topfd)
453
Larry Hastingsb4038062012-07-15 17:57:38[diff] [blame]454 def _fwalk(topfd, toppath, topdown, onerror, follow_symlinks):
Charles-François Natali7372b062012-02-05 14:15:38[diff] [blame]455 # Note: This uses O(depth of the directory tree) file descriptors: if
456 # necessary, it can be adapted to only require O(1) FDs, see issue
457 # #13734.
458
Larry Hastings9cf065c2012-06-22 23:30:09[diff] [blame]459 names = listdir(topfd)
Charles-François Natali7372b062012-02-05 14:15:38[diff] [blame]460 dirs, nondirs = [], []
461 for name in names:
Hynek Schlawack66bfcc12012-05-15 14:32:21[diff] [blame]462 try:
463 # Here, we don't use AT_SYMLINK_NOFOLLOW to be consistent with
464 # walk() which reports symlinks to directories as directories.
465 # We do however check for symlinks before recursing into
466 # a subdirectory.
Larry Hastings9cf065c2012-06-22 23:30:09[diff] [blame]467 if st.S_ISDIR(stat(name, dir_fd=topfd).st_mode):
Hynek Schlawack66bfcc12012-05-15 14:32:21[diff] [blame]468 dirs.append(name)
469 else:
470 nondirs.append(name)
471 except FileNotFoundError:
472 try:
473 # Add dangling symlinks, ignore disappeared files
Larry Hastings9cf065c2012-06-22 23:30:09[diff] [blame]474 if st.S_ISLNK(stat(name, dir_fd=topfd, follow_symlinks=False)
Hynek Schlawack66bfcc12012-05-15 14:32:21[diff] [blame]475 .st_mode):
476 nondirs.append(name)
477 except FileNotFoundError:
478 continue
Charles-François Natali7372b062012-02-05 14:15:38[diff] [blame]479
480 if topdown:
481 yield toppath, dirs, nondirs, topfd
482
483 for name in dirs:
484 try:
Larry Hastingsb4038062012-07-15 17:57:38[diff] [blame]485 orig_st = stat(name, dir_fd=topfd, follow_symlinks=follow_symlinks)
Larry Hastings9cf065c2012-06-22 23:30:09[diff] [blame]486 dirfd = open(name, O_RDONLY, dir_fd=topfd)
Charles-François Natali7372b062012-02-05 14:15:38[diff] [blame]487 except error as err:
488 if onerror is not None:
489 onerror(err)
490 return
491 try:
Larry Hastingsb4038062012-07-15 17:57:38[diff] [blame]492 if follow_symlinks or path.samestat(orig_st, stat(dirfd)):
Charles-François Natali7372b062012-02-05 14:15:38[diff] [blame]493 dirpath = path.join(toppath, name)
Larry Hastingsb4038062012-07-15 17:57:38[diff] [blame]494 yield from _fwalk(dirfd, dirpath, topdown, onerror, follow_symlinks)
Charles-François Natali7372b062012-02-05 14:15:38[diff] [blame]495 finally:
496 close(dirfd)
497
498 if not topdown:
499 yield toppath, dirs, nondirs, topfd
500
501 __all__.append("fwalk")
502
Guido van Rossuma28dab51997-08-29 22:36:47[diff] [blame]503# Make sure os.environ exists, at least
504try:
Guido van Rossum61de0ac1997-12-05 21:24:30[diff] [blame]505 environ
Guido van Rossuma28dab51997-08-29 22:36:47[diff] [blame]506except NameError:
Guido van Rossum61de0ac1997-12-05 21:24:30[diff] [blame]507 environ = {}
Guido van Rossuma28dab51997-08-29 22:36:47[diff] [blame]508
Guido van Rossume65cce51993-11-08 15:05:21[diff] [blame]509def execl(file, *args):
Guido van Rossum7da3cc52000-04-25 10:53:22[diff] [blame]510 """execl(file, *args)
511
512 Execute the executable file with argument list args, replacing the
513 current process. """
Guido van Rossum61de0ac1997-12-05 21:24:30[diff] [blame]514 execv(file, args)
Guido van Rossume65cce51993-11-08 15:05:21[diff] [blame]515
516def execle(file, *args):
Guido van Rossum7da3cc52000-04-25 10:53:22[diff] [blame]517 """execle(file, *args, env)
518
519 Execute the executable file with argument list args and
520 environment env, replacing the current process. """
Guido van Rossum61de0ac1997-12-05 21:24:30[diff] [blame]521 env = args[-1]
522 execve(file, args[:-1], env)
Guido van Rossume65cce51993-11-08 15:05:21[diff] [blame]523
524def execlp(file, *args):
Guido van Rossum7da3cc52000-04-25 10:53:22[diff] [blame]525 """execlp(file, *args)
526
527 Execute the executable file (which is searched for along $PATH)
528 with argument list args, replacing the current process. """
Guido van Rossum61de0ac1997-12-05 21:24:30[diff] [blame]529 execvp(file, args)
Guido van Rossume65cce51993-11-08 15:05:21[diff] [blame]530
Guido van Rossum030afb11995-03-14 17:27:18[diff] [blame]531def execlpe(file, *args):
Guido van Rossum7da3cc52000-04-25 10:53:22[diff] [blame]532 """execlpe(file, *args, env)
533
534 Execute the executable file (which is searched for along $PATH)
535 with argument list args and environment env, replacing the current
Tim Peters2344fae2001-01-15 00:50:52[diff] [blame]536 process. """
Guido van Rossum61de0ac1997-12-05 21:24:30[diff] [blame]537 env = args[-1]
538 execvpe(file, args[:-1], env)
Guido van Rossum030afb11995-03-14 17:27:18[diff] [blame]539
Guido van Rossume65cce51993-11-08 15:05:21[diff] [blame]540def execvp(file, args):
Matthias Klosea09c54f2010-01-31 16:48:44[diff] [blame]541 """execvp(file, args)
Guido van Rossum7da3cc52000-04-25 10:53:22[diff] [blame]542
543 Execute the executable file (which is searched for along $PATH)
544 with argument list args, replacing the current process.
Thomas Wouters7e474022000-07-16 12:04:32[diff] [blame]545 args may be a list or tuple of strings. """
Guido van Rossum61de0ac1997-12-05 21:24:30[diff] [blame]546 _execvpe(file, args)
Guido van Rossum030afb11995-03-14 17:27:18[diff] [blame]547
548def execvpe(file, args, env):
Guido van Rossum683c0fe2002-09-03 16:36:17[diff] [blame]549 """execvpe(file, args, env)
Guido van Rossum7da3cc52000-04-25 10:53:22[diff] [blame]550
551 Execute the executable file (which is searched for along $PATH)
552 with argument list args and environment env , replacing the
553 current process.
Tim Peters2344fae2001-01-15 00:50:52[diff] [blame]554 args may be a list or tuple of strings. """
Guido van Rossum61de0ac1997-12-05 21:24:30[diff] [blame]555 _execvpe(file, args, env)
Guido van Rossum030afb11995-03-14 17:27:18[diff] [blame]556
Skip Montanaro269b83b2001-02-06 01:07:02[diff] [blame]557__all__.extend(["execl","execle","execlp","execlpe","execvp","execvpe"])
558
Guido van Rossum5a2ca931999-11-02 13:27:32[diff] [blame]559def _execvpe(file, args, env=None):
Guido van Rossum5a2ca931999-11-02 13:27:32[diff] [blame]560 if env is not None:
Gregory P. Smithb6e8c7e2010-02-27 07:22:22[diff] [blame]561 exec_func = execve
Guido van Rossum61de0ac1997-12-05 21:24:30[diff] [blame]562 argrest = (args, env)
563 else:
Gregory P. Smithb6e8c7e2010-02-27 07:22:22[diff] [blame]564 exec_func = execv
Guido van Rossum61de0ac1997-12-05 21:24:30[diff] [blame]565 argrest = (args,)
566 env = environ
Guido van Rossumaed51d82002-08-05 16:13:24[diff] [blame]567
Guido van Rossum61de0ac1997-12-05 21:24:30[diff] [blame]568 head, tail = path.split(file)
569 if head:
Gregory P. Smithb6e8c7e2010-02-27 07:22:22[diff] [blame]570 exec_func(file, *argrest)
Guido van Rossum61de0ac1997-12-05 21:24:30[diff] [blame]571 return
Guido van Rossume7ba4952007-06-06 23:52:48[diff] [blame]572 last_exc = saved_exc = None
Guido van Rossum683c0fe2002-09-03 16:36:17[diff] [blame]573 saved_tb = None
Victor Stinnerb745a742010-05-18 17:17:23[diff] [blame]574 path_list = get_exec_path(env)
575 if name != 'nt':
576 file = fsencode(file)
577 path_list = map(fsencode, path_list)
578 for dir in path_list:
Guido van Rossum61de0ac1997-12-05 21:24:30[diff] [blame]579 fullname = path.join(dir, file)
580 try:
Gregory P. Smithb6e8c7e2010-02-27 07:22:22[diff] [blame]581 exec_func(fullname, *argrest)
Guido van Rossumb940e112007-01-10 16:19:56[diff] [blame]582 except error as e:
Guido van Rossume7ba4952007-06-06 23:52:48[diff] [blame]583 last_exc = e
Guido van Rossum683c0fe2002-09-03 16:36:17[diff] [blame]584 tb = sys.exc_info()[2]
Christian Heimes45f9af32007-11-27 21:50:00[diff] [blame]585 if (e.errno != errno.ENOENT and e.errno != errno.ENOTDIR
Guido van Rossum683c0fe2002-09-03 16:36:17[diff] [blame]586 and saved_exc is None):
587 saved_exc = e
588 saved_tb = tb
589 if saved_exc:
Benjamin Peterson4b068192009-02-20 03:19:25[diff] [blame]590 raise saved_exc.with_traceback(saved_tb)
591 raise last_exc.with_traceback(tb)
Guido van Rossumd74fb6b2001-03-02 06:43:49[diff] [blame]592
Guido van Rossumcd16bf62007-06-13 18:07:49[diff] [blame]593
Gregory P. Smithb6e8c7e2010-02-27 07:22:22[diff] [blame]594def get_exec_path(env=None):
595 """Returns the sequence of directories that will be searched for the
596 named executable (similar to a shell) when launching a process.
597
598 *env* must be an environment variable dict or None. If *env* is None,
599 os.environ will be used.
600 """
Victor Stinner273b7662010-11-06 12:59:33[diff] [blame]601 # Use a local import instead of a global import to limit the number of
602 # modules loaded at startup: the os module is always loaded at startup by
603 # Python. It may also avoid a bootstrap issue.
Victor Stinner6f35eda2010-10-29 00:38:58[diff] [blame]604 import warnings
605
Gregory P. Smithb6e8c7e2010-02-27 07:22:22[diff] [blame]606 if env is None:
607 env = environ
Victor Stinnerb745a742010-05-18 17:17:23[diff] [blame]608
Victor Stinnerbb4f2182010-11-07 15:43:39[diff] [blame]609 # {b'PATH': ...}.get('PATH') and {'PATH': ...}.get(b'PATH') emit a
610 # BytesWarning when using python -b or python -bb: ignore the warning
Victor Stinner273b7662010-11-06 12:59:33[diff] [blame]611 with warnings.catch_warnings():
612 warnings.simplefilter("ignore", BytesWarning)
Victor Stinnerb745a742010-05-18 17:17:23[diff] [blame]613
Victor Stinnerb745a742010-05-18 17:17:23[diff] [blame]614 try:
Victor Stinner273b7662010-11-06 12:59:33[diff] [blame]615 path_list = env.get('PATH')
616 except TypeError:
617 path_list = None
Victor Stinnerb745a742010-05-18 17:17:23[diff] [blame]618
Victor Stinner273b7662010-11-06 12:59:33[diff] [blame]619 if supports_bytes_environ:
620 try:
621 path_listb = env[b'PATH']
622 except (KeyError, TypeError):
623 pass
624 else:
625 if path_list is not None:
626 raise ValueError(
627 "env cannot contain 'PATH' and b'PATH' keys")
628 path_list = path_listb
629
630 if path_list is not None and isinstance(path_list, bytes):
631 path_list = fsdecode(path_list)
Victor Stinnerb745a742010-05-18 17:17:23[diff] [blame]632
633 if path_list is None:
634 path_list = defpath
635 return path_list.split(pathsep)
Gregory P. Smithb6e8c7e2010-02-27 07:22:22[diff] [blame]636
637
Skip Montanaro289bc052007-08-17 02:30:27[diff] [blame]638# Change environ to automatically call putenv(), unsetenv if they exist.
Raymond Hettinger158c9c22011-02-22 00:41:50[diff] [blame]639from collections.abc import MutableMapping
Skip Montanaro289bc052007-08-17 02:30:27[diff] [blame]640
641class _Environ(MutableMapping):
Victor Stinner84ae1182010-05-06 22:05:07[diff] [blame]642 def __init__(self, data, encodekey, decodekey, encodevalue, decodevalue, putenv, unsetenv):
643 self.encodekey = encodekey
644 self.decodekey = decodekey
645 self.encodevalue = encodevalue
646 self.decodevalue = decodevalue
Skip Montanaro289bc052007-08-17 02:30:27[diff] [blame]647 self.putenv = putenv
648 self.unsetenv = unsetenv
Victor Stinner3d75d0c2010-09-10 22:18:16[diff] [blame]649 self._data = data
Ezio Melotti19e4acf2010-02-22 15:59:01[diff] [blame]650
Skip Montanaro289bc052007-08-17 02:30:27[diff] [blame]651 def __getitem__(self, key):
Victor Stinner6d101392013-04-14 14:35:04[diff] [blame]652 try:
653 value = self._data[self.encodekey(key)]
654 except KeyError:
655 # raise KeyError with the original key value
Victor Stinner0c2dd0c2013-08-23 17:19:15[diff] [blame]656 raise KeyError(key) from None
Victor Stinner84ae1182010-05-06 22:05:07[diff] [blame]657 return self.decodevalue(value)
Ezio Melotti19e4acf2010-02-22 15:59:01[diff] [blame]658
Skip Montanaro289bc052007-08-17 02:30:27[diff] [blame]659 def __setitem__(self, key, value):
Victor Stinner84ae1182010-05-06 22:05:07[diff] [blame]660 key = self.encodekey(key)
661 value = self.encodevalue(value)
Skip Montanaro289bc052007-08-17 02:30:27[diff] [blame]662 self.putenv(key, value)
Victor Stinner3d75d0c2010-09-10 22:18:16[diff] [blame]663 self._data[key] = value
Ezio Melotti19e4acf2010-02-22 15:59:01[diff] [blame]664
Skip Montanaro289bc052007-08-17 02:30:27[diff] [blame]665 def __delitem__(self, key):
Victor Stinner6d101392013-04-14 14:35:04[diff] [blame]666 encodedkey = self.encodekey(key)
667 self.unsetenv(encodedkey)
668 try:
669 del self._data[encodedkey]
670 except KeyError:
671 # raise KeyError with the original key value
Victor Stinner0c2dd0c2013-08-23 17:19:15[diff] [blame]672 raise KeyError(key) from None
Ezio Melotti19e4acf2010-02-22 15:59:01[diff] [blame]673
Skip Montanaro289bc052007-08-17 02:30:27[diff] [blame]674 def __iter__(self):
Victor Stinner3d75d0c2010-09-10 22:18:16[diff] [blame]675 for key in self._data:
Victor Stinner84ae1182010-05-06 22:05:07[diff] [blame]676 yield self.decodekey(key)
Ezio Melotti19e4acf2010-02-22 15:59:01[diff] [blame]677
Skip Montanaro289bc052007-08-17 02:30:27[diff] [blame]678 def __len__(self):
Victor Stinner3d75d0c2010-09-10 22:18:16[diff] [blame]679 return len(self._data)
Ezio Melotti19e4acf2010-02-22 15:59:01[diff] [blame]680
681 def __repr__(self):
Victor Stinnerbed71172010-07-28 21:25:42[diff] [blame]682 return 'environ({{{}}})'.format(', '.join(
Victor Stinnerd73c1a32010-07-28 21:23:23[diff] [blame]683 ('{!r}: {!r}'.format(self.decodekey(key), self.decodevalue(value))
Victor Stinner3d75d0c2010-09-10 22:18:16[diff] [blame]684 for key, value in self._data.items())))
Ezio Melotti19e4acf2010-02-22 15:59:01[diff] [blame]685
Skip Montanaro289bc052007-08-17 02:30:27[diff] [blame]686 def copy(self):
687 return dict(self)
Ezio Melotti19e4acf2010-02-22 15:59:01[diff] [blame]688
Skip Montanaro289bc052007-08-17 02:30:27[diff] [blame]689 def setdefault(self, key, value):
690 if key not in self:
691 self[key] = value
692 return self[key]
693
694try:
695 _putenv = putenv
696except NameError:
697 _putenv = lambda key, value: None
Martin v. Löwisa90f4382001-03-07 09:05:45[diff] [blame]698else:
Skip Montanaro289bc052007-08-17 02:30:27[diff] [blame]699 __all__.append("putenv")
Guido van Rossum3b8e20d1996-07-24 00:55:17[diff] [blame]700
Skip Montanaro289bc052007-08-17 02:30:27[diff] [blame]701try:
702 _unsetenv = unsetenv
703except NameError:
704 _unsetenv = lambda key: _putenv(key, "")
705else:
706 __all__.append("unsetenv")
Guido van Rossumc524d952001-10-19 01:31:59[diff] [blame]707
Victor Stinner84ae1182010-05-06 22:05:07[diff] [blame]708def _createenviron():
709 if name in ('os2', 'nt'):
710 # Where Env Var Names Must Be UPPERCASE
711 def check_str(value):
712 if not isinstance(value, str):
713 raise TypeError("str expected, not %s" % type(value).__name__)
714 return value
715 encode = check_str
716 decode = str
717 def encodekey(key):
718 return encode(key).upper()
719 data = {}
720 for key, value in environ.items():
721 data[encodekey(key)] = value
722 else:
723 # Where Env Var Names Can Be Mixed Case
Victor Stinnerdf6d6cb2010-10-24 20:32:26[diff] [blame]724 encoding = sys.getfilesystemencoding()
Victor Stinner84ae1182010-05-06 22:05:07[diff] [blame]725 def encode(value):
726 if not isinstance(value, str):
727 raise TypeError("str expected, not %s" % type(value).__name__)
Victor Stinnerdf6d6cb2010-10-24 20:32:26[diff] [blame]728 return value.encode(encoding, 'surrogateescape')
Victor Stinner84ae1182010-05-06 22:05:07[diff] [blame]729 def decode(value):
Victor Stinnerdf6d6cb2010-10-24 20:32:26[diff] [blame]730 return value.decode(encoding, 'surrogateescape')
Victor Stinner84ae1182010-05-06 22:05:07[diff] [blame]731 encodekey = encode
732 data = environ
733 return _Environ(data,
734 encodekey, decode,
735 encode, decode,
736 _putenv, _unsetenv)
Guido van Rossumc524d952001-10-19 01:31:59[diff] [blame]737
Victor Stinner84ae1182010-05-06 22:05:07[diff] [blame]738# unicode environ
739environ = _createenviron()
740del _createenviron
Guido van Rossum61de0ac1997-12-05 21:24:30[diff] [blame]741
Guido van Rossum5a2ca931999-11-02 13:27:32[diff] [blame]742
Jack Jansenb11ce9b2003-01-08 16:33:40[diff] [blame]743def getenv(key, default=None):
Tim Peters2c60f7a2003-01-29 03:49:43[diff] [blame]744 """Get an environment variable, return None if it doesn't exist.
Victor Stinner84ae1182010-05-06 22:05:07[diff] [blame]745 The optional second argument can specify an alternate default.
746 key, default and the result are str."""
Tim Peters2c60f7a2003-01-29 03:49:43[diff] [blame]747 return environ.get(key, default)
Guido van Rossum5a2ca931999-11-02 13:27:32[diff] [blame]748
Victor Stinnerb745a742010-05-18 17:17:23[diff] [blame]749supports_bytes_environ = name not in ('os2', 'nt')
750__all__.extend(("getenv", "supports_bytes_environ"))
751
752if supports_bytes_environ:
Victor Stinner84ae1182010-05-06 22:05:07[diff] [blame]753 def _check_bytes(value):
754 if not isinstance(value, bytes):
755 raise TypeError("bytes expected, not %s" % type(value).__name__)
756 return value
757
758 # bytes environ
Victor Stinner3d75d0c2010-09-10 22:18:16[diff] [blame]759 environb = _Environ(environ._data,
Victor Stinner84ae1182010-05-06 22:05:07[diff] [blame]760 _check_bytes, bytes,
761 _check_bytes, bytes,
762 _putenv, _unsetenv)
763 del _check_bytes
764
765 def getenvb(key, default=None):
766 """Get an environment variable, return None if it doesn't exist.
767 The optional second argument can specify an alternate default.
768 key, default and the result are bytes."""
769 return environb.get(key, default)
Victor Stinner70120e22010-07-29 17:19:38[diff] [blame]770
771 __all__.extend(("environb", "getenvb"))
Victor Stinner84ae1182010-05-06 22:05:07[diff] [blame]772
Victor Stinnerdf6d6cb2010-10-24 20:32:26[diff] [blame]773def _fscodec():
774 encoding = sys.getfilesystemencoding()
775 if encoding == 'mbcs':
Victor Stinnere882aac2010-10-24 21:12:26[diff] [blame]776 errors = 'strict'
Victor Stinner313a1202010-06-11 23:56:51[diff] [blame]777 else:
Victor Stinnerdf6d6cb2010-10-24 20:32:26[diff] [blame]778 errors = 'surrogateescape'
Victor Stinnere8d51452010-08-19 01:05:19[diff] [blame]779
Victor Stinnerdf6d6cb2010-10-24 20:32:26[diff] [blame]780 def fsencode(filename):
781 """
782 Encode filename to the filesystem encoding with 'surrogateescape' error
783 handler, return bytes unchanged. On Windows, use 'strict' error handler if
784 the file system encoding is 'mbcs' (which is the default encoding).
785 """
786 if isinstance(filename, bytes):
787 return filename
788 elif isinstance(filename, str):
789 return filename.encode(encoding, errors)
Victor Stinnere8d51452010-08-19 01:05:19[diff] [blame]790 else:
Victor Stinnerdf6d6cb2010-10-24 20:32:26[diff] [blame]791 raise TypeError("expect bytes or str, not %s" % type(filename).__name__)
792
793 def fsdecode(filename):
794 """
795 Decode filename from the filesystem encoding with 'surrogateescape' error
796 handler, return str unchanged. On Windows, use 'strict' error handler if
797 the file system encoding is 'mbcs' (which is the default encoding).
798 """
799 if isinstance(filename, str):
800 return filename
801 elif isinstance(filename, bytes):
802 return filename.decode(encoding, errors)
803 else:
804 raise TypeError("expect bytes or str, not %s" % type(filename).__name__)
805
806 return fsencode, fsdecode
807
808fsencode, fsdecode = _fscodec()
809del _fscodec
Victor Stinner449c4662010-05-08 11:10:09[diff] [blame]810
Guido van Rossum5a2ca931999-11-02 13:27:32[diff] [blame]811# Supply spawn*() (probably only for Unix)
812if _exists("fork") and not _exists("spawnv") and _exists("execv"):
813
814 P_WAIT = 0
815 P_NOWAIT = P_NOWAITO = 1
816
Petri Lehtinen3bc37f22012-05-23 18:36:16[diff] [blame]817 __all__.extend(["P_WAIT", "P_NOWAIT", "P_NOWAITO"])
818
Guido van Rossum5a2ca931999-11-02 13:27:32[diff] [blame]819 # XXX Should we support P_DETACH? I suppose it could fork()**2
820 # and close the std I/O streams. Also, P_OVERLAY is the same
821 # as execv*()?
822
823 def _spawnvef(mode, file, args, env, func):
824 # Internal helper; func is the exec*() function to use
825 pid = fork()
826 if not pid:
827 # Child
828 try:
829 if env is None:
830 func(file, args)
831 else:
832 func(file, args, env)
833 except:
834 _exit(127)
835 else:
836 # Parent
837 if mode == P_NOWAIT:
838 return pid # Caller is responsible for waiting!
839 while 1:
840 wpid, sts = waitpid(pid, 0)
841 if WIFSTOPPED(sts):
842 continue
843 elif WIFSIGNALED(sts):
844 return -WTERMSIG(sts)
845 elif WIFEXITED(sts):
846 return WEXITSTATUS(sts)
847 else:
Collin Winter828f04a2007-08-31 00:04:24[diff] [blame]848 raise error("Not stopped, signaled or exited???")
Guido van Rossum5a2ca931999-11-02 13:27:32[diff] [blame]849
850 def spawnv(mode, file, args):
Guido van Rossume0cd2912000-04-21 18:35:36[diff] [blame]851 """spawnv(mode, file, args) -> integer
852
853Execute file with arguments from args in a subprocess.
854If mode == P_NOWAIT return the pid of the process.
855If mode == P_WAIT return the process's exit code if it exits normally;
Tim Peters2344fae2001-01-15 00:50:52[diff] [blame]856otherwise return -SIG, where SIG is the signal that killed it. """
Guido van Rossum5a2ca931999-11-02 13:27:32[diff] [blame]857 return _spawnvef(mode, file, args, None, execv)
858
859 def spawnve(mode, file, args, env):
Guido van Rossume0cd2912000-04-21 18:35:36[diff] [blame]860 """spawnve(mode, file, args, env) -> integer
861
862Execute file with arguments from args in a subprocess with the
863specified environment.
864If mode == P_NOWAIT return the pid of the process.
865If mode == P_WAIT return the process's exit code if it exits normally;
866otherwise return -SIG, where SIG is the signal that killed it. """
Guido van Rossum5a2ca931999-11-02 13:27:32[diff] [blame]867 return _spawnvef(mode, file, args, env, execve)
868
Guido van Rossumdd7cbbf1999-11-02 20:44:07[diff] [blame]869 # Note: spawnvp[e] is't currently supported on Windows
870
871 def spawnvp(mode, file, args):
Guido van Rossume0cd2912000-04-21 18:35:36[diff] [blame]872 """spawnvp(mode, file, args) -> integer
873
874Execute file (which is looked for along $PATH) with arguments from
875args in a subprocess.
876If mode == P_NOWAIT return the pid of the process.
877If mode == P_WAIT return the process's exit code if it exits normally;
878otherwise return -SIG, where SIG is the signal that killed it. """
Guido van Rossumdd7cbbf1999-11-02 20:44:07[diff] [blame]879 return _spawnvef(mode, file, args, None, execvp)
880
881 def spawnvpe(mode, file, args, env):
Guido van Rossume0cd2912000-04-21 18:35:36[diff] [blame]882 """spawnvpe(mode, file, args, env) -> integer
883
884Execute file (which is looked for along $PATH) with arguments from
885args in a subprocess with the supplied environment.
886If mode == P_NOWAIT return the pid of the process.
887If mode == P_WAIT return the process's exit code if it exits normally;
888otherwise return -SIG, where SIG is the signal that killed it. """
Guido van Rossumdd7cbbf1999-11-02 20:44:07[diff] [blame]889 return _spawnvef(mode, file, args, env, execvpe)
890
891if _exists("spawnv"):
892 # These aren't supplied by the basic Windows code
893 # but can be easily implemented in Python
Guido van Rossum5a2ca931999-11-02 13:27:32[diff] [blame]894
895 def spawnl(mode, file, *args):
Guido van Rossume0cd2912000-04-21 18:35:36[diff] [blame]896 """spawnl(mode, file, *args) -> integer
897
898Execute file with arguments from args in a subprocess.
899If mode == P_NOWAIT return the pid of the process.
900If mode == P_WAIT return the process's exit code if it exits normally;
901otherwise return -SIG, where SIG is the signal that killed it. """
Guido van Rossum5a2ca931999-11-02 13:27:32[diff] [blame]902 return spawnv(mode, file, args)
903
904 def spawnle(mode, file, *args):
Guido van Rossume0cd2912000-04-21 18:35:36[diff] [blame]905 """spawnle(mode, file, *args, env) -> integer
906
907Execute file with arguments from args in a subprocess with the
908supplied environment.
909If mode == P_NOWAIT return the pid of the process.
910If mode == P_WAIT return the process's exit code if it exits normally;
911otherwise return -SIG, where SIG is the signal that killed it. """
Guido van Rossum5a2ca931999-11-02 13:27:32[diff] [blame]912 env = args[-1]
913 return spawnve(mode, file, args[:-1], env)
914
Andrew MacIntyre69e18c92004-04-04 07:11:43[diff] [blame]915
916 __all__.extend(["spawnv", "spawnve", "spawnl", "spawnle",])
917
918
Guido van Rossumdd7cbbf1999-11-02 20:44:07[diff] [blame]919if _exists("spawnvp"):
920 # At the moment, Windows doesn't implement spawnvp[e],
921 # so it won't have spawnlp[e] either.
Guido van Rossum5a2ca931999-11-02 13:27:32[diff] [blame]922 def spawnlp(mode, file, *args):
Neal Norwitzb7f68102003-07-02 02:49:33[diff] [blame]923 """spawnlp(mode, file, *args) -> integer
Guido van Rossume0cd2912000-04-21 18:35:36[diff] [blame]924
925Execute file (which is looked for along $PATH) with arguments from
926args in a subprocess with the supplied environment.
927If mode == P_NOWAIT return the pid of the process.
928If mode == P_WAIT return the process's exit code if it exits normally;
929otherwise return -SIG, where SIG is the signal that killed it. """
Guido van Rossum5a2ca931999-11-02 13:27:32[diff] [blame]930 return spawnvp(mode, file, args)
931
932 def spawnlpe(mode, file, *args):
Guido van Rossume0cd2912000-04-21 18:35:36[diff] [blame]933 """spawnlpe(mode, file, *args, env) -> integer
934
935Execute file (which is looked for along $PATH) with arguments from
936args in a subprocess with the supplied environment.
937If mode == P_NOWAIT return the pid of the process.
938If mode == P_WAIT return the process's exit code if it exits normally;
939otherwise return -SIG, where SIG is the signal that killed it. """
Guido van Rossum5a2ca931999-11-02 13:27:32[diff] [blame]940 env = args[-1]
941 return spawnvpe(mode, file, args[:-1], env)
Guido van Rossume0cd2912000-04-21 18:35:36[diff] [blame]942
943
Andrew MacIntyre69e18c92004-04-04 07:11:43[diff] [blame]944 __all__.extend(["spawnvp", "spawnvpe", "spawnlp", "spawnlpe",])
Skip Montanaro269b83b2001-02-06 01:07:02[diff] [blame]945
Alexandre Vassalottif7fa63d2008-05-11 08:55:36[diff] [blame]946import copyreg as _copyreg
Michael W. Hudson0e025302002-03-06 17:11:18[diff] [blame]947
948def _make_stat_result(tup, dict):
949 return stat_result(tup, dict)
950
951def _pickle_stat_result(sr):
952 (type, args) = sr.__reduce__()
953 return (_make_stat_result, args)
954
Michael W. Hudsonce00b732002-03-15 10:18:58[diff] [blame]955try:
Alexandre Vassalottif7fa63d2008-05-11 08:55:36[diff] [blame]956 _copyreg.pickle(stat_result, _pickle_stat_result, _make_stat_result)
Michael W. Hudsonce00b732002-03-15 10:18:58[diff] [blame]957except NameError: # stat_result may not exist
958 pass
Michael W. Hudson0e025302002-03-06 17:11:18[diff] [blame]959
960def _make_statvfs_result(tup, dict):
961 return statvfs_result(tup, dict)
962
963def _pickle_statvfs_result(sr):
964 (type, args) = sr.__reduce__()
965 return (_make_statvfs_result, args)
966
Michael W. Hudsonce00b732002-03-15 10:18:58[diff] [blame]967try:
Alexandre Vassalottif7fa63d2008-05-11 08:55:36[diff] [blame]968 _copyreg.pickle(statvfs_result, _pickle_statvfs_result,
Michael W. Hudsonce00b732002-03-15 10:18:58[diff] [blame]969 _make_statvfs_result)
Michael W. Hudsone5363b72002-03-15 10:21:59[diff] [blame]970except NameError: # statvfs_result may not exist
Michael W. Hudsonce00b732002-03-15 10:18:58[diff] [blame]971 pass
Martin v. Löwisdc3883f2004-08-29 15:46:35[diff] [blame]972
Guido van Rossumc2f93dc2007-05-24 00:50:02[diff] [blame]973# Supply os.popen()
Antoine Pitrou877766d2011-03-19 16:00:37[diff] [blame]974def popen(cmd, mode="r", buffering=-1):
Guido van Rossum3172c5d2007-10-16 18:12:55[diff] [blame]975 if not isinstance(cmd, str):
Guido van Rossumc2f93dc2007-05-24 00:50:02[diff] [blame]976 raise TypeError("invalid cmd type (%s, expected string)" % type(cmd))
977 if mode not in ("r", "w"):
978 raise ValueError("invalid mode %r" % mode)
Benjamin Petersonb29614e2012-10-09 15:16:03[diff] [blame]979 if buffering == 0 or buffering is None:
Antoine Pitrou877766d2011-03-19 16:00:37[diff] [blame]980 raise ValueError("popen() does not support unbuffered streams")
Guido van Rossumc2f93dc2007-05-24 00:50:02[diff] [blame]981 import subprocess, io
982 if mode == "r":
983 proc = subprocess.Popen(cmd,
984 shell=True,
985 stdout=subprocess.PIPE,
986 bufsize=buffering)
987 return _wrap_close(io.TextIOWrapper(proc.stdout), proc)
988 else:
989 proc = subprocess.Popen(cmd,
990 shell=True,
991 stdin=subprocess.PIPE,
992 bufsize=buffering)
993 return _wrap_close(io.TextIOWrapper(proc.stdin), proc)
994
995# Helper for popen() -- a proxy for a file whose close waits for the process
996class _wrap_close:
997 def __init__(self, stream, proc):
998 self._stream = stream
999 self._proc = proc
1000 def close(self):
1001 self._stream.close()
Amaury Forgeot d'Arc97e5f282009-07-11 09:35:13[diff] [blame]1002 returncode = self._proc.wait()
1003 if returncode == 0:
1004 return None
1005 if name == 'nt':
1006 return returncode
1007 else:
1008 return returncode << 8 # Shift left to match old behavior
Antoine Pitrouac625352009-12-09 00:01:27[diff] [blame]1009 def __enter__(self):
1010 return self
1011 def __exit__(self, *args):
1012 self.close()
Guido van Rossumc2f93dc2007-05-24 00:50:02[diff] [blame]1013 def __getattr__(self, name):
1014 return getattr(self._stream, name)
Thomas Heller476157b2007-09-04 11:27:47[diff] [blame]1015 def __iter__(self):
1016 return iter(self._stream)
Guido van Rossumc2f93dc2007-05-24 00:50:02[diff] [blame]1017
Amaury Forgeot d'Arcbdbddf82008-08-01 00:06:49[diff] [blame]1018# Supply os.fdopen()
1019def fdopen(fd, *args, **kwargs):
Guido van Rossumc2f93dc2007-05-24 00:50:02[diff] [blame]1020 if not isinstance(fd, int):
1021 raise TypeError("invalid fd type (%s, expected integer)" % type(fd))
1022 import io
Amaury Forgeot d'Arcbdbddf82008-08-01 00:06:49[diff] [blame]1023 return io.open(fd, *args, **kwargs)