Python code coverage for Lib/os.py

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