Python code coverage for Lib/posixpath.py

#	count	content
1	n/a	"""Common operations on Posix pathnames.
2	n/a
3	n/a	Instead of importing this module directly, import os and refer to
4	n/a	this module as os.path. The "os.path" name is an alias for this
5	n/a	module on Posix systems; on other systems (e.g. Mac, Windows),
6	n/a	os.path provides the same operations in a manner specific to that
7	n/a	platform, and is an alias to another module (e.g. macpath, ntpath).
8	n/a
9	n/a	Some of this can actually be useful on non-Posix systems too, e.g.
10	n/a	for manipulation of the pathname component of URLs.
11	n/a	"""
12	n/a
13	n/a	import os
14	n/a	import sys
15	n/a	import stat
16	n/a	import genericpath
17	n/a	from genericpath import *
18	n/a
19	n/a	__all__ = ["normcase","isabs","join","splitdrive","split","splitext",
20	n/a	"basename","dirname","commonprefix","getsize","getmtime",
21	n/a	"getatime","getctime","islink","exists","lexists","isdir","isfile",
22	n/a	"ismount", "expanduser","expandvars","normpath","abspath",
23	n/a	"samefile","sameopenfile","samestat",
24	n/a	"curdir","pardir","sep","pathsep","defpath","altsep","extsep",
25	n/a	"devnull","realpath","supports_unicode_filenames","relpath",
26	n/a	"commonpath"]
27	n/a
28	n/a	# Strings representing various path-related bits and pieces.
29	n/a	# These are primarily for export; internally, they are hardcoded.
30	n/a	curdir = '.'
31	n/a	pardir = '..'
32	n/a	extsep = '.'
33	n/a	sep = '/'
34	n/a	pathsep = ':'
35	n/a	defpath = ':/bin:/usr/bin'
36	n/a	altsep = None
37	n/a	devnull = '/dev/null'
38	n/a
39	n/a	def _get_sep(path):
40	n/a	if isinstance(path, bytes):
41	n/a	return b'/'
42	n/a	else:
43	n/a	return '/'
44	n/a
45	n/a	# Normalize the case of a pathname. Trivial in Posix, string.lower on Mac.
46	n/a	# On MS-DOS this may also turn slashes into backslashes; however, other
47	n/a	# normalizations (such as optimizing '../' away) are not allowed
48	n/a	# (another function should be defined to do that).
49	n/a
50	n/a	def normcase(s):
51	n/a	"""Normalize case of pathname. Has no effect under Posix"""
52	n/a	s = os.fspath(s)
53	n/a	if not isinstance(s, (bytes, str)):
54	n/a	raise TypeError("normcase() argument must be str or bytes, "
55	n/a	"not '{}'".format(s.__class__.__name__))
56	n/a	return s
57	n/a
58	n/a
59	n/a	# Return whether a path is absolute.
60	n/a	# Trivial in Posix, harder on the Mac or MS-DOS.
61	n/a
62	n/a	def isabs(s):
63	n/a	"""Test whether a path is absolute"""
64	n/a	s = os.fspath(s)
65	n/a	sep = _get_sep(s)
66	n/a	return s.startswith(sep)
67	n/a
68	n/a
69	n/a	# Join pathnames.
70	n/a	# Ignore the previous parts if a part is absolute.
71	n/a	# Insert a '/' unless the first part is empty or already ends in '/'.
72	n/a
73	n/a	def join(a, *p):
74	n/a	"""Join two or more pathname components, inserting '/' as needed.
75	n/a	If any component is an absolute path, all previous path components
76	n/a	will be discarded. An empty last part will result in a path that
77	n/a	ends with a separator."""
78	n/a	a = os.fspath(a)
79	n/a	sep = _get_sep(a)
80	n/a	path = a
81	n/a	try:
82	n/a	if not p:
83	n/a	path[:0] + sep #23780: Ensure compatible data type even if p is null.
84	n/a	for b in map(os.fspath, p):
85	n/a	if b.startswith(sep):
86	n/a	path = b
87	n/a	elif not path or path.endswith(sep):
88	n/a	path += b
89	n/a	else:
90	n/a	path += sep + b
91	n/a	except (TypeError, AttributeError, BytesWarning):
92	n/a	genericpath._check_arg_types('join', a, *p)
93	n/a	raise
94	n/a	return path
95	n/a
96	n/a
97	n/a	# Split a path in head (everything up to the last '/') and tail (the
98	n/a	# rest). If the path ends in '/', tail will be empty. If there is no
99	n/a	# '/' in the path, head will be empty.
100	n/a	# Trailing '/'es are stripped from head unless it is the root.
101	n/a
102	n/a	def split(p):
103	n/a	"""Split a pathname. Returns tuple "(head, tail)" where "tail" is
104	n/a	everything after the final slash. Either part may be empty."""
105	n/a	p = os.fspath(p)
106	n/a	sep = _get_sep(p)
107	n/a	i = p.rfind(sep) + 1
108	n/a	head, tail = p[:i], p[i:]
109	n/a	if head and head != sep*len(head):
110	n/a	head = head.rstrip(sep)
111	n/a	return head, tail
112	n/a
113	n/a
114	n/a	# Split a path in root and extension.
115	n/a	# The extension is everything starting at the last dot in the last
116	n/a	# pathname component; the root is everything before that.
117	n/a	# It is always true that root + ext == p.
118	n/a
119	n/a	def splitext(p):
120	n/a	p = os.fspath(p)
121	n/a	if isinstance(p, bytes):
122	n/a	sep = b'/'
123	n/a	extsep = b'.'
124	n/a	else:
125	n/a	sep = '/'
126	n/a	extsep = '.'
127	n/a	return genericpath._splitext(p, sep, None, extsep)
128	n/a	splitext.__doc__ = genericpath._splitext.__doc__
129	n/a
130	n/a	# Split a pathname into a drive specification and the rest of the
131	n/a	# path. Useful on DOS/Windows/NT; on Unix, the drive is always empty.
132	n/a
133	n/a	def splitdrive(p):
134	n/a	"""Split a pathname into drive and path. On Posix, drive is always
135	n/a	empty."""
136	n/a	p = os.fspath(p)
137	n/a	return p[:0], p
138	n/a
139	n/a
140	n/a	# Return the tail (basename) part of a path, same as split(path)[1].
141	n/a
142	n/a	def basename(p):
143	n/a	"""Returns the final component of a pathname"""
144	n/a	p = os.fspath(p)
145	n/a	sep = _get_sep(p)
146	n/a	i = p.rfind(sep) + 1
147	n/a	return p[i:]
148	n/a
149	n/a
150	n/a	# Return the head (dirname) part of a path, same as split(path)[0].
151	n/a
152	n/a	def dirname(p):
153	n/a	"""Returns the directory component of a pathname"""
154	n/a	p = os.fspath(p)
155	n/a	sep = _get_sep(p)
156	n/a	i = p.rfind(sep) + 1
157	n/a	head = p[:i]
158	n/a	if head and head != sep*len(head):
159	n/a	head = head.rstrip(sep)
160	n/a	return head
161	n/a
162	n/a
163	n/a	# Is a path a symbolic link?
164	n/a	# This will always return false on systems where os.lstat doesn't exist.
165	n/a
166	n/a	def islink(path):
167	n/a	"""Test whether a path is a symbolic link"""
168	n/a	try:
169	n/a	st = os.lstat(path)
170	n/a	except (OSError, AttributeError):
171	n/a	return False
172	n/a	return stat.S_ISLNK(st.st_mode)
173	n/a
174	n/a	# Being true for dangling symbolic links is also useful.
175	n/a
176	n/a	def lexists(path):
177	n/a	"""Test whether a path exists. Returns True for broken symbolic links"""
178	n/a	try:
179	n/a	os.lstat(path)
180	n/a	except OSError:
181	n/a	return False
182	n/a	return True
183	n/a
184	n/a
185	n/a	# Is a path a mount point?
186	n/a	# (Does this work for all UNIXes? Is it even guaranteed to work by Posix?)
187	n/a
188	n/a	def ismount(path):
189	n/a	"""Test whether a path is a mount point"""
190	n/a	try:
191	n/a	s1 = os.lstat(path)
192	n/a	except OSError:
193	n/a	# It doesn't exist -- so not a mount point. :-)
194	n/a	return False
195	n/a	else:
196	n/a	# A symlink can never be a mount point
197	n/a	if stat.S_ISLNK(s1.st_mode):
198	n/a	return False
199	n/a
200	n/a	if isinstance(path, bytes):
201	n/a	parent = join(path, b'..')
202	n/a	else:
203	n/a	parent = join(path, '..')
204	n/a	parent = realpath(parent)
205	n/a	try:
206	n/a	s2 = os.lstat(parent)
207	n/a	except OSError:
208	n/a	return False
209	n/a
210	n/a	dev1 = s1.st_dev
211	n/a	dev2 = s2.st_dev
212	n/a	if dev1 != dev2:
213	n/a	return True # path/.. on a different device as path
214	n/a	ino1 = s1.st_ino
215	n/a	ino2 = s2.st_ino
216	n/a	if ino1 == ino2:
217	n/a	return True # path/.. is the same i-node as path
218	n/a	return False
219	n/a
220	n/a
221	n/a	# Expand paths beginning with '~' or '~user'.
222	n/a	# '~' means $HOME; '~user' means that user's home directory.
223	n/a	# If the path doesn't begin with '~', or if the user or $HOME is unknown,
224	n/a	# the path is returned unchanged (leaving error reporting to whatever
225	n/a	# function is called with the expanded path as argument).
226	n/a	# See also module 'glob' for expansion of *, ? and [...] in pathnames.
227	n/a	# (A function should also be defined to do full *sh-style environment
228	n/a	# variable expansion.)
229	n/a
230	n/a	def expanduser(path):
231	n/a	"""Expand ~ and ~user constructions. If user or $HOME is unknown,
232	n/a	do nothing."""
233	n/a	path = os.fspath(path)
234	n/a	if isinstance(path, bytes):
235	n/a	tilde = b'~'
236	n/a	else:
237	n/a	tilde = '~'
238	n/a	if not path.startswith(tilde):
239	n/a	return path
240	n/a	sep = _get_sep(path)
241	n/a	i = path.find(sep, 1)
242	n/a	if i < 0:
243	n/a	i = len(path)
244	n/a	if i == 1:
245	n/a	if 'HOME' not in os.environ:
246	n/a	import pwd
247	n/a	userhome = pwd.getpwuid(os.getuid()).pw_dir
248	n/a	else:
249	n/a	userhome = os.environ['HOME']
250	n/a	else:
251	n/a	import pwd
252	n/a	name = path[1:i]
253	n/a	if isinstance(name, bytes):
254	n/a	name = str(name, 'ASCII')
255	n/a	try:
256	n/a	pwent = pwd.getpwnam(name)
257	n/a	except KeyError:
258	n/a	return path
259	n/a	userhome = pwent.pw_dir
260	n/a	if isinstance(path, bytes):
261	n/a	userhome = os.fsencode(userhome)
262	n/a	root = b'/'
263	n/a	else:
264	n/a	root = '/'
265	n/a	userhome = userhome.rstrip(root)
266	n/a	return (userhome + path[i:]) or root
267	n/a
268	n/a
269	n/a	# Expand paths containing shell variable substitutions.
270	n/a	# This expands the forms $variable and ${variable} only.
271	n/a	# Non-existent variables are left unchanged.
272	n/a
273	n/a	_varprog = None
274	n/a	_varprogb = None
275	n/a
276	n/a	def expandvars(path):
277	n/a	"""Expand shell variables of form $var and ${var}. Unknown variables
278	n/a	are left unchanged."""
279	n/a	path = os.fspath(path)
280	n/a	global _varprog, _varprogb
281	n/a	if isinstance(path, bytes):
282	n/a	if b'$' not in path:
283	n/a	return path
284	n/a	if not _varprogb:
285	n/a	import re
286	n/a	_varprogb = re.compile(br'\$(\w+\|\{[^}]*\})', re.ASCII)
287	n/a	search = _varprogb.search
288	n/a	start = b'{'
289	n/a	end = b'}'
290	n/a	environ = getattr(os, 'environb', None)
291	n/a	else:
292	n/a	if '$' not in path:
293	n/a	return path
294	n/a	if not _varprog:
295	n/a	import re
296	n/a	_varprog = re.compile(r'\$(\w+\|\{[^}]*\})', re.ASCII)
297	n/a	search = _varprog.search
298	n/a	start = '{'
299	n/a	end = '}'
300	n/a	environ = os.environ
301	n/a	i = 0
302	n/a	while True:
303	n/a	m = search(path, i)
304	n/a	if not m:
305	n/a	break
306	n/a	i, j = m.span(0)
307	n/a	name = m.group(1)
308	n/a	if name.startswith(start) and name.endswith(end):
309	n/a	name = name[1:-1]
310	n/a	try:
311	n/a	if environ is None:
312	n/a	value = os.fsencode(os.environ[os.fsdecode(name)])
313	n/a	else:
314	n/a	value = environ[name]
315	n/a	except KeyError:
316	n/a	i = j
317	n/a	else:
318	n/a	tail = path[j:]
319	n/a	path = path[:i] + value
320	n/a	i = len(path)
321	n/a	path += tail
322	n/a	return path
323	n/a
324	n/a
325	n/a	# Normalize a path, e.g. A//B, A/./B and A/foo/../B all become A/B.
326	n/a	# It should be understood that this may change the meaning of the path
327	n/a	# if it contains symbolic links!
328	n/a
329	n/a	def normpath(path):
330	n/a	"""Normalize path, eliminating double slashes, etc."""
331	n/a	path = os.fspath(path)
332	n/a	if isinstance(path, bytes):
333	n/a	sep = b'/'
334	n/a	empty = b''
335	n/a	dot = b'.'
336	n/a	dotdot = b'..'
337	n/a	else:
338	n/a	sep = '/'
339	n/a	empty = ''
340	n/a	dot = '.'
341	n/a	dotdot = '..'
342	n/a	if path == empty:
343	n/a	return dot
344	n/a	initial_slashes = path.startswith(sep)
345	n/a	# POSIX allows one or two initial slashes, but treats three or more
346	n/a	# as single slash.
347	n/a	if (initial_slashes and
348	n/a	path.startswith(sep2) and not path.startswith(sep3)):
349	n/a	initial_slashes = 2
350	n/a	comps = path.split(sep)
351	n/a	new_comps = []
352	n/a	for comp in comps:
353	n/a	if comp in (empty, dot):
354	n/a	continue
355	n/a	if (comp != dotdot or (not initial_slashes and not new_comps) or
356	n/a	(new_comps and new_comps[-1] == dotdot)):
357	n/a	new_comps.append(comp)
358	n/a	elif new_comps:
359	n/a	new_comps.pop()
360	n/a	comps = new_comps
361	n/a	path = sep.join(comps)
362	n/a	if initial_slashes:
363	n/a	path = sep*initial_slashes + path
364	n/a	return path or dot
365	n/a
366	n/a
367	n/a	def abspath(path):
368	n/a	"""Return an absolute path."""
369	n/a	path = os.fspath(path)
370	n/a	if not isabs(path):
371	n/a	if isinstance(path, bytes):
372	n/a	cwd = os.getcwdb()
373	n/a	else:
374	n/a	cwd = os.getcwd()
375	n/a	path = join(cwd, path)
376	n/a	return normpath(path)
377	n/a
378	n/a
379	n/a	# Return a canonical path (i.e. the absolute location of a file on the
380	n/a	# filesystem).
381	n/a
382	n/a	def realpath(filename):
383	n/a	"""Return the canonical path of the specified filename, eliminating any
384	n/a	symbolic links encountered in the path."""
385	n/a	filename = os.fspath(filename)
386	n/a	path, ok = _joinrealpath(filename[:0], filename, {})
387	n/a	return abspath(path)
388	n/a
389	n/a	# Join two paths, normalizing and eliminating any symbolic links
390	n/a	# encountered in the second path.
391	n/a	def _joinrealpath(path, rest, seen):
392	n/a	if isinstance(path, bytes):
393	n/a	sep = b'/'
394	n/a	curdir = b'.'
395	n/a	pardir = b'..'
396	n/a	else:
397	n/a	sep = '/'
398	n/a	curdir = '.'
399	n/a	pardir = '..'
400	n/a
401	n/a	if isabs(rest):
402	n/a	rest = rest[1:]
403	n/a	path = sep
404	n/a
405	n/a	while rest:
406	n/a	name, _, rest = rest.partition(sep)
407	n/a	if not name or name == curdir:
408	n/a	# current dir
409	n/a	continue
410	n/a	if name == pardir:
411	n/a	# parent dir
412	n/a	if path:
413	n/a	path, name = split(path)
414	n/a	if name == pardir:
415	n/a	path = join(path, pardir, pardir)
416	n/a	else:
417	n/a	path = pardir
418	n/a	continue
419	n/a	newpath = join(path, name)
420	n/a	if not islink(newpath):
421	n/a	path = newpath
422	n/a	continue
423	n/a	# Resolve the symbolic link
424	n/a	if newpath in seen:
425	n/a	# Already seen this path
426	n/a	path = seen[newpath]
427	n/a	if path is not None:
428	n/a	# use cached value
429	n/a	continue
430	n/a	# The symlink is not resolved, so we must have a symlink loop.
431	n/a	# Return already resolved part + rest of the path unchanged.
432	n/a	return join(newpath, rest), False
433	n/a	seen[newpath] = None # not resolved symlink
434	n/a	path, ok = _joinrealpath(path, os.readlink(newpath), seen)
435	n/a	if not ok:
436	n/a	return join(path, rest), False
437	n/a	seen[newpath] = path # resolved symlink
438	n/a
439	n/a	return path, True
440	n/a
441	n/a
442	n/a	supports_unicode_filenames = (sys.platform == 'darwin')
443	n/a
444	n/a	def relpath(path, start=None):
445	n/a	"""Return a relative version of a path"""
446	n/a
447	n/a	if not path:
448	n/a	raise ValueError("no path specified")
449	n/a
450	n/a	path = os.fspath(path)
451	n/a	if isinstance(path, bytes):
452	n/a	curdir = b'.'
453	n/a	sep = b'/'
454	n/a	pardir = b'..'
455	n/a	else:
456	n/a	curdir = '.'
457	n/a	sep = '/'
458	n/a	pardir = '..'
459	n/a
460	n/a	if start is None:
461	n/a	start = curdir
462	n/a	else:
463	n/a	start = os.fspath(start)
464	n/a
465	n/a	try:
466	n/a	start_list = [x for x in abspath(start).split(sep) if x]
467	n/a	path_list = [x for x in abspath(path).split(sep) if x]
468	n/a	# Work out how much of the filepath is shared by start and path.
469	n/a	i = len(commonprefix([start_list, path_list]))
470	n/a
471	n/a	rel_list = [pardir] * (len(start_list)-i) + path_list[i:]
472	n/a	if not rel_list:
473	n/a	return curdir
474	n/a	return join(*rel_list)
475	n/a	except (TypeError, AttributeError, BytesWarning, DeprecationWarning):
476	n/a	genericpath._check_arg_types('relpath', path, start)
477	n/a	raise
478	n/a
479	n/a
480	n/a	# Return the longest common sub-path of the sequence of paths given as input.
481	n/a	# The paths are not normalized before comparing them (this is the
482	n/a	# responsibility of the caller). Any trailing separator is stripped from the
483	n/a	# returned path.
484	n/a
485	n/a	def commonpath(paths):
486	n/a	"""Given a sequence of path names, returns the longest common sub-path."""
487	n/a
488	n/a	if not paths:
489	n/a	raise ValueError('commonpath() arg is an empty sequence')
490	n/a
491	n/a	paths = tuple(map(os.fspath, paths))
492	n/a	if isinstance(paths[0], bytes):
493	n/a	sep = b'/'
494	n/a	curdir = b'.'
495	n/a	else:
496	n/a	sep = '/'
497	n/a	curdir = '.'
498	n/a
499	n/a	try:
500	n/a	split_paths = [path.split(sep) for path in paths]
501	n/a
502	n/a	try:
503	n/a	isabs, = set(p[:1] == sep for p in paths)
504	n/a	except ValueError:
505	n/a	raise ValueError("Can't mix absolute and relative paths") from None
506	n/a
507	n/a	split_paths = [[c for c in s if c and c != curdir] for s in split_paths]
508	n/a	s1 = min(split_paths)
509	n/a	s2 = max(split_paths)
510	n/a	common = s1
511	n/a	for i, c in enumerate(s1):
512	n/a	if c != s2[i]:
513	n/a	common = s1[:i]
514	n/a	break
515	n/a
516	n/a	prefix = sep if isabs else sep[:0]
517	n/a	return prefix + sep.join(common)
518	n/a	except (TypeError, AttributeError):
519	n/a	genericpath._check_arg_types('commonpath', *paths)
520	n/a	raise