1:mod:`os.path` --- Common pathname manipulations 2================================================ 3 4.. module:: os.path 5 :synopsis: Operations on pathnames. 6 7.. index:: single: path; operations 8 9This module implements some useful functions on pathnames. To read or 10write files see :func:`open`, and for accessing the filesystem see the 11:mod:`os` module. 12 13.. note:: 14 15 On Windows, many of these functions do not properly support UNC pathnames. 16 :func:`splitunc` and :func:`ismount` do handle them correctly. 17 18 19Unlike a unix shell, Python does not do any *automatic* path expansions. 20Functions such as :func:`expanduser` and :func:`expandvars` can be invoked 21explicitly when an application desires shell-like path expansion. (See also 22the :mod:`glob` module.) 23 24.. note:: 25 26 Since different operating systems have different path name conventions, there 27 are several versions of this module in the standard library. The 28 :mod:`os.path` module is always the path module suitable for the operating 29 system Python is running on, and therefore usable for local paths. However, 30 you can also import and use the individual modules if you want to manipulate 31 a path that is *always* in one of the different formats. They all have the 32 same interface: 33 34 * :mod:`posixpath` for UNIX-style paths 35 * :mod:`ntpath` for Windows paths 36 * :mod:`macpath` for old-style MacOS paths 37 * :mod:`os2emxpath` for OS/2 EMX paths 38 39 40.. function:: abspath(path) 41 42 Return a normalized absolutized version of the pathname *path*. On most 43 platforms, this is equivalent to calling the function :func:`normpath` as 44 follows: ``normpath(join(os.getcwd(), path))``. 45 46 .. versionadded:: 1.5.2 47 48 49.. function:: basename(path) 50 51 Return the base name of pathname *path*. This is the second element of the 52 pair returned by passing *path* to the function :func:`split`. Note that 53 the result of this function is different 54 from the Unix :program:`basename` program; where :program:`basename` for 55 ``'/foo/bar/'`` returns ``'bar'``, the :func:`basename` function returns an 56 empty string (``''``). 57 58 59.. function:: commonprefix(list) 60 61 Return the longest path prefix (taken character-by-character) that is a prefix 62 of all paths in *list*. If *list* is empty, return the empty string (``''``). 63 Note that this may return invalid paths because it works a character at a time. 64 65 66.. function:: dirname(path) 67 68 Return the directory name of pathname *path*. This is the first element of 69 the pair returned by passing *path* to the function :func:`split`. 70 71 72.. function:: exists(path) 73 74 Return ``True`` if *path* refers to an existing path. Returns ``False`` for 75 broken symbolic links. On some platforms, this function may return ``False`` if 76 permission is not granted to execute :func:`os.stat` on the requested file, even 77 if the *path* physically exists. 78 79 80.. function:: lexists(path) 81 82 Return ``True`` if *path* refers to an existing path. Returns ``True`` for 83 broken symbolic links. Equivalent to :func:`exists` on platforms lacking 84 :func:`os.lstat`. 85 86 .. versionadded:: 2.4 87 88 89.. function:: expanduser(path) 90 91 On Unix and Windows, return the argument with an initial component of ``~`` or 92 ``~user`` replaced by that *user*'s home directory. 93 94 .. index:: module: pwd 95 96 On Unix, an initial ``~`` is replaced by the environment variable :envvar:`HOME` 97 if it is set; otherwise the current user's home directory is looked up in the 98 password directory through the built-in module :mod:`pwd`. An initial ``~user`` 99 is looked up directly in the password directory. 100 101 On Windows, :envvar:`HOME` and :envvar:`USERPROFILE` will be used if set, 102 otherwise a combination of :envvar:`HOMEPATH` and :envvar:`HOMEDRIVE` will be 103 used. An initial ``~user`` is handled by stripping the last directory component 104 from the created user path derived above. 105 106 If the expansion fails or if the path does not begin with a tilde, the path is 107 returned unchanged. 108 109 110.. function:: expandvars(path) 111 112 Return the argument with environment variables expanded. Substrings of the form 113 ``$name`` or ``${name}`` are replaced by the value of environment variable 114 *name*. Malformed variable names and references to non-existing variables are 115 left unchanged. 116 117 On Windows, ``%name%`` expansions are supported in addition to ``$name`` and 118 ``${name}``. 119 120 121.. function:: getatime(path) 122 123 Return the time of last access of *path*. The return value is a number giving 124 the number of seconds since the epoch (see the :mod:`time` module). Raise 125 :exc:`os.error` if the file does not exist or is inaccessible. 126 127 .. versionadded:: 1.5.2 128 129 .. versionchanged:: 2.3 130 If :func:`os.stat_float_times` returns ``True``, the result is a floating point 131 number. 132 133 134.. function:: getmtime(path) 135 136 Return the time of last modification of *path*. The return value is a number 137 giving the number of seconds since the epoch (see the :mod:`time` module). 138 Raise :exc:`os.error` if the file does not exist or is inaccessible. 139 140 .. versionadded:: 1.5.2 141 142 .. versionchanged:: 2.3 143 If :func:`os.stat_float_times` returns ``True``, the result is a floating point 144 number. 145 146 147.. function:: getctime(path) 148 149 Return the system's ctime which, on some systems (like Unix) is the time of the 150 last metadata change, and, on others (like Windows), is the creation time for *path*. 151 The return value is a number giving the number of seconds since the epoch (see 152 the :mod:`time` module). Raise :exc:`os.error` if the file does not exist or 153 is inaccessible. 154 155 .. versionadded:: 2.3 156 157 158.. function:: getsize(path) 159 160 Return the size, in bytes, of *path*. Raise :exc:`os.error` if the file does 161 not exist or is inaccessible. 162 163 .. versionadded:: 1.5.2 164 165 166.. function:: isabs(path) 167 168 Return ``True`` if *path* is an absolute pathname. On Unix, that means it 169 begins with a slash, on Windows that it begins with a (back)slash after chopping 170 off a potential drive letter. 171 172 173.. function:: isfile(path) 174 175 Return ``True`` if *path* is an existing regular file. This follows symbolic 176 links, so both :func:`islink` and :func:`isfile` can be true for the same path. 177 178 179.. function:: isdir(path) 180 181 Return ``True`` if *path* is an existing directory. This follows symbolic 182 links, so both :func:`islink` and :func:`isdir` can be true for the same path. 183 184 185.. function:: islink(path) 186 187 Return ``True`` if *path* refers to a directory entry that is a symbolic link. 188 Always ``False`` if symbolic links are not supported by the Python runtime. 189 190 191.. function:: ismount(path) 192 193 Return ``True`` if pathname *path* is a :dfn:`mount point`: a point in a file 194 system where a different file system has been mounted. The function checks 195 whether *path*'s parent, :file:`path/..`, is on a different device than *path*, 196 or whether :file:`path/..` and *path* point to the same i-node on the same 197 device --- this should detect mount points for all Unix and POSIX variants. 198 199 200.. function:: join(path, *paths) 201 202 Join one or more path components intelligently. The return value is the 203 concatenation of *path* and any members of *\*paths* with exactly one 204 directory separator (``os.sep``) following each non-empty part except the 205 last, meaning that the result will only end in a separator if the last 206 part is empty. If a component is an absolute path, all previous 207 components are thrown away and joining continues from the absolute path 208 component. 209 210 On Windows, the drive letter is not reset when an absolute path component 211 (e.g., ``r'\foo'``) is encountered. If a component contains a drive 212 letter, all previous components are thrown away and the drive letter is 213 reset. Note that since there is a current directory for each drive, 214 ``os.path.join("c:", "foo")`` represents a path relative to the current 215 directory on drive :file:`C:` (:file:`c:foo`), not :file:`c:\\foo`. 216 217 218.. function:: normcase(path) 219 220 Normalize the case of a pathname. On Unix and Mac OS X, this returns the 221 path unchanged; on case-insensitive filesystems, it converts the path to 222 lowercase. On Windows, it also converts forward slashes to backward slashes. 223 224 225.. function:: normpath(path) 226 227 Normalize a pathname by collapsing redundant separators and up-level 228 references so that ``A//B``, ``A/B/``, ``A/./B`` and ``A/foo/../B`` all 229 become ``A/B``. This string manipulation may change the meaning of a path 230 that contains symbolic links. On Windows, it converts forward slashes to 231 backward slashes. To normalize case, use :func:`normcase`. 232 233 234.. function:: realpath(path) 235 236 Return the canonical path of the specified filename, eliminating any symbolic 237 links encountered in the path (if they are supported by the operating system). 238 239 .. versionadded:: 2.2 240 241 242.. function:: relpath(path[, start]) 243 244 Return a relative filepath to *path* either from the current directory or 245 from an optional *start* directory. This is a path computation: the 246 filesystem is not accessed to confirm the existence or nature of *path* or 247 *start*. 248 249 *start* defaults to :attr:`os.curdir`. 250 251 Availability: Windows, Unix. 252 253 .. versionadded:: 2.6 254 255 256.. function:: samefile(path1, path2) 257 258 Return ``True`` if both pathname arguments refer to the same file or directory 259 (as indicated by device number and i-node number). Raise an exception if an 260 :func:`os.stat` call on either pathname fails. 261 262 Availability: Unix. 263 264 265.. function:: sameopenfile(fp1, fp2) 266 267 Return ``True`` if the file descriptors *fp1* and *fp2* refer to the same file. 268 269 Availability: Unix. 270 271 272.. function:: samestat(stat1, stat2) 273 274 Return ``True`` if the stat tuples *stat1* and *stat2* refer to the same file. 275 These structures may have been returned by :func:`os.fstat`, 276 :func:`os.lstat`, or :func:`os.stat`. This function implements the 277 underlying comparison used by :func:`samefile` and :func:`sameopenfile`. 278 279 Availability: Unix. 280 281 282.. function:: split(path) 283 284 Split the pathname *path* into a pair, ``(head, tail)`` where *tail* is the 285 last pathname component and *head* is everything leading up to that. The 286 *tail* part will never contain a slash; if *path* ends in a slash, *tail* 287 will be empty. If there is no slash in *path*, *head* will be empty. If 288 *path* is empty, both *head* and *tail* are empty. Trailing slashes are 289 stripped from *head* unless it is the root (one or more slashes only). In 290 all cases, ``join(head, tail)`` returns a path to the same location as *path* 291 (but the strings may differ). Also see the functions :func:`dirname` and 292 :func:`basename`. 293 294 295.. function:: splitdrive(path) 296 297 Split the pathname *path* into a pair ``(drive, tail)`` where *drive* is either 298 a drive specification or the empty string. On systems which do not use drive 299 specifications, *drive* will always be the empty string. In all cases, ``drive 300 + tail`` will be the same as *path*. 301 302 .. versionadded:: 1.3 303 304 305.. function:: splitext(path) 306 307 Split the pathname *path* into a pair ``(root, ext)`` such that ``root + ext == 308 path``, and *ext* is empty or begins with a period and contains at most one 309 period. Leading periods on the basename are ignored; ``splitext('.cshrc')`` 310 returns ``('.cshrc', '')``. 311 312 .. versionchanged:: 2.6 313 Earlier versions could produce an empty root when the only period was the 314 first character. 315 316 317.. function:: splitunc(path) 318 319 Split the pathname *path* into a pair ``(unc, rest)`` so that *unc* is the UNC 320 mount point (such as ``r'\\host\mount'``), if present, and *rest* the rest of 321 the path (such as ``r'\path\file.ext'``). For paths containing drive letters, 322 *unc* will always be the empty string. 323 324 Availability: Windows. 325 326 327.. function:: walk(path, visit, arg) 328 329 Calls the function *visit* with arguments ``(arg, dirname, names)`` for each 330 directory in the directory tree rooted at *path* (including *path* itself, if it 331 is a directory). The argument *dirname* specifies the visited directory, the 332 argument *names* lists the files in the directory (gotten from 333 ``os.listdir(dirname)``). The *visit* function may modify *names* to influence 334 the set of directories visited below *dirname*, e.g. to avoid visiting certain 335 parts of the tree. (The object referred to by *names* must be modified in 336 place, using :keyword:`del` or slice assignment.) 337 338 .. note:: 339 340 Symbolic links to directories are not treated as subdirectories, and that 341 :func:`walk` therefore will not visit them. To visit linked directories you must 342 identify them with ``os.path.islink(file)`` and ``os.path.isdir(file)``, and 343 invoke :func:`walk` as necessary. 344 345 .. note:: 346 347 This function is deprecated and has been removed in Python 3 in favor of 348 :func:`os.walk`. 349 350 351.. data:: supports_unicode_filenames 352 353 ``True`` if arbitrary Unicode strings can be used as file names (within limitations 354 imposed by the file system). 355 356 .. versionadded:: 2.3 357 358