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 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 7 | .. index:: single: path; operations |
| 8 | |
| 9 | This module implements some useful functions on pathnames. To read or |
| 10 | 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] | 11 | :mod:`os` module. The path parameters can be passed as either strings, |
| 12 | or bytes. Applications are encouraged to represent file names as |
| 13 | (Unicode) character strings. Unfortunately, some file names may not be |
| 14 | representable as strings on Unix, so applications that need to support |
| 15 | arbitrary file names on Unix should use bytes objects to represent |
| 16 | path names. Vice versa, using bytes objects cannot represent all file |
| 17 | names on Windows (in the standard ``mbcs`` encoding), hence Windows |
| 18 | applications should use string objects to access all files. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 19 | |
Georg Brandl | 76e5538 | 2008-10-08 16:34:57 +0000 | [diff] [blame] | 20 | .. note:: |
| 21 | |
| 22 | All of these functions accept either only bytes or only string objects as |
| 23 | their parameters. The result is an object of the same type, if a path or |
| 24 | file name is returned. |
| 25 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 26 | |
Benjamin Peterson | d23f822 | 2009-04-05 19:13:16 +0000 | [diff] [blame] | 27 | .. note:: |
| 28 | |
| 29 | Since different operating systems have different path name conventions, there |
| 30 | are several versions of this module in the standard library. The |
| 31 | :mod:`os.path` module is always the path module suitable for the operating |
| 32 | system Python is running on, and therefore usable for local paths. However, |
| 33 | you can also import and use the individual modules if you want to manipulate |
| 34 | a path that is *always* in one of the different formats. They all have the |
| 35 | same interface: |
| 36 | |
| 37 | * :mod:`posixpath` for UNIX-style paths |
| 38 | * :mod:`ntpath` for Windows paths |
| 39 | * :mod:`macpath` for old-style MacOS paths |
| 40 | * :mod:`os2emxpath` for OS/2 EMX paths |
| 41 | |
| 42 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 43 | .. function:: abspath(path) |
| 44 | |
| 45 | Return a normalized absolutized version of the pathname *path*. On most |
| 46 | platforms, this is equivalent to ``normpath(join(os.getcwd(), path))``. |
| 47 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 48 | |
| 49 | .. function:: basename(path) |
| 50 | |
| 51 | Return the base name of pathname *path*. This is the second half of the pair |
| 52 | returned by ``split(path)``. Note that the result of this function is different |
| 53 | from the Unix :program:`basename` program; where :program:`basename` for |
| 54 | ``'/foo/bar/'`` returns ``'bar'``, the :func:`basename` function returns an |
| 55 | empty string (``''``). |
| 56 | |
| 57 | |
| 58 | .. function:: commonprefix(list) |
| 59 | |
| 60 | Return the longest path prefix (taken character-by-character) that is a prefix |
| 61 | of all paths in *list*. If *list* is empty, return the empty string (``''``). |
| 62 | Note that this may return invalid paths because it works a character at a time. |
| 63 | |
| 64 | |
| 65 | .. function:: dirname(path) |
| 66 | |
| 67 | Return the directory name of pathname *path*. This is the first half of the |
| 68 | pair returned by ``split(path)``. |
| 69 | |
| 70 | |
| 71 | .. function:: exists(path) |
| 72 | |
| 73 | Return ``True`` if *path* refers to an existing path. Returns ``False`` for |
| 74 | broken symbolic links. On some platforms, this function may return ``False`` if |
| 75 | permission is not granted to execute :func:`os.stat` on the requested file, even |
| 76 | if the *path* physically exists. |
| 77 | |
| 78 | |
| 79 | .. function:: lexists(path) |
| 80 | |
| 81 | Return ``True`` if *path* refers to an existing path. Returns ``True`` for |
| 82 | broken symbolic links. Equivalent to :func:`exists` on platforms lacking |
| 83 | :func:`os.lstat`. |
| 84 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 85 | |
| 86 | .. function:: expanduser(path) |
| 87 | |
| 88 | On Unix and Windows, return the argument with an initial component of ``~`` or |
| 89 | ``~user`` replaced by that *user*'s home directory. |
| 90 | |
| 91 | .. index:: module: pwd |
| 92 | |
| 93 | On Unix, an initial ``~`` is replaced by the environment variable :envvar:`HOME` |
| 94 | if it is set; otherwise the current user's home directory is looked up in the |
| 95 | password directory through the built-in module :mod:`pwd`. An initial ``~user`` |
| 96 | is looked up directly in the password directory. |
| 97 | |
| 98 | On Windows, :envvar:`HOME` and :envvar:`USERPROFILE` will be used if set, |
| 99 | otherwise a combination of :envvar:`HOMEPATH` and :envvar:`HOMEDRIVE` will be |
| 100 | used. An initial ``~user`` is handled by stripping the last directory component |
| 101 | from the created user path derived above. |
| 102 | |
| 103 | If the expansion fails or if the path does not begin with a tilde, the path is |
| 104 | returned unchanged. |
| 105 | |
| 106 | |
| 107 | .. function:: expandvars(path) |
| 108 | |
| 109 | Return the argument with environment variables expanded. Substrings of the form |
| 110 | ``$name`` or ``${name}`` are replaced by the value of environment variable |
| 111 | *name*. Malformed variable names and references to non-existing variables are |
| 112 | left unchanged. |
| 113 | |
| 114 | On Windows, ``%name%`` expansions are supported in addition to ``$name`` and |
| 115 | ``${name}``. |
| 116 | |
| 117 | |
| 118 | .. function:: getatime(path) |
| 119 | |
| 120 | Return the time of last access of *path*. The return value is a number giving |
| 121 | the number of seconds since the epoch (see the :mod:`time` module). Raise |
| 122 | :exc:`os.error` if the file does not exist or is inaccessible. |
| 123 | |
Georg Brandl | 55ac8f0 | 2007-09-01 13:51:09 +0000 | [diff] [blame] | 124 | If :func:`os.stat_float_times` returns True, the result is a floating point |
| 125 | number. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 126 | |
| 127 | |
| 128 | .. function:: getmtime(path) |
| 129 | |
| 130 | Return the time of last modification of *path*. The return value is a number |
| 131 | giving the number of seconds since the epoch (see the :mod:`time` module). |
| 132 | Raise :exc:`os.error` if the file does not exist or is inaccessible. |
| 133 | |
Georg Brandl | 55ac8f0 | 2007-09-01 13:51:09 +0000 | [diff] [blame] | 134 | If :func:`os.stat_float_times` returns True, the result is a floating point |
| 135 | number. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 136 | |
| 137 | |
| 138 | .. function:: getctime(path) |
| 139 | |
| 140 | Return the system's ctime which, on some systems (like Unix) is the time of the |
| 141 | last change, and, on others (like Windows), is the creation time for *path*. |
| 142 | The return value is a number giving the number of seconds since the epoch (see |
| 143 | the :mod:`time` module). Raise :exc:`os.error` if the file does not exist or |
| 144 | is inaccessible. |
| 145 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 146 | |
| 147 | .. function:: getsize(path) |
| 148 | |
| 149 | Return the size, in bytes, of *path*. Raise :exc:`os.error` if the file does |
| 150 | not exist or is inaccessible. |
| 151 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 152 | |
| 153 | .. function:: isabs(path) |
| 154 | |
Christian Heimes | af98da1 | 2008-01-27 15:18:18 +0000 | [diff] [blame] | 155 | Return ``True`` if *path* is an absolute pathname. On Unix, that means it |
| 156 | begins with a slash, on Windows that it begins with a (back)slash after chopping |
| 157 | off a potential drive letter. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 158 | |
| 159 | |
| 160 | .. function:: isfile(path) |
| 161 | |
| 162 | Return ``True`` if *path* is an existing regular file. This follows symbolic |
| 163 | links, so both :func:`islink` and :func:`isfile` can be true for the same path. |
| 164 | |
| 165 | |
| 166 | .. function:: isdir(path) |
| 167 | |
| 168 | Return ``True`` if *path* is an existing directory. This follows symbolic |
| 169 | links, so both :func:`islink` and :func:`isdir` can be true for the same path. |
| 170 | |
| 171 | |
| 172 | .. function:: islink(path) |
| 173 | |
| 174 | Return ``True`` if *path* refers to a directory entry that is a symbolic link. |
| 175 | Always ``False`` if symbolic links are not supported. |
| 176 | |
| 177 | |
| 178 | .. function:: ismount(path) |
| 179 | |
| 180 | Return ``True`` if pathname *path* is a :dfn:`mount point`: a point in a file |
| 181 | system where a different file system has been mounted. The function checks |
| 182 | whether *path*'s parent, :file:`path/..`, is on a different device than *path*, |
| 183 | or whether :file:`path/..` and *path* point to the same i-node on the same |
| 184 | device --- this should detect mount points for all Unix and POSIX variants. |
| 185 | |
| 186 | |
| 187 | .. function:: join(path1[, path2[, ...]]) |
| 188 | |
| 189 | Join one or more path components intelligently. If any component is an absolute |
| 190 | path, all previous components (on Windows, including the previous drive letter, |
| 191 | if there was one) are thrown away, and joining continues. The return value is |
| 192 | the concatenation of *path1*, and optionally *path2*, etc., with exactly one |
| 193 | directory separator (``os.sep``) inserted between components, unless *path2* is |
| 194 | empty. Note that on Windows, since there is a current directory for each drive, |
| 195 | ``os.path.join("c:", "foo")`` represents a path relative to the current |
| 196 | directory on drive :file:`C:` (:file:`c:foo`), not :file:`c:\\foo`. |
| 197 | |
| 198 | |
| 199 | .. function:: normcase(path) |
| 200 | |
Benjamin Peterson | d23f822 | 2009-04-05 19:13:16 +0000 | [diff] [blame] | 201 | Normalize the case of a pathname. On Unix and Mac OS X, this returns the |
| 202 | path unchanged; on case-insensitive filesystems, it converts the path to |
| 203 | lowercase. On Windows, it also converts forward slashes to backward slashes. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 204 | |
| 205 | |
| 206 | .. function:: normpath(path) |
| 207 | |
| 208 | Normalize a pathname. This collapses redundant separators and up-level |
| 209 | references so that ``A//B``, ``A/./B`` and ``A/foo/../B`` all become ``A/B``. |
| 210 | It does not normalize the case (use :func:`normcase` for that). On Windows, it |
| 211 | converts forward slashes to backward slashes. It should be understood that this |
| 212 | may change the meaning of the path if it contains symbolic links! |
| 213 | |
| 214 | |
| 215 | .. function:: realpath(path) |
| 216 | |
| 217 | Return the canonical path of the specified filename, eliminating any symbolic |
| 218 | links encountered in the path (if they are supported by the operating system). |
| 219 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 220 | |
| 221 | .. function:: relpath(path[, start]) |
| 222 | |
| 223 | Return a relative filepath to *path* either from the current directory or from |
| 224 | an optional *start* point. |
| 225 | |
Benjamin Peterson | d91203b | 2010-05-06 23:20:40 +0000 | [diff] [blame] | 226 | *start* defaults to :attr:`os.curdir`. |
| 227 | |
| 228 | Availability: Windows, Unix. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 229 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 230 | |
| 231 | .. function:: samefile(path1, path2) |
| 232 | |
| 233 | Return ``True`` if both pathname arguments refer to the same file or directory |
| 234 | (as indicated by device number and i-node number). Raise an exception if a |
Benjamin Peterson | d91203b | 2010-05-06 23:20:40 +0000 | [diff] [blame] | 235 | :func:`os.stat` call on either pathname fails. |
| 236 | |
| 237 | Availability: Unix. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 238 | |
| 239 | |
| 240 | .. function:: sameopenfile(fp1, fp2) |
| 241 | |
| 242 | Return ``True`` if the file descriptors *fp1* and *fp2* refer to the same file. |
Benjamin Peterson | d91203b | 2010-05-06 23:20:40 +0000 | [diff] [blame] | 243 | |
Georg Brandl | c575c90 | 2008-09-13 17:46:05 +0000 | [diff] [blame] | 244 | Availability: Unix. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 245 | |
| 246 | |
| 247 | .. function:: samestat(stat1, stat2) |
| 248 | |
| 249 | Return ``True`` if the stat tuples *stat1* and *stat2* refer to the same file. |
| 250 | These structures may have been returned by :func:`fstat`, :func:`lstat`, or |
| 251 | :func:`stat`. This function implements the underlying comparison used by |
Benjamin Peterson | d91203b | 2010-05-06 23:20:40 +0000 | [diff] [blame] | 252 | :func:`samefile` and :func:`sameopenfile`. |
| 253 | |
| 254 | Availability: Unix. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 255 | |
| 256 | |
| 257 | .. function:: split(path) |
| 258 | |
| 259 | Split the pathname *path* into a pair, ``(head, tail)`` where *tail* is the last |
| 260 | pathname component and *head* is everything leading up to that. The *tail* part |
| 261 | will never contain a slash; if *path* ends in a slash, *tail* will be empty. If |
| 262 | there is no slash in *path*, *head* will be empty. If *path* is empty, both |
| 263 | *head* and *tail* are empty. Trailing slashes are stripped from *head* unless |
| 264 | it is the root (one or more slashes only). In nearly all cases, ``join(head, |
| 265 | tail)`` equals *path* (the only exception being when there were multiple slashes |
| 266 | separating *head* from *tail*). |
| 267 | |
| 268 | |
| 269 | .. function:: splitdrive(path) |
| 270 | |
| 271 | 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] | 272 | 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] | 273 | specifications, *drive* will always be the empty string. In all cases, ``drive |
| 274 | + tail`` will be the same as *path*. |
| 275 | |
Mark Hammond | 5a607a3 | 2009-05-06 08:04:54 +0000 | [diff] [blame] | 276 | On Windows, splits a pathname into drive/UNC sharepoint and relative path. |
| 277 | |
| 278 | If the path contains a drive letter, drive will contain everything |
| 279 | up to and including the colon. |
| 280 | e.g. ``splitdrive("c:/dir")`` returns ``("c:", "/dir")`` |
| 281 | |
| 282 | If the path contains a UNC path, drive will contain the host name |
| 283 | and share, up to but not including the fourth separator. |
| 284 | e.g. ``splitdrive("//host/computer/dir")`` returns ``("//host/computer", "/dir")`` |
| 285 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 286 | |
| 287 | .. function:: splitext(path) |
| 288 | |
| 289 | Split the pathname *path* into a pair ``(root, ext)`` such that ``root + ext == |
| 290 | path``, and *ext* is empty or begins with a period and contains at most one |
| 291 | period. Leading periods on the basename are ignored; ``splitext('.cshrc')`` |
| 292 | returns ``('.cshrc', '')``. |
| 293 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 294 | |
| 295 | .. function:: splitunc(path) |
| 296 | |
Mark Hammond | 5a607a3 | 2009-05-06 08:04:54 +0000 | [diff] [blame] | 297 | .. deprecated:: 3.1 |
| 298 | Use *splitdrive* instead. |
| 299 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 300 | Split the pathname *path* into a pair ``(unc, rest)`` so that *unc* is the UNC |
| 301 | mount point (such as ``r'\\host\mount'``), if present, and *rest* the rest of |
| 302 | the path (such as ``r'\path\file.ext'``). For paths containing drive letters, |
Benjamin Peterson | d91203b | 2010-05-06 23:20:40 +0000 | [diff] [blame] | 303 | *unc* will always be the empty string. |
| 304 | |
| 305 | Availability: Windows. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 306 | |
| 307 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 308 | .. data:: supports_unicode_filenames |
| 309 | |
| 310 | True if arbitrary Unicode strings can be used as file names (within limitations |
Victor Stinner | a76020a | 2010-09-11 00:23:53 +0000 | [diff] [blame] | 311 | imposed by the file system). |