blob: ecb4e5a8f7072c52effe4606b7406190a2dd7787 [file] [log] [blame]
Guido van Rossum54f22ed2000-02-04 15:10:34 +00001"""Common operations on Posix pathnames.
2
3Instead of importing this module directly, import os and refer to
4this module as os.path. The "os.path" name is an alias for this
Victor Stinnerd7538dd2018-12-14 13:37:26 +01005module on Posix systems; on other systems (e.g. Windows),
Guido van Rossum54f22ed2000-02-04 15:10:34 +00006os.path provides the same operations in a manner specific to that
Victor Stinnerd7538dd2018-12-14 13:37:26 +01007platform, and is an alias to another module (e.g. ntpath).
Guido van Rossum54f22ed2000-02-04 15:10:34 +00008
9Some of this can actually be useful on non-Posix systems too, e.g.
10for manipulation of the pathname component of URLs.
Guido van Rossum346f7af1997-12-05 19:04:51 +000011"""
Guido van Rossumc6360141990-10-13 19:23:40 +000012
Serhiy Storchaka34601982018-01-07 17:54:31 +020013# Strings representing various path-related bits and pieces.
14# These are primarily for export; internally, they are hardcoded.
15# Should be set before imports for resolving cyclic dependency.
16curdir = '.'
17pardir = '..'
18extsep = '.'
19sep = '/'
20pathsep = ':'
Victor Stinner2c4c02f2019-04-17 17:05:30 +020021defpath = '/bin:/usr/bin'
Serhiy Storchaka34601982018-01-07 17:54:31 +020022altsep = None
23devnull = '/dev/null'
24
Guido van Rossumd3876d31996-07-23 03:47:28 +000025import os
Guido van Rossumf0af3e32008-10-02 18:55:37 +000026import sys
Guido van Rossum40d93041990-10-21 16:17:34 +000027import stat
Guido van Rossumd8faa362007-04-27 19:54:29 +000028import genericpath
Thomas Wouters89f507f2006-12-13 04:49:30 +000029from genericpath import *
Guido van Rossumc6360141990-10-13 19:23:40 +000030
Skip Montanaroc62c81e2001-02-12 02:00:42 +000031__all__ = ["normcase","isabs","join","splitdrive","split","splitext",
32 "basename","dirname","commonprefix","getsize","getmtime",
Georg Brandlf0de6a12005-08-22 18:02:59 +000033 "getatime","getctime","islink","exists","lexists","isdir","isfile",
Benjamin Petersond71ca412008-05-08 23:44:58 +000034 "ismount", "expanduser","expandvars","normpath","abspath",
Neal Norwitz61cdac62003-01-03 18:01:57 +000035 "samefile","sameopenfile","samestat",
Skip Montanaro117910d2003-02-14 19:35:31 +000036 "curdir","pardir","sep","pathsep","defpath","altsep","extsep",
Serhiy Storchaka38220932015-03-31 15:31:53 +030037 "devnull","realpath","supports_unicode_filenames","relpath",
38 "commonpath"]
Guido van Rossumc6360141990-10-13 19:23:40 +000039
Skip Montanaro117910d2003-02-14 19:35:31 +000040
Guido van Rossumf0af3e32008-10-02 18:55:37 +000041def _get_sep(path):
42 if isinstance(path, bytes):
43 return b'/'
44 else:
45 return '/'
46
Guido van Rossum7ac48781992-01-14 18:29:32 +000047# Normalize the case of a pathname. Trivial in Posix, string.lower on Mac.
48# On MS-DOS this may also turn slashes into backslashes; however, other
49# normalizations (such as optimizing '../' away) are not allowed
50# (another function should be defined to do that).
51
52def normcase(s):
Guido van Rossum346f7af1997-12-05 19:04:51 +000053 """Normalize case of pathname. Has no effect under Posix"""
Wolfgang Maier74510e22019-03-28 22:47:18 +010054 return os.fspath(s)
Guido van Rossum7ac48781992-01-14 18:29:32 +000055
56
Jeremy Hyltona05e2932000-06-28 14:48:01 +000057# Return whether a path is absolute.
Guido van Rossum7ac48781992-01-14 18:29:32 +000058# Trivial in Posix, harder on the Mac or MS-DOS.
59
60def isabs(s):
Guido van Rossum346f7af1997-12-05 19:04:51 +000061 """Test whether a path is absolute"""
Brett Cannon3f9183b2016-08-26 14:44:48 -070062 s = os.fspath(s)
Guido van Rossumf0af3e32008-10-02 18:55:37 +000063 sep = _get_sep(s)
64 return s.startswith(sep)
Guido van Rossum7ac48781992-01-14 18:29:32 +000065
66
Barry Warsaw384d2491997-02-18 21:53:25 +000067# Join pathnames.
68# Ignore the previous parts if a part is absolute.
Guido van Rossum4d0fdc31991-08-16 13:27:58 +000069# Insert a '/' unless the first part is empty or already ends in '/'.
Guido van Rossum7ac48781992-01-14 18:29:32 +000070
Barry Warsaw384d2491997-02-18 21:53:25 +000071def join(a, *p):
Guido van Rossum04110fb2007-08-24 16:32:05 +000072 """Join two or more pathname components, inserting '/' as needed.
73 If any component is an absolute path, all previous path components
R David Murraye3de1752012-07-21 14:33:56 -040074 will be discarded. An empty last part will result in a path that
75 ends with a separator."""
Brett Cannon3f9183b2016-08-26 14:44:48 -070076 a = os.fspath(a)
Guido van Rossumf0af3e32008-10-02 18:55:37 +000077 sep = _get_sep(a)
Guido van Rossum346f7af1997-12-05 19:04:51 +000078 path = a
Hynek Schlawack47749462012-07-15 16:21:30 +020079 try:
Serhiy Storchaka5bfc03f2015-05-19 11:00:07 +030080 if not p:
81 path[:0] + sep #23780: Ensure compatible data type even if p is null.
Brett Cannon3f9183b2016-08-26 14:44:48 -070082 for b in map(os.fspath, p):
Hynek Schlawack47749462012-07-15 16:21:30 +020083 if b.startswith(sep):
84 path = b
85 elif not path or path.endswith(sep):
86 path += b
87 else:
88 path += sep + b
Serhiy Storchaka3deeeb02014-10-04 14:58:43 +030089 except (TypeError, AttributeError, BytesWarning):
90 genericpath._check_arg_types('join', a, *p)
91 raise
Guido van Rossum346f7af1997-12-05 19:04:51 +000092 return path
Guido van Rossumc6360141990-10-13 19:23:40 +000093
94
Guido van Rossum26847381992-03-31 18:54:35 +000095# Split a path in head (everything up to the last '/') and tail (the
Guido van Rossuma89b1ba1995-09-01 20:32:21 +000096# 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.
Guido van Rossum7ac48781992-01-14 18:29:32 +000099
Guido van Rossumc6360141990-10-13 19:23:40 +0000100def split(p):
Tim Peters2344fae2001-01-15 00:50:52 +0000101 """Split a pathname. Returns tuple "(head, tail)" where "tail" is
Fred Drakec0ab93e2000-09-28 16:22:52 +0000102 everything after the final slash. Either part may be empty."""
Brett Cannon3f9183b2016-08-26 14:44:48 -0700103 p = os.fspath(p)
Guido van Rossumf0af3e32008-10-02 18:55:37 +0000104 sep = _get_sep(p)
105 i = p.rfind(sep) + 1
Guido van Rossum346f7af1997-12-05 19:04:51 +0000106 head, tail = p[:i], p[i:]
Guido van Rossumf0af3e32008-10-02 18:55:37 +0000107 if head and head != sep*len(head):
108 head = head.rstrip(sep)
Guido van Rossum346f7af1997-12-05 19:04:51 +0000109 return head, tail
Guido van Rossumc6360141990-10-13 19:23:40 +0000110
111
Guido van Rossum4d0fdc31991-08-16 13:27:58 +0000112# Split a path in root and extension.
Guido van Rossum422869a1996-08-20 20:24:17 +0000113# The extension is everything starting at the last dot in the last
Guido van Rossum4d0fdc31991-08-16 13:27:58 +0000114# pathname component; the root is everything before that.
Guido van Rossum7ac48781992-01-14 18:29:32 +0000115# It is always true that root + ext == p.
116
Guido van Rossum4d0fdc31991-08-16 13:27:58 +0000117def splitext(p):
Brett Cannon3f9183b2016-08-26 14:44:48 -0700118 p = os.fspath(p)
Guido van Rossumf0af3e32008-10-02 18:55:37 +0000119 if isinstance(p, bytes):
120 sep = b'/'
121 extsep = b'.'
122 else:
123 sep = '/'
124 extsep = '.'
125 return genericpath._splitext(p, sep, None, extsep)
Guido van Rossumd8faa362007-04-27 19:54:29 +0000126splitext.__doc__ = genericpath._splitext.__doc__
Guido van Rossum4d0fdc31991-08-16 13:27:58 +0000127
Guido van Rossum221df241995-08-07 20:17:55 +0000128# Split a pathname into a drive specification and the rest of the
129# path. Useful on DOS/Windows/NT; on Unix, the drive is always empty.
130
131def splitdrive(p):
Tim Peters2344fae2001-01-15 00:50:52 +0000132 """Split a pathname into drive and path. On Posix, drive is always
Fred Drakec0ab93e2000-09-28 16:22:52 +0000133 empty."""
Brett Cannon3f9183b2016-08-26 14:44:48 -0700134 p = os.fspath(p)
Guido van Rossumf0af3e32008-10-02 18:55:37 +0000135 return p[:0], p
Guido van Rossum221df241995-08-07 20:17:55 +0000136
137
Thomas Wouters89f507f2006-12-13 04:49:30 +0000138# Return the tail (basename) part of a path, same as split(path)[1].
Guido van Rossum7ac48781992-01-14 18:29:32 +0000139
Guido van Rossumc6360141990-10-13 19:23:40 +0000140def basename(p):
Guido van Rossum346f7af1997-12-05 19:04:51 +0000141 """Returns the final component of a pathname"""
Brett Cannon3f9183b2016-08-26 14:44:48 -0700142 p = os.fspath(p)
Guido van Rossumf0af3e32008-10-02 18:55:37 +0000143 sep = _get_sep(p)
144 i = p.rfind(sep) + 1
Thomas Wouters89f507f2006-12-13 04:49:30 +0000145 return p[i:]
Guido van Rossumc6360141990-10-13 19:23:40 +0000146
147
Thomas Wouters89f507f2006-12-13 04:49:30 +0000148# Return the head (dirname) part of a path, same as split(path)[0].
Guido van Rossumc629d341992-11-05 10:43:02 +0000149
150def dirname(p):
Guido van Rossum346f7af1997-12-05 19:04:51 +0000151 """Returns the directory component of a pathname"""
Brett Cannon3f9183b2016-08-26 14:44:48 -0700152 p = os.fspath(p)
Guido van Rossumf0af3e32008-10-02 18:55:37 +0000153 sep = _get_sep(p)
154 i = p.rfind(sep) + 1
Thomas Wouters89f507f2006-12-13 04:49:30 +0000155 head = p[:i]
Guido van Rossumf0af3e32008-10-02 18:55:37 +0000156 if head and head != sep*len(head):
157 head = head.rstrip(sep)
Thomas Wouters89f507f2006-12-13 04:49:30 +0000158 return head
Guido van Rossumc629d341992-11-05 10:43:02 +0000159
160
Guido van Rossum7ac48781992-01-14 18:29:32 +0000161# Is a path a symbolic link?
Guido van Rossumd3876d31996-07-23 03:47:28 +0000162# This will always return false on systems where os.lstat doesn't exist.
Guido van Rossum7ac48781992-01-14 18:29:32 +0000163
164def islink(path):
Guido van Rossum346f7af1997-12-05 19:04:51 +0000165 """Test whether a path is a symbolic link"""
166 try:
167 st = os.lstat(path)
Serhiy Storchaka0185f342018-09-18 11:28:51 +0300168 except (OSError, ValueError, AttributeError):
Guido van Rossum8ca162f2002-04-07 06:36:23 +0000169 return False
Raymond Hettinger32200ae2002-06-01 19:51:15 +0000170 return stat.S_ISLNK(st.st_mode)
Guido van Rossum7ac48781992-01-14 18:29:32 +0000171
Johannes Gijsbersae882f72004-08-30 10:19:56 +0000172# Being true for dangling symbolic links is also useful.
173
174def lexists(path):
175 """Test whether a path exists. Returns True for broken symbolic links"""
176 try:
Georg Brandl89fad142010-03-14 10:23:39 +0000177 os.lstat(path)
Serhiy Storchaka0185f342018-09-18 11:28:51 +0300178 except (OSError, ValueError):
Johannes Gijsbersae882f72004-08-30 10:19:56 +0000179 return False
180 return True
181
182
Guido van Rossumc6360141990-10-13 19:23:40 +0000183# Is a path a mount point?
Guido van Rossumd3876d31996-07-23 03:47:28 +0000184# (Does this work for all UNIXes? Is it even guaranteed to work by Posix?)
Guido van Rossum7ac48781992-01-14 18:29:32 +0000185
Guido van Rossumc6360141990-10-13 19:23:40 +0000186def ismount(path):
Guido van Rossum346f7af1997-12-05 19:04:51 +0000187 """Test whether a path is a mount point"""
188 try:
Christian Heimesfaf2f632008-01-06 16:59:19 +0000189 s1 = os.lstat(path)
Serhiy Storchaka0185f342018-09-18 11:28:51 +0300190 except (OSError, ValueError):
Brian Curtin06f6fbf2013-07-22 13:07:52 -0500191 # It doesn't exist -- so not a mount point. :-)
192 return False
193 else:
Brian Curtina3852ff2013-07-22 19:05:48 -0500194 # A symlink can never be a mount point
Brian Curtin06f6fbf2013-07-22 13:07:52 -0500195 if stat.S_ISLNK(s1.st_mode):
196 return False
197
198 if isinstance(path, bytes):
199 parent = join(path, b'..')
200 else:
201 parent = join(path, '..')
R David Murray750018b2016-08-18 21:27:48 -0400202 parent = realpath(parent)
Brian Curtin06f6fbf2013-07-22 13:07:52 -0500203 try:
Guido van Rossumf0af3e32008-10-02 18:55:37 +0000204 s2 = os.lstat(parent)
Serhiy Storchaka0185f342018-09-18 11:28:51 +0300205 except (OSError, ValueError):
Brian Curtin06f6fbf2013-07-22 13:07:52 -0500206 return False
207
Raymond Hettinger32200ae2002-06-01 19:51:15 +0000208 dev1 = s1.st_dev
209 dev2 = s2.st_dev
Guido van Rossum346f7af1997-12-05 19:04:51 +0000210 if dev1 != dev2:
Tim Petersbc0e9102002-04-04 22:55:58 +0000211 return True # path/.. on a different device as path
Raymond Hettinger32200ae2002-06-01 19:51:15 +0000212 ino1 = s1.st_ino
213 ino2 = s2.st_ino
Guido van Rossum346f7af1997-12-05 19:04:51 +0000214 if ino1 == ino2:
Tim Petersbc0e9102002-04-04 22:55:58 +0000215 return True # path/.. is the same i-node as path
216 return False
Guido van Rossumc6360141990-10-13 19:23:40 +0000217
218
Guido van Rossum7ac48781992-01-14 18:29:32 +0000219# Expand paths beginning with '~' or '~user'.
220# '~' means $HOME; '~user' means that user's home directory.
221# If the path doesn't begin with '~', or if the user or $HOME is unknown,
222# the path is returned unchanged (leaving error reporting to whatever
223# function is called with the expanded path as argument).
224# See also module 'glob' for expansion of *, ? and [...] in pathnames.
225# (A function should also be defined to do full *sh-style environment
226# variable expansion.)
227
228def expanduser(path):
Tim Peters2344fae2001-01-15 00:50:52 +0000229 """Expand ~ and ~user constructions. If user or $HOME is unknown,
Fred Drakec0ab93e2000-09-28 16:22:52 +0000230 do nothing."""
Brett Cannon3f9183b2016-08-26 14:44:48 -0700231 path = os.fspath(path)
Guido van Rossumf0af3e32008-10-02 18:55:37 +0000232 if isinstance(path, bytes):
233 tilde = b'~'
234 else:
235 tilde = '~'
236 if not path.startswith(tilde):
Guido van Rossum346f7af1997-12-05 19:04:51 +0000237 return path
Guido van Rossumf0af3e32008-10-02 18:55:37 +0000238 sep = _get_sep(path)
239 i = path.find(sep, 1)
Walter Dörwalda9da5ae2003-06-19 10:21:14 +0000240 if i < 0:
241 i = len(path)
Guido van Rossum346f7af1997-12-05 19:04:51 +0000242 if i == 1:
Walter Dörwalda9da5ae2003-06-19 10:21:14 +0000243 if 'HOME' not in os.environ:
Neal Norwitz609ba812002-09-05 21:08:25 +0000244 import pwd
Victor Stinnerf2f45552018-12-05 16:49:35 +0100245 try:
246 userhome = pwd.getpwuid(os.getuid()).pw_dir
247 except KeyError:
248 # bpo-10496: if the current user identifier doesn't exist in the
249 # password database, return the path unchanged
250 return path
Neal Norwitz609ba812002-09-05 21:08:25 +0000251 else:
252 userhome = os.environ['HOME']
Guido van Rossum346f7af1997-12-05 19:04:51 +0000253 else:
254 import pwd
Guido van Rossumf0af3e32008-10-02 18:55:37 +0000255 name = path[1:i]
256 if isinstance(name, bytes):
257 name = str(name, 'ASCII')
Guido van Rossum346f7af1997-12-05 19:04:51 +0000258 try:
Guido van Rossumf0af3e32008-10-02 18:55:37 +0000259 pwent = pwd.getpwnam(name)
Guido van Rossum346f7af1997-12-05 19:04:51 +0000260 except KeyError:
Victor Stinnerf2f45552018-12-05 16:49:35 +0100261 # bpo-10496: if the user name from the path doesn't exist in the
262 # password database, return the path unchanged
Guido van Rossum346f7af1997-12-05 19:04:51 +0000263 return path
Walter Dörwald77cdeaf2003-06-17 13:13:40 +0000264 userhome = pwent.pw_dir
Guido van Rossumf0af3e32008-10-02 18:55:37 +0000265 if isinstance(path, bytes):
Victor Stinner16004ac2010-09-29 16:59:18 +0000266 userhome = os.fsencode(userhome)
Benjamin Petersonef3e4c22009-04-11 19:48:14 +0000267 root = b'/'
268 else:
269 root = '/'
Jesus Cea7f0d8882012-05-10 05:10:50 +0200270 userhome = userhome.rstrip(root)
271 return (userhome + path[i:]) or root
Guido van Rossum4732ccf1992-08-09 13:54:50 +0000272
273
274# Expand paths containing shell variable substitutions.
Guido van Rossumb6775db1994-08-01 11:34:53 +0000275# This expands the forms $variable and ${variable} only.
Jeremy Hyltona05e2932000-06-28 14:48:01 +0000276# Non-existent variables are left unchanged.
Guido van Rossumb6775db1994-08-01 11:34:53 +0000277
278_varprog = None
Guido van Rossumf0af3e32008-10-02 18:55:37 +0000279_varprogb = None
Guido van Rossum4732ccf1992-08-09 13:54:50 +0000280
281def expandvars(path):
Guido van Rossum346f7af1997-12-05 19:04:51 +0000282 """Expand shell variables of form $var and ${var}. Unknown variables
Fred Drakec0ab93e2000-09-28 16:22:52 +0000283 are left unchanged."""
Brett Cannon3f9183b2016-08-26 14:44:48 -0700284 path = os.fspath(path)
Guido van Rossumf0af3e32008-10-02 18:55:37 +0000285 global _varprog, _varprogb
286 if isinstance(path, bytes):
287 if b'$' not in path:
288 return path
289 if not _varprogb:
290 import re
291 _varprogb = re.compile(br'\$(\w+|\{[^}]*\})', re.ASCII)
292 search = _varprogb.search
293 start = b'{'
294 end = b'}'
Serhiy Storchakadbb10192014-02-13 10:13:53 +0200295 environ = getattr(os, 'environb', None)
Guido van Rossumf0af3e32008-10-02 18:55:37 +0000296 else:
297 if '$' not in path:
298 return path
299 if not _varprog:
300 import re
301 _varprog = re.compile(r'\$(\w+|\{[^}]*\})', re.ASCII)
302 search = _varprog.search
303 start = '{'
304 end = '}'
Serhiy Storchakadbb10192014-02-13 10:13:53 +0200305 environ = os.environ
Guido van Rossum346f7af1997-12-05 19:04:51 +0000306 i = 0
Guido van Rossum8ca162f2002-04-07 06:36:23 +0000307 while True:
Guido van Rossumf0af3e32008-10-02 18:55:37 +0000308 m = search(path, i)
Guido van Rossum346f7af1997-12-05 19:04:51 +0000309 if not m:
310 break
311 i, j = m.span(0)
312 name = m.group(1)
Guido van Rossumf0af3e32008-10-02 18:55:37 +0000313 if name.startswith(start) and name.endswith(end):
Guido van Rossum346f7af1997-12-05 19:04:51 +0000314 name = name[1:-1]
Serhiy Storchakadbb10192014-02-13 10:13:53 +0200315 try:
316 if environ is None:
Serhiy Storchakaffadbb72014-02-13 10:45:14 +0200317 value = os.fsencode(os.environ[os.fsdecode(name)])
Serhiy Storchakadbb10192014-02-13 10:13:53 +0200318 else:
319 value = environ[name]
320 except KeyError:
321 i = j
322 else:
Guido van Rossum346f7af1997-12-05 19:04:51 +0000323 tail = path[j:]
Guido van Rossumf0af3e32008-10-02 18:55:37 +0000324 path = path[:i] + value
Guido van Rossum346f7af1997-12-05 19:04:51 +0000325 i = len(path)
Walter Dörwald77cdeaf2003-06-17 13:13:40 +0000326 path += tail
Guido van Rossum346f7af1997-12-05 19:04:51 +0000327 return path
Guido van Rossumc629d341992-11-05 10:43:02 +0000328
329
330# Normalize a path, e.g. A//B, A/./B and A/foo/../B all become A/B.
331# It should be understood that this may change the meaning of the path
332# if it contains symbolic links!
333
334def normpath(path):
Guido van Rossum346f7af1997-12-05 19:04:51 +0000335 """Normalize path, eliminating double slashes, etc."""
Brett Cannon3f9183b2016-08-26 14:44:48 -0700336 path = os.fspath(path)
Guido van Rossumf0af3e32008-10-02 18:55:37 +0000337 if isinstance(path, bytes):
338 sep = b'/'
339 empty = b''
340 dot = b'.'
341 dotdot = b'..'
342 else:
343 sep = '/'
344 empty = ''
345 dot = '.'
346 dotdot = '..'
347 if path == empty:
348 return dot
349 initial_slashes = path.startswith(sep)
Marc-André Lemburgbf222c92001-01-29 11:29:44 +0000350 # POSIX allows one or two initial slashes, but treats three or more
351 # as single slash.
Tim Peters658cba62001-02-09 20:06:00 +0000352 if (initial_slashes and
Guido van Rossumf0af3e32008-10-02 18:55:37 +0000353 path.startswith(sep*2) and not path.startswith(sep*3)):
Marc-André Lemburgbf222c92001-01-29 11:29:44 +0000354 initial_slashes = 2
Guido van Rossumf0af3e32008-10-02 18:55:37 +0000355 comps = path.split(sep)
Skip Montanaro018dfae2000-07-19 17:09:51 +0000356 new_comps = []
357 for comp in comps:
Guido van Rossumf0af3e32008-10-02 18:55:37 +0000358 if comp in (empty, dot):
Skip Montanaro018dfae2000-07-19 17:09:51 +0000359 continue
Guido van Rossumf0af3e32008-10-02 18:55:37 +0000360 if (comp != dotdot or (not initial_slashes and not new_comps) or
361 (new_comps and new_comps[-1] == dotdot)):
Skip Montanaro018dfae2000-07-19 17:09:51 +0000362 new_comps.append(comp)
363 elif new_comps:
364 new_comps.pop()
365 comps = new_comps
Guido van Rossumf0af3e32008-10-02 18:55:37 +0000366 path = sep.join(comps)
Marc-André Lemburgbf222c92001-01-29 11:29:44 +0000367 if initial_slashes:
Guido van Rossumf0af3e32008-10-02 18:55:37 +0000368 path = sep*initial_slashes + path
369 return path or dot
Guido van Rossume294cf61999-01-29 18:05:18 +0000370
371
Guido van Rossume294cf61999-01-29 18:05:18 +0000372def abspath(path):
Guido van Rossum54f22ed2000-02-04 15:10:34 +0000373 """Return an absolute path."""
Brett Cannon3f9183b2016-08-26 14:44:48 -0700374 path = os.fspath(path)
Guido van Rossume294cf61999-01-29 18:05:18 +0000375 if not isabs(path):
Guido van Rossumf0af3e32008-10-02 18:55:37 +0000376 if isinstance(path, bytes):
377 cwd = os.getcwdb()
378 else:
379 cwd = os.getcwd()
380 path = join(cwd, path)
Guido van Rossume294cf61999-01-29 18:05:18 +0000381 return normpath(path)
Guido van Rossum83eeef42001-09-17 15:16:09 +0000382
383
384# Return a canonical path (i.e. the absolute location of a file on the
385# filesystem).
386
387def realpath(filename):
388 """Return the canonical path of the specified filename, eliminating any
389symbolic links encountered in the path."""
Brett Cannon3f9183b2016-08-26 14:44:48 -0700390 filename = os.fspath(filename)
Serhiy Storchakadf326912013-02-10 12:22:07 +0200391 path, ok = _joinrealpath(filename[:0], filename, {})
392 return abspath(path)
393
Martin Panter119e5022016-04-16 09:28:57 +0000394# Join two paths, normalizing and eliminating any symbolic links
Serhiy Storchakadf326912013-02-10 12:22:07 +0200395# encountered in the second path.
396def _joinrealpath(path, rest, seen):
397 if isinstance(path, bytes):
Guido van Rossumf0af3e32008-10-02 18:55:37 +0000398 sep = b'/'
Serhiy Storchakadf326912013-02-10 12:22:07 +0200399 curdir = b'.'
400 pardir = b'..'
Johannes Gijsbers4ec40642004-08-14 15:01:53 +0000401 else:
Guido van Rossumf0af3e32008-10-02 18:55:37 +0000402 sep = '/'
Serhiy Storchakadf326912013-02-10 12:22:07 +0200403 curdir = '.'
404 pardir = '..'
Tim Petersa45cacf2004-08-20 03:47:14 +0000405
Serhiy Storchakadf326912013-02-10 12:22:07 +0200406 if isabs(rest):
407 rest = rest[1:]
408 path = sep
409
410 while rest:
411 name, _, rest = rest.partition(sep)
412 if not name or name == curdir:
413 # current dir
414 continue
415 if name == pardir:
416 # parent dir
417 if path:
Serhiy Storchaka467393d2013-02-18 12:21:04 +0200418 path, name = split(path)
419 if name == pardir:
420 path = join(path, pardir, pardir)
Brett Cannonf50299c2004-07-10 22:55:15 +0000421 else:
Serhiy Storchaka467393d2013-02-18 12:21:04 +0200422 path = pardir
Serhiy Storchakadf326912013-02-10 12:22:07 +0200423 continue
424 newpath = join(path, name)
425 if not islink(newpath):
426 path = newpath
427 continue
428 # Resolve the symbolic link
429 if newpath in seen:
430 # Already seen this path
431 path = seen[newpath]
432 if path is not None:
433 # use cached value
434 continue
435 # The symlink is not resolved, so we must have a symlink loop.
436 # Return already resolved part + rest of the path unchanged.
437 return join(newpath, rest), False
438 seen[newpath] = None # not resolved symlink
439 path, ok = _joinrealpath(path, os.readlink(newpath), seen)
440 if not ok:
441 return join(path, rest), False
442 seen[newpath] = path # resolved symlink
Tim Petersb64bec32001-09-18 02:26:39 +0000443
Serhiy Storchakadf326912013-02-10 12:22:07 +0200444 return path, True
Tim Petersa45cacf2004-08-20 03:47:14 +0000445
Brett Cannonf50299c2004-07-10 22:55:15 +0000446
Victor Stinnere797c162010-09-17 23:34:26 +0000447supports_unicode_filenames = (sys.platform == 'darwin')
Guido van Rossumd8faa362007-04-27 19:54:29 +0000448
Guido van Rossumf0af3e32008-10-02 18:55:37 +0000449def relpath(path, start=None):
Guido van Rossumd8faa362007-04-27 19:54:29 +0000450 """Return a relative version of a path"""
451
452 if not path:
453 raise ValueError("no path specified")
454
Brett Cannon3f9183b2016-08-26 14:44:48 -0700455 path = os.fspath(path)
Guido van Rossumf0af3e32008-10-02 18:55:37 +0000456 if isinstance(path, bytes):
457 curdir = b'.'
458 sep = b'/'
459 pardir = b'..'
460 else:
461 curdir = '.'
462 sep = '/'
463 pardir = '..'
464
465 if start is None:
466 start = curdir
Brett Cannon3f9183b2016-08-26 14:44:48 -0700467 else:
468 start = os.fspath(start)
Guido van Rossumf0af3e32008-10-02 18:55:37 +0000469
Serhiy Storchaka3deeeb02014-10-04 14:58:43 +0300470 try:
471 start_list = [x for x in abspath(start).split(sep) if x]
472 path_list = [x for x in abspath(path).split(sep) if x]
473 # Work out how much of the filepath is shared by start and path.
474 i = len(commonprefix([start_list, path_list]))
Guido van Rossumd8faa362007-04-27 19:54:29 +0000475
Serhiy Storchaka3deeeb02014-10-04 14:58:43 +0300476 rel_list = [pardir] * (len(start_list)-i) + path_list[i:]
477 if not rel_list:
478 return curdir
479 return join(*rel_list)
Serhiy Storchakae4f47082014-10-04 16:09:02 +0300480 except (TypeError, AttributeError, BytesWarning, DeprecationWarning):
Serhiy Storchaka3deeeb02014-10-04 14:58:43 +0300481 genericpath._check_arg_types('relpath', path, start)
482 raise
Serhiy Storchaka38220932015-03-31 15:31:53 +0300483
484
485# Return the longest common sub-path of the sequence of paths given as input.
486# The paths are not normalized before comparing them (this is the
487# responsibility of the caller). Any trailing separator is stripped from the
488# returned path.
489
490def commonpath(paths):
491 """Given a sequence of path names, returns the longest common sub-path."""
492
493 if not paths:
494 raise ValueError('commonpath() arg is an empty sequence')
495
Brett Cannon3f9183b2016-08-26 14:44:48 -0700496 paths = tuple(map(os.fspath, paths))
Serhiy Storchaka38220932015-03-31 15:31:53 +0300497 if isinstance(paths[0], bytes):
498 sep = b'/'
499 curdir = b'.'
500 else:
501 sep = '/'
502 curdir = '.'
503
504 try:
505 split_paths = [path.split(sep) for path in paths]
506
507 try:
508 isabs, = set(p[:1] == sep for p in paths)
509 except ValueError:
510 raise ValueError("Can't mix absolute and relative paths") from None
511
512 split_paths = [[c for c in s if c and c != curdir] for s in split_paths]
513 s1 = min(split_paths)
514 s2 = max(split_paths)
515 common = s1
516 for i, c in enumerate(s1):
517 if c != s2[i]:
518 common = s1[:i]
519 break
520
521 prefix = sep if isabs else sep[:0]
522 return prefix + sep.join(common)
523 except (TypeError, AttributeError):
524 genericpath._check_arg_types('commonpath', *paths)
525 raise