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