Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | :mod:`os.path` --- Common pathname manipulations |
| 2 | ================================================ |
| 3 | |
| 4 | .. module:: os.path |
| 5 | :synopsis: Operations on pathnames. |
| 6 | |
Victor Stinner | d7538dd | 2018-12-14 13:37:26 +0100 | [diff] [blame] | 7 | **Source code:** :source:`Lib/posixpath.py` (for POSIX) and |
| 8 | :source:`Lib/ntpath.py` (for Windows NT). |
Terry Jan Reedy | fa089b9 | 2016-06-11 15:02:54 -0400 | [diff] [blame] | 9 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 10 | .. index:: single: path; operations |
| 11 | |
Terry Jan Reedy | fa089b9 | 2016-06-11 15:02:54 -0400 | [diff] [blame] | 12 | -------------- |
| 13 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 14 | This module implements some useful functions on pathnames. To read or |
| 15 | write files see :func:`open`, and for accessing the filesystem see the |
Martin v. Löwis | 651423c | 2008-10-07 07:03:04 +0000 | [diff] [blame] | 16 | :mod:`os` module. The path parameters can be passed as either strings, |
| 17 | or bytes. Applications are encouraged to represent file names as |
| 18 | (Unicode) character strings. Unfortunately, some file names may not be |
| 19 | representable as strings on Unix, so applications that need to support |
| 20 | arbitrary file names on Unix should use bytes objects to represent |
| 21 | path names. Vice versa, using bytes objects cannot represent all file |
| 22 | names on Windows (in the standard ``mbcs`` encoding), hence Windows |
| 23 | applications should use string objects to access all files. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 24 | |
R David Murray | a4e700c | 2013-01-06 16:13:10 -0500 | [diff] [blame] | 25 | Unlike a unix shell, Python does not do any *automatic* path expansions. |
| 26 | Functions such as :func:`expanduser` and :func:`expandvars` can be invoked |
| 27 | explicitly when an application desires shell-like path expansion. (See also |
| 28 | the :mod:`glob` module.) |
| 29 | |
Antoine Pitrou | 31119e4 | 2013-11-22 17:38:12 +0100 | [diff] [blame] | 30 | |
| 31 | .. seealso:: |
| 32 | The :mod:`pathlib` module offers high-level path objects. |
| 33 | |
| 34 | |
Georg Brandl | 76e5538 | 2008-10-08 16:34:57 +0000 | [diff] [blame] | 35 | .. note:: |
| 36 | |
| 37 | All of these functions accept either only bytes or only string objects as |
| 38 | their parameters. The result is an object of the same type, if a path or |
| 39 | file name is returned. |
| 40 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 41 | |
Benjamin Peterson | d23f822 | 2009-04-05 19:13:16 +0000 | [diff] [blame] | 42 | .. note:: |
| 43 | |
| 44 | Since different operating systems have different path name conventions, there |
| 45 | are several versions of this module in the standard library. The |
| 46 | :mod:`os.path` module is always the path module suitable for the operating |
| 47 | system Python is running on, and therefore usable for local paths. However, |
| 48 | you can also import and use the individual modules if you want to manipulate |
| 49 | a path that is *always* in one of the different formats. They all have the |
| 50 | same interface: |
| 51 | |
| 52 | * :mod:`posixpath` for UNIX-style paths |
| 53 | * :mod:`ntpath` for Windows paths |
Benjamin Peterson | d23f822 | 2009-04-05 19:13:16 +0000 | [diff] [blame] | 54 | |
| 55 | |
Serhiy Storchaka | 0185f34 | 2018-09-18 11:28:51 +0300 | [diff] [blame] | 56 | .. versionchanged:: 3.8 |
| 57 | |
| 58 | :func:`exists`, :func:`lexists`, :func:`isdir`, :func:`isfile`, |
| 59 | :func:`islink`, and :func:`ismount` now return ``False`` instead of |
| 60 | raising an exception for paths that contain characters or bytes |
| 61 | unrepresentable at the OS level. |
| 62 | |
| 63 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 64 | .. function:: abspath(path) |
| 65 | |
| 66 | Return a normalized absolutized version of the pathname *path*. On most |
Chris Jerdonek | 0b502ff | 2012-11-25 20:38:01 -0800 | [diff] [blame] | 67 | platforms, this is equivalent to calling the function :func:`normpath` as |
| 68 | follows: ``normpath(join(os.getcwd(), path))``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 69 | |
Brett Cannon | 6fa7aad | 2016-09-06 15:55:02 -0700 | [diff] [blame] | 70 | .. versionchanged:: 3.6 |
| 71 | Accepts a :term:`path-like object`. |
| 72 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 73 | |
| 74 | .. function:: basename(path) |
| 75 | |
Chris Jerdonek | 0b502ff | 2012-11-25 20:38:01 -0800 | [diff] [blame] | 76 | Return the base name of pathname *path*. This is the second element of the |
| 77 | pair returned by passing *path* to the function :func:`split`. Note that |
| 78 | the result of this function is different |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 79 | from the Unix :program:`basename` program; where :program:`basename` for |
| 80 | ``'/foo/bar/'`` returns ``'bar'``, the :func:`basename` function returns an |
| 81 | empty string (``''``). |
| 82 | |
Brett Cannon | 6fa7aad | 2016-09-06 15:55:02 -0700 | [diff] [blame] | 83 | .. versionchanged:: 3.6 |
| 84 | Accepts a :term:`path-like object`. |
| 85 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 86 | |
Serhiy Storchaka | 3822093 | 2015-03-31 15:31:53 +0300 | [diff] [blame] | 87 | .. function:: commonpath(paths) |
| 88 | |
| 89 | Return the longest common sub-path of each pathname in the sequence |
Makdon | 9549203 | 2019-06-13 21:59:49 +0800 | [diff] [blame] | 90 | *paths*. Raise :exc:`ValueError` if *paths* contain both absolute |
| 91 | and relative pathnames, the *paths* are on the different drives or |
| 92 | if *paths* is empty. Unlike :func:`commonprefix`, this returns a |
| 93 | valid path. |
Serhiy Storchaka | 3822093 | 2015-03-31 15:31:53 +0300 | [diff] [blame] | 94 | |
Cheryl Sabella | 2d6097d | 2018-10-12 10:55:20 -0400 | [diff] [blame] | 95 | .. availability:: Unix, Windows. |
Serhiy Storchaka | 3822093 | 2015-03-31 15:31:53 +0300 | [diff] [blame] | 96 | |
| 97 | .. versionadded:: 3.5 |
| 98 | |
Brett Cannon | 6fa7aad | 2016-09-06 15:55:02 -0700 | [diff] [blame] | 99 | .. versionchanged:: 3.6 |
| 100 | Accepts a sequence of :term:`path-like objects <path-like object>`. |
| 101 | |
Serhiy Storchaka | 3822093 | 2015-03-31 15:31:53 +0300 | [diff] [blame] | 102 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 103 | .. function:: commonprefix(list) |
| 104 | |
Serhiy Storchaka | 3822093 | 2015-03-31 15:31:53 +0300 | [diff] [blame] | 105 | Return the longest path prefix (taken character-by-character) that is a |
| 106 | prefix of all paths in *list*. If *list* is empty, return the empty string |
Yury Selivanov | 80ac11f | 2015-08-17 23:43:43 -0400 | [diff] [blame] | 107 | (``''``). |
| 108 | |
| 109 | .. note:: |
| 110 | |
| 111 | This function may return invalid paths because it works a |
| 112 | character at a time. To obtain a valid path, see |
| 113 | :func:`commonpath`. |
| 114 | |
| 115 | :: |
| 116 | |
Yury Selivanov | de11561 | 2015-08-19 09:53:28 -0400 | [diff] [blame] | 117 | >>> os.path.commonprefix(['/usr/lib', '/usr/local/lib']) |
| 118 | '/usr/l' |
Yury Selivanov | 80ac11f | 2015-08-17 23:43:43 -0400 | [diff] [blame] | 119 | |
Yury Selivanov | de11561 | 2015-08-19 09:53:28 -0400 | [diff] [blame] | 120 | >>> os.path.commonpath(['/usr/lib', '/usr/local/lib']) |
| 121 | '/usr' |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 122 | |
Brett Cannon | 6fa7aad | 2016-09-06 15:55:02 -0700 | [diff] [blame] | 123 | .. versionchanged:: 3.6 |
| 124 | Accepts a :term:`path-like object`. |
| 125 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 126 | |
| 127 | .. function:: dirname(path) |
| 128 | |
Chris Jerdonek | 0b502ff | 2012-11-25 20:38:01 -0800 | [diff] [blame] | 129 | Return the directory name of pathname *path*. This is the first element of |
| 130 | the pair returned by passing *path* to the function :func:`split`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 131 | |
Brett Cannon | 6fa7aad | 2016-09-06 15:55:02 -0700 | [diff] [blame] | 132 | .. versionchanged:: 3.6 |
| 133 | Accepts a :term:`path-like object`. |
| 134 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 135 | |
| 136 | .. function:: exists(path) |
| 137 | |
Richard Oudkerk | 2240ac1 | 2012-07-06 12:05:32 +0100 | [diff] [blame] | 138 | Return ``True`` if *path* refers to an existing path or an open |
| 139 | file descriptor. Returns ``False`` for broken symbolic links. On |
| 140 | some platforms, this function may return ``False`` if permission is |
| 141 | not granted to execute :func:`os.stat` on the requested file, even |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 142 | if the *path* physically exists. |
| 143 | |
Richard Oudkerk | 2240ac1 | 2012-07-06 12:05:32 +0100 | [diff] [blame] | 144 | .. versionchanged:: 3.3 |
| 145 | *path* can now be an integer: ``True`` is returned if it is an |
| 146 | open file descriptor, ``False`` otherwise. |
| 147 | |
Brett Cannon | 6fa7aad | 2016-09-06 15:55:02 -0700 | [diff] [blame] | 148 | .. versionchanged:: 3.6 |
| 149 | Accepts a :term:`path-like object`. |
| 150 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 151 | |
| 152 | .. function:: lexists(path) |
| 153 | |
| 154 | Return ``True`` if *path* refers to an existing path. Returns ``True`` for |
| 155 | broken symbolic links. Equivalent to :func:`exists` on platforms lacking |
| 156 | :func:`os.lstat`. |
| 157 | |
Brett Cannon | 6fa7aad | 2016-09-06 15:55:02 -0700 | [diff] [blame] | 158 | .. versionchanged:: 3.6 |
| 159 | Accepts a :term:`path-like object`. |
| 160 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 161 | |
Serhiy Storchaka | 913876d | 2018-10-28 13:41:26 +0200 | [diff] [blame] | 162 | .. index:: single: ~ (tilde); home directory expansion |
Serhiy Storchaka | ddb961d | 2018-10-26 09:00:49 +0300 | [diff] [blame] | 163 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 164 | .. function:: expanduser(path) |
| 165 | |
| 166 | On Unix and Windows, return the argument with an initial component of ``~`` or |
| 167 | ``~user`` replaced by that *user*'s home directory. |
| 168 | |
| 169 | .. index:: module: pwd |
| 170 | |
| 171 | On Unix, an initial ``~`` is replaced by the environment variable :envvar:`HOME` |
| 172 | if it is set; otherwise the current user's home directory is looked up in the |
| 173 | password directory through the built-in module :mod:`pwd`. An initial ``~user`` |
| 174 | is looked up directly in the password directory. |
| 175 | |
Steve Dower | 8ef864d | 2019-03-12 15:15:26 -0700 | [diff] [blame] | 176 | On Windows, :envvar:`USERPROFILE` will be used if set, otherwise a combination |
| 177 | of :envvar:`HOMEPATH` and :envvar:`HOMEDRIVE` will be used. An initial |
| 178 | ``~user`` is handled by stripping the last directory component from the created |
| 179 | user path derived above. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 180 | |
| 181 | If the expansion fails or if the path does not begin with a tilde, the path is |
| 182 | returned unchanged. |
| 183 | |
Brett Cannon | 6fa7aad | 2016-09-06 15:55:02 -0700 | [diff] [blame] | 184 | .. versionchanged:: 3.6 |
| 185 | Accepts a :term:`path-like object`. |
| 186 | |
Steve Dower | 8ef864d | 2019-03-12 15:15:26 -0700 | [diff] [blame] | 187 | .. versionchanged:: 3.8 |
| 188 | No longer uses :envvar:`HOME` on Windows. |
| 189 | |
Serhiy Storchaka | ddb961d | 2018-10-26 09:00:49 +0300 | [diff] [blame] | 190 | .. index:: |
Serhiy Storchaka | 913876d | 2018-10-28 13:41:26 +0200 | [diff] [blame] | 191 | single: $ (dollar); environment variables expansion |
| 192 | single: % (percent); environment variables expansion (Windows) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 193 | |
| 194 | .. function:: expandvars(path) |
| 195 | |
| 196 | Return the argument with environment variables expanded. Substrings of the form |
| 197 | ``$name`` or ``${name}`` are replaced by the value of environment variable |
| 198 | *name*. Malformed variable names and references to non-existing variables are |
| 199 | left unchanged. |
| 200 | |
| 201 | On Windows, ``%name%`` expansions are supported in addition to ``$name`` and |
| 202 | ``${name}``. |
| 203 | |
Brett Cannon | 6fa7aad | 2016-09-06 15:55:02 -0700 | [diff] [blame] | 204 | .. versionchanged:: 3.6 |
| 205 | Accepts a :term:`path-like object`. |
| 206 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 207 | |
| 208 | .. function:: getatime(path) |
| 209 | |
Victor Stinner | 01b5aab | 2017-10-24 02:02:00 -0700 | [diff] [blame] | 210 | Return the time of last access of *path*. The return value is a floating point number giving |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 211 | the number of seconds since the epoch (see the :mod:`time` module). Raise |
Andrew Svetlov | 618c2e1 | 2012-12-15 22:59:24 +0200 | [diff] [blame] | 212 | :exc:`OSError` if the file does not exist or is inaccessible. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 213 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 214 | |
| 215 | .. function:: getmtime(path) |
| 216 | |
Victor Stinner | 01b5aab | 2017-10-24 02:02:00 -0700 | [diff] [blame] | 217 | Return the time of last modification of *path*. The return value is a floating point number |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 218 | giving the number of seconds since the epoch (see the :mod:`time` module). |
Andrew Svetlov | 618c2e1 | 2012-12-15 22:59:24 +0200 | [diff] [blame] | 219 | Raise :exc:`OSError` if the file does not exist or is inaccessible. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 220 | |
Brett Cannon | 6fa7aad | 2016-09-06 15:55:02 -0700 | [diff] [blame] | 221 | .. versionchanged:: 3.6 |
| 222 | Accepts a :term:`path-like object`. |
| 223 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 224 | |
| 225 | .. function:: getctime(path) |
| 226 | |
| 227 | Return the system's ctime which, on some systems (like Unix) is the time of the |
Georg Brandl | f632494 | 2013-10-06 09:52:55 +0200 | [diff] [blame] | 228 | last metadata change, and, on others (like Windows), is the creation time for *path*. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 229 | The return value is a number giving the number of seconds since the epoch (see |
Andrew Svetlov | 618c2e1 | 2012-12-15 22:59:24 +0200 | [diff] [blame] | 230 | the :mod:`time` module). Raise :exc:`OSError` if the file does not exist or |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 231 | is inaccessible. |
| 232 | |
Brett Cannon | 6fa7aad | 2016-09-06 15:55:02 -0700 | [diff] [blame] | 233 | .. versionchanged:: 3.6 |
| 234 | Accepts a :term:`path-like object`. |
| 235 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 236 | |
| 237 | .. function:: getsize(path) |
| 238 | |
Andrew Svetlov | 618c2e1 | 2012-12-15 22:59:24 +0200 | [diff] [blame] | 239 | Return the size, in bytes, of *path*. Raise :exc:`OSError` if the file does |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 240 | not exist or is inaccessible. |
| 241 | |
Brett Cannon | 6fa7aad | 2016-09-06 15:55:02 -0700 | [diff] [blame] | 242 | .. versionchanged:: 3.6 |
| 243 | Accepts a :term:`path-like object`. |
| 244 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 245 | |
| 246 | .. function:: isabs(path) |
| 247 | |
Christian Heimes | af98da1 | 2008-01-27 15:18:18 +0000 | [diff] [blame] | 248 | Return ``True`` if *path* is an absolute pathname. On Unix, that means it |
| 249 | begins with a slash, on Windows that it begins with a (back)slash after chopping |
| 250 | off a potential drive letter. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 251 | |
Brett Cannon | 6fa7aad | 2016-09-06 15:55:02 -0700 | [diff] [blame] | 252 | .. versionchanged:: 3.6 |
| 253 | Accepts a :term:`path-like object`. |
| 254 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 255 | |
| 256 | .. function:: isfile(path) |
| 257 | |
Cheryl Sabella | b3dd18d | 2018-01-14 23:57:51 -0500 | [diff] [blame] | 258 | Return ``True`` if *path* is an :func:`existing <exists>` regular file. |
| 259 | This follows symbolic links, so both :func:`islink` and :func:`isfile` can |
| 260 | be true for the same path. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 261 | |
Brett Cannon | 6fa7aad | 2016-09-06 15:55:02 -0700 | [diff] [blame] | 262 | .. versionchanged:: 3.6 |
| 263 | Accepts a :term:`path-like object`. |
| 264 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 265 | |
| 266 | .. function:: isdir(path) |
| 267 | |
Cheryl Sabella | b3dd18d | 2018-01-14 23:57:51 -0500 | [diff] [blame] | 268 | Return ``True`` if *path* is an :func:`existing <exists>` directory. This |
| 269 | follows symbolic links, so both :func:`islink` and :func:`isdir` can be true |
| 270 | for the same path. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 271 | |
Brett Cannon | 6fa7aad | 2016-09-06 15:55:02 -0700 | [diff] [blame] | 272 | .. versionchanged:: 3.6 |
| 273 | Accepts a :term:`path-like object`. |
| 274 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 275 | |
| 276 | .. function:: islink(path) |
| 277 | |
Cheryl Sabella | b3dd18d | 2018-01-14 23:57:51 -0500 | [diff] [blame] | 278 | Return ``True`` if *path* refers to an :func:`existing <exists>` directory |
| 279 | entry that is a symbolic link. Always ``False`` if symbolic links are not |
| 280 | supported by the Python runtime. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 281 | |
Brett Cannon | 6fa7aad | 2016-09-06 15:55:02 -0700 | [diff] [blame] | 282 | .. versionchanged:: 3.6 |
| 283 | Accepts a :term:`path-like object`. |
| 284 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 285 | |
| 286 | .. function:: ismount(path) |
| 287 | |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 288 | Return ``True`` if pathname *path* is a :dfn:`mount point`: a point in a |
| 289 | file system where a different file system has been mounted. On POSIX, the |
Serhiy Storchaka | 32ebd85 | 2019-01-15 10:55:40 +0200 | [diff] [blame] | 290 | function checks whether *path*'s parent, :file:`{path}/..`, is on a different |
| 291 | device than *path*, or whether :file:`{path}/..` and *path* point to the same |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 292 | i-node on the same device --- this should detect mount points for all Unix |
Serhiy Storchaka | 32ebd85 | 2019-01-15 10:55:40 +0200 | [diff] [blame] | 293 | and POSIX variants. It is not able to reliably detect bind mounts on the |
| 294 | same filesystem. On Windows, a drive letter root and a share UNC are |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 295 | always mount points, and for any other path ``GetVolumePathName`` is called |
| 296 | to see if it is different from the input path. |
| 297 | |
| 298 | .. versionadded:: 3.4 |
| 299 | Support for detecting non-root mount points on Windows. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 300 | |
Brett Cannon | 6fa7aad | 2016-09-06 15:55:02 -0700 | [diff] [blame] | 301 | .. versionchanged:: 3.6 |
| 302 | Accepts a :term:`path-like object`. |
| 303 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 304 | |
Zachary Ware | a13dab4 | 2014-10-10 16:03:14 -0500 | [diff] [blame] | 305 | .. function:: join(path, *paths) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 306 | |
Zachary Ware | a13dab4 | 2014-10-10 16:03:14 -0500 | [diff] [blame] | 307 | Join one or more path components intelligently. The return value is the |
| 308 | concatenation of *path* and any members of *\*paths* with exactly one |
| 309 | directory separator (``os.sep``) following each non-empty part except the |
| 310 | last, meaning that the result will only end in a separator if the last |
| 311 | part is empty. If a component is an absolute path, all previous |
| 312 | components are thrown away and joining continues from the absolute path |
| 313 | component. |
| 314 | |
| 315 | On Windows, the drive letter is not reset when an absolute path component |
| 316 | (e.g., ``r'\foo'``) is encountered. If a component contains a drive |
| 317 | letter, all previous components are thrown away and the drive letter is |
| 318 | reset. Note that since there is a current directory for each drive, |
| 319 | ``os.path.join("c:", "foo")`` represents a path relative to the current |
| 320 | directory on drive :file:`C:` (:file:`c:foo`), not :file:`c:\\foo`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 321 | |
Brett Cannon | 6fa7aad | 2016-09-06 15:55:02 -0700 | [diff] [blame] | 322 | .. versionchanged:: 3.6 |
| 323 | Accepts a :term:`path-like object` for *path* and *paths*. |
| 324 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 325 | |
| 326 | .. function:: normcase(path) |
| 327 | |
Kexuan Sun | 32d1458 | 2019-05-13 04:38:20 -0700 | [diff] [blame] | 328 | Normalize the case of a pathname. On Windows, convert all characters in the |
| 329 | pathname to lowercase, and also convert forward slashes to backward slashes. |
| 330 | On other operating systems, return the path unchanged. |
Brett Cannon | 6fa7aad | 2016-09-06 15:55:02 -0700 | [diff] [blame] | 331 | |
| 332 | .. versionchanged:: 3.6 |
| 333 | Accepts a :term:`path-like object`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 334 | |
| 335 | |
| 336 | .. function:: normpath(path) |
| 337 | |
Terry Jan Reedy | ec6e132 | 2013-03-17 15:21:26 -0400 | [diff] [blame] | 338 | Normalize a pathname by collapsing redundant separators and up-level |
| 339 | references so that ``A//B``, ``A/B/``, ``A/./B`` and ``A/foo/../B`` all |
| 340 | become ``A/B``. This string manipulation may change the meaning of a path |
| 341 | that contains symbolic links. On Windows, it converts forward slashes to |
Terry Jan Reedy | f346041 | 2013-03-17 15:28:10 -0400 | [diff] [blame] | 342 | backward slashes. To normalize case, use :func:`normcase`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 343 | |
Brett Cannon | 6fa7aad | 2016-09-06 15:55:02 -0700 | [diff] [blame] | 344 | .. versionchanged:: 3.6 |
| 345 | Accepts a :term:`path-like object`. |
| 346 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 347 | |
| 348 | .. function:: realpath(path) |
| 349 | |
| 350 | Return the canonical path of the specified filename, eliminating any symbolic |
Steve Dower | 75e0649 | 2019-08-21 13:43:06 -0700 | [diff] [blame] | 351 | links encountered in the path (if they are supported by the operating |
| 352 | system). |
| 353 | |
| 354 | .. note:: |
| 355 | When symbolic link cycles occur, the returned path will be one member of |
| 356 | the cycle, but no guarantee is made about which member that will be. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 357 | |
Brett Cannon | 6fa7aad | 2016-09-06 15:55:02 -0700 | [diff] [blame] | 358 | .. versionchanged:: 3.6 |
| 359 | Accepts a :term:`path-like object`. |
| 360 | |
Steve Dower | 75e0649 | 2019-08-21 13:43:06 -0700 | [diff] [blame] | 361 | .. versionchanged:: 3.8 |
| 362 | Symbolic links and junctions are now resolved on Windows. |
| 363 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 364 | |
Benjamin Peterson | 409a1be | 2014-03-20 12:39:53 -0500 | [diff] [blame] | 365 | .. function:: relpath(path, start=os.curdir) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 366 | |
R David Murray | ce10fab | 2013-07-12 17:43:11 -0400 | [diff] [blame] | 367 | Return a relative filepath to *path* either from the current directory or |
| 368 | from an optional *start* directory. This is a path computation: the |
| 369 | filesystem is not accessed to confirm the existence or nature of *path* or |
| 370 | *start*. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 371 | |
Benjamin Peterson | f650e46 | 2010-05-06 23:03:05 +0000 | [diff] [blame] | 372 | *start* defaults to :attr:`os.curdir`. |
| 373 | |
Cheryl Sabella | 2d6097d | 2018-10-12 10:55:20 -0400 | [diff] [blame] | 374 | .. availability:: Unix, Windows. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 375 | |
Brett Cannon | 6fa7aad | 2016-09-06 15:55:02 -0700 | [diff] [blame] | 376 | .. versionchanged:: 3.6 |
| 377 | Accepts a :term:`path-like object`. |
| 378 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 379 | |
| 380 | .. function:: samefile(path1, path2) |
| 381 | |
Brian Curtin | d40e6f7 | 2010-07-08 21:39:08 +0000 | [diff] [blame] | 382 | Return ``True`` if both pathname arguments refer to the same file or directory. |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 383 | This is determined by the device number and i-node number and raises an |
Martin Panter | 7462b649 | 2015-11-02 03:37:02 +0000 | [diff] [blame] | 384 | exception if an :func:`os.stat` call on either pathname fails. |
Benjamin Peterson | f650e46 | 2010-05-06 23:03:05 +0000 | [diff] [blame] | 385 | |
Cheryl Sabella | 2d6097d | 2018-10-12 10:55:20 -0400 | [diff] [blame] | 386 | .. availability:: Unix, Windows. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 387 | |
Georg Brandl | b382337 | 2010-07-10 08:58:37 +0000 | [diff] [blame] | 388 | .. versionchanged:: 3.2 |
| 389 | Added Windows support. |
Brian Curtin | c739569 | 2010-07-09 15:15:09 +0000 | [diff] [blame] | 390 | |
Brian Curtin | 490b32a | 2012-12-26 07:03:03 -0600 | [diff] [blame] | 391 | .. versionchanged:: 3.4 |
| 392 | Windows now uses the same implementation as all other platforms. |
| 393 | |
Brett Cannon | 6fa7aad | 2016-09-06 15:55:02 -0700 | [diff] [blame] | 394 | .. versionchanged:: 3.6 |
| 395 | Accepts a :term:`path-like object`. |
| 396 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 397 | |
| 398 | .. function:: sameopenfile(fp1, fp2) |
| 399 | |
| 400 | Return ``True`` if the file descriptors *fp1* and *fp2* refer to the same file. |
Benjamin Peterson | f650e46 | 2010-05-06 23:03:05 +0000 | [diff] [blame] | 401 | |
Cheryl Sabella | 2d6097d | 2018-10-12 10:55:20 -0400 | [diff] [blame] | 402 | .. availability:: Unix, Windows. |
Brian Curtin | 6285774 | 2010-09-06 17:07:27 +0000 | [diff] [blame] | 403 | |
Georg Brandl | 61063cc | 2012-06-24 22:48:30 +0200 | [diff] [blame] | 404 | .. versionchanged:: 3.2 |
| 405 | Added Windows support. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 406 | |
Brett Cannon | 6fa7aad | 2016-09-06 15:55:02 -0700 | [diff] [blame] | 407 | .. versionchanged:: 3.6 |
| 408 | Accepts a :term:`path-like object`. |
| 409 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 410 | |
| 411 | .. function:: samestat(stat1, stat2) |
| 412 | |
| 413 | Return ``True`` if the stat tuples *stat1* and *stat2* refer to the same file. |
Serhiy Storchaka | dab8354 | 2013-10-13 20:12:43 +0300 | [diff] [blame] | 414 | These structures may have been returned by :func:`os.fstat`, |
| 415 | :func:`os.lstat`, or :func:`os.stat`. This function implements the |
| 416 | underlying comparison used by :func:`samefile` and :func:`sameopenfile`. |
Benjamin Peterson | f650e46 | 2010-05-06 23:03:05 +0000 | [diff] [blame] | 417 | |
Cheryl Sabella | 2d6097d | 2018-10-12 10:55:20 -0400 | [diff] [blame] | 418 | .. availability:: Unix, Windows. |
Brian Curtin | 490b32a | 2012-12-26 07:03:03 -0600 | [diff] [blame] | 419 | |
| 420 | .. versionchanged:: 3.4 |
| 421 | Added Windows support. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 422 | |
Brett Cannon | 6fa7aad | 2016-09-06 15:55:02 -0700 | [diff] [blame] | 423 | .. versionchanged:: 3.6 |
| 424 | Accepts a :term:`path-like object`. |
| 425 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 426 | |
| 427 | .. function:: split(path) |
| 428 | |
Georg Brandl | 539c165 | 2010-10-14 06:46:08 +0000 | [diff] [blame] | 429 | Split the pathname *path* into a pair, ``(head, tail)`` where *tail* is the |
| 430 | last pathname component and *head* is everything leading up to that. The |
| 431 | *tail* part will never contain a slash; if *path* ends in a slash, *tail* |
| 432 | will be empty. If there is no slash in *path*, *head* will be empty. If |
| 433 | *path* is empty, both *head* and *tail* are empty. Trailing slashes are |
| 434 | stripped from *head* unless it is the root (one or more slashes only). In |
| 435 | all cases, ``join(head, tail)`` returns a path to the same location as *path* |
Chris Jerdonek | 0b502ff | 2012-11-25 20:38:01 -0800 | [diff] [blame] | 436 | (but the strings may differ). Also see the functions :func:`dirname` and |
| 437 | :func:`basename`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 438 | |
Brett Cannon | 6fa7aad | 2016-09-06 15:55:02 -0700 | [diff] [blame] | 439 | .. versionchanged:: 3.6 |
| 440 | Accepts a :term:`path-like object`. |
| 441 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 442 | |
| 443 | .. function:: splitdrive(path) |
| 444 | |
| 445 | Split the pathname *path* into a pair ``(drive, tail)`` where *drive* is either |
Mark Hammond | 5a607a3 | 2009-05-06 08:04:54 +0000 | [diff] [blame] | 446 | a mount point or the empty string. On systems which do not use drive |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 447 | specifications, *drive* will always be the empty string. In all cases, ``drive |
| 448 | + tail`` will be the same as *path*. |
| 449 | |
Mark Hammond | 5a607a3 | 2009-05-06 08:04:54 +0000 | [diff] [blame] | 450 | On Windows, splits a pathname into drive/UNC sharepoint and relative path. |
| 451 | |
| 452 | If the path contains a drive letter, drive will contain everything |
| 453 | up to and including the colon. |
| 454 | e.g. ``splitdrive("c:/dir")`` returns ``("c:", "/dir")`` |
| 455 | |
| 456 | If the path contains a UNC path, drive will contain the host name |
| 457 | and share, up to but not including the fourth separator. |
| 458 | e.g. ``splitdrive("//host/computer/dir")`` returns ``("//host/computer", "/dir")`` |
| 459 | |
Brett Cannon | 6fa7aad | 2016-09-06 15:55:02 -0700 | [diff] [blame] | 460 | .. versionchanged:: 3.6 |
| 461 | Accepts a :term:`path-like object`. |
| 462 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 463 | |
| 464 | .. function:: splitext(path) |
| 465 | |
| 466 | Split the pathname *path* into a pair ``(root, ext)`` such that ``root + ext == |
| 467 | path``, and *ext* is empty or begins with a period and contains at most one |
| 468 | period. Leading periods on the basename are ignored; ``splitext('.cshrc')`` |
| 469 | returns ``('.cshrc', '')``. |
| 470 | |
Brett Cannon | 6fa7aad | 2016-09-06 15:55:02 -0700 | [diff] [blame] | 471 | .. versionchanged:: 3.6 |
| 472 | Accepts a :term:`path-like object`. |
| 473 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 474 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 475 | .. data:: supports_unicode_filenames |
| 476 | |
Serhiy Storchaka | fbc1c26 | 2013-11-29 12:17:13 +0200 | [diff] [blame] | 477 | ``True`` if arbitrary Unicode strings can be used as file names (within limitations |
Victor Stinner | b55e498 | 2010-09-11 00:22:12 +0000 | [diff] [blame] | 478 | imposed by the file system). |