4 this module as os.path.  The "os.path" name is an alias for this
6 os.path provides the same operations in a manner specific to that
7 platform, and is an alias to another module (e.g. ntpath).
9 Some of this can actually be useful on non-Posix systems too, e.g.
13 # Strings representing various path-related bits and pieces.
41 def _get_sep(path):  argument
42     if isinstance(path, bytes):
48 # On MS-DOS this may also turn slashes into backslashes; however, other
57 # Return whether a path is absolute.
58 # Trivial in Posix, harder on the Mac or MS-DOS.
61     """Test whether a path is absolute"""
68 # Ignore the previous parts if a part is absolute.
69 # Insert a '/' unless the first part is empty or already ends in '/'.
73     If any component is an absolute path, all previous path components
74     will be discarded.  An empty last part will result in a path that
78     path = a
81             path[:0] + sep  #23780: Ensure compatible data type even if p is null.
84                 path = b
85             elif not path or path.endswith(sep):
86                 path += b
88                 path += sep + b
92     return path
95 # Split a path in head (everything up to the last '/') and tail (the
96 # rest).  If the path ends in '/', tail will be empty.  If there is no
97 # '/' in the path, head  will be empty.
98 # Trailing '/'es are stripped from head unless it is the root.
101     """Split a pathname.  Returns tuple "(head, tail)" where "tail" is
112 # Split a path in root and extension.
113 # The extension is everything starting at the last dot in the last
114 # pathname component; the root is everything before that.
115 # It is always true that root + ext == p.
129 # path.  Useful on DOS/Windows/NT; on Unix, the drive is always empty.
132     """Split a pathname into drive and path. On Posix, drive is always
138 # Return the tail (basename) part of a path, same as split(path)[1].
148 # Return the head (dirname) part of a path, same as split(path)[0].
161 # Is a path a symbolic link?
164 def islink(path):  argument
165     """Test whether a path is a symbolic link"""
167         st = os.lstat(path)
172 # Being true for dangling symbolic links is also useful.
174 def lexists(path):  argument
175     """Test whether a path exists.  Returns True for broken symbolic links"""
177         os.lstat(path)
183 # Is a path a mount point?
184 # (Does this work for all UNIXes?  Is it even guaranteed to work by Posix?)
186 def ismount(path):  argument
187     """Test whether a path is a mount point"""
189         s1 = os.lstat(path)
191         # It doesn't exist -- so not a mount point. :-)
198     path = os.fspath(path)
199     if isinstance(path, bytes):
200         parent = join(path, b'..')
202         parent = join(path, '..')
212         return True     # path/.. on a different device as path
216         return True     # path/.. is the same i-node as path
222 # If the path doesn't begin with '~', or if the user or $HOME is unknown,
223 # the path is returned unchanged (leaving error reporting to whatever
224 # function is called with the expanded path as argument).
226 # (A function should also be defined to do full *sh-style environment
229 def expanduser(path):  argument
230     """Expand ~ and ~user constructions.  If user or $HOME is unknown,
232     path = os.fspath(path)
233     if isinstance(path, bytes):
237     if not path.startswith(tilde):
238         return path
239     sep = _get_sep(path)
240     i = path.find(sep, 1)
242         i = len(path)
248                 # pwd module unavailable, return path unchanged
249                 return path
253                 # bpo-10496: if the current user identifier doesn't exist in the
254                 # password database, return the path unchanged
255                 return path
262             # pwd module unavailable, return path unchanged
263             return path
264         name = path[1:i]
270             # bpo-10496: if the user name from the path doesn't exist in the
271             # password database, return the path unchanged
272             return path
274     # if no user home, return the path unchanged on VxWorks
275     if userhome is None and sys.platform == "vxworks":
276         return path
277     if isinstance(path, bytes):
283     return (userhome + path[i:]) or root
288 # Non-existent variables are left unchanged.
293 def expandvars(path):  argument
296     path = os.fspath(path)
298     if isinstance(path, bytes):
299         if b'$' not in path:
300             return path
309         if '$' not in path:
310             return path
320         m = search(path, i)
326             name = name[1:-1]
328             if environ is None:
335             tail = path[j:]
336             path = path[:i] + value
337             i = len(path)
338             path += tail
339     return path
342 # Normalize a path, e.g. A//B, A/./B and A/foo/../B all become A/B.
343 # It should be understood that this may change the meaning of the path
350     def normpath(path):  argument
351         """Normalize path, eliminating double slashes, etc."""
352         path = os.fspath(path)
353         if isinstance(path, bytes):
363         if path == empty:
365         initial_slashes = path.startswith(sep)
370             path.startswith(sep*2) and not path.startswith(sep*3)):
372         comps = path.split(sep)
378                  (new_comps and new_comps[-1] == dotdot)):
383         path = sep.join(comps)
385             path = sep*initial_slashes + path
386         return path or dot
389     def normpath(path):  argument
390         """Normalize path, eliminating double slashes, etc."""
391         path = os.fspath(path)
392         if isinstance(path, bytes):
393             return os.fsencode(_path_normpath(os.fsdecode(path))) or b"."
394         return _path_normpath(path) or "."
397 def abspath(path):  argument
398     """Return an absolute path."""
399     path = os.fspath(path)
400     if not isabs(path):
401         if isinstance(path, bytes):
405         path = join(cwd, path)
406     return normpath(path)
409 # Return a canonical path (i.e. the absolute location of a file on the
413     """Return the canonical path of the specified filename, eliminating any
414 symbolic links encountered in the path."""
416     path, ok = _joinrealpath(filename[:0], filename, strict, {})
417     return abspath(path)
420 # encountered in the second path.
421 def _joinrealpath(path, rest, strict, seen):  argument
422     if isinstance(path, bytes):
431     if strict is ALLOW_MISSING:
442         path = sep
451             if path:
452                 path, name = split(path)
454                     path = join(path, pardir, pardir)
456                 path = pardir
458         newpath = join(path, name)
466             path = newpath
470             # Already seen this path
471             path = seen[newpath]
472             if path is not None:
475             # The symlink is not resolved, so we must have a symlink loop.
480                 # Return already resolved part + rest of the path unchanged.
483         path, ok = _joinrealpath(path, os.readlink(newpath), strict, seen)
485             return join(path, rest), False
486         seen[newpath] = path # resolved symlink
488     return path, True
493 def relpath(path, start=None):  argument
494     """Return a relative version of a path"""
496     if not path:
497         raise ValueError("no path specified")
499     path = os.fspath(path)
500     if isinstance(path, bytes):
509     if start is None:
516         path_list = [x for x in abspath(path).split(sep) if x]
517         # Work out how much of the filepath is shared by start and path.
520         rel_list = [pardir] * (len(start_list)-i) + path_list[i:]
525         genericpath._check_arg_types('relpath', path, start)
529 # Return the longest common sub-path of the sequence of paths given as input.
530 # The paths are not normalized before comparing them (this is the
531 # responsibility of the caller). Any trailing separator is stripped from the
532 # returned path.
535     """Given a sequence of path names, returns the longest common sub-path."""
538         raise ValueError('commonpath() arg is an empty sequence')
549         split_paths = [path.split(sep) for path in paths]
554             raise ValueError("Can't mix absolute and relative paths") from None