Doc/library/os.path.rst

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