Issue #5170: Fixed regression caused when fixing #5768.
[python.git] / Doc / library / os.path.rst
blob0e7f3765168837cb52699cad14a510eb001c978f
1 :mod:`os.path` --- Common pathname manipulations
2 ================================================
4 .. module:: os.path
5    :synopsis: Operations on pathnames.
7 .. index:: single: path; operations
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.
13 .. warning::
15    On Windows, many of these functions do not properly support UNC pathnames.
16    :func:`splitunc` and :func:`ismount` do handle them correctly.
19 .. note::
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:
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
35 .. function:: abspath(path)
37    Return a normalized absolutized version of the pathname *path*. On most
38    platforms, this is equivalent to ``normpath(join(os.getcwd(), path))``.
40    .. versionadded:: 1.5.2
43 .. function:: basename(path)
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 (``''``).
52 .. function:: commonprefix(list)
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.
59 .. function:: dirname(path)
61    Return the directory name of pathname *path*.  This is the first half of the
62    pair returned by ``split(path)``.
65 .. function:: exists(path)
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.
73 .. function:: lexists(path)
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`.
79    .. versionadded:: 2.4
82 .. function:: expanduser(path)
84    On Unix and Windows, return the argument with an initial component of ``~`` or
85    ``~user`` replaced by that *user*'s home directory.
87    .. index:: module: pwd
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.
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.
99    If the expansion fails or if the path does not begin with a tilde, the path is
100    returned unchanged.
103 .. function:: expandvars(path)
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.
110    On Windows, ``%name%`` expansions are supported in addition to ``$name`` and
111    ``${name}``.
114 .. function:: getatime(path)
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.
120    .. versionadded:: 1.5.2
122    .. versionchanged:: 2.3
123       If :func:`os.stat_float_times` returns True, the result is a floating point
124       number.
127 .. function:: getmtime(path)
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.
133    .. versionadded:: 1.5.2
135    .. versionchanged:: 2.3
136       If :func:`os.stat_float_times` returns True, the result is a floating point
137       number.
140 .. function:: getctime(path)
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.
148    .. versionadded:: 2.3
151 .. function:: getsize(path)
153    Return the size, in bytes, of *path*.  Raise :exc:`os.error` if the file does
154    not exist or is inaccessible.
156    .. versionadded:: 1.5.2
159 .. function:: isabs(path)
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.
166 .. function:: isfile(path)
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.
172 .. function:: isdir(path)
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.
178 .. function:: islink(path)
180    Return ``True`` if *path* refers to a directory entry that is a symbolic link.
181    Always ``False`` if symbolic links are not supported.
184 .. function:: ismount(path)
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.
193 .. function:: join(path1[, path2[, ...]])
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``) inserted between components, unless *path2* is
200    empty.  Note that on Windows, since there is a current directory for each drive,
201    ``os.path.join("c:", "foo")`` represents a path relative to the current
202    directory on drive :file:`C:` (:file:`c:foo`), not :file:`c:\\foo`.
205 .. function:: normcase(path)
207    Normalize the case of a pathname.  On Unix and Mac OS X, this returns the
208    path unchanged; on case-insensitive filesystems, it converts the path to
209    lowercase.  On Windows, it also converts forward slashes to backward slashes.
212 .. function:: normpath(path)
214    Normalize a pathname.  This collapses redundant separators and up-level
215    references so that ``A//B``, ``A/./B`` and ``A/foo/../B`` all become ``A/B``.
216    It does not normalize the case (use :func:`normcase` for that).  On Windows, it
217    converts forward slashes to backward slashes. It should be understood that this
218    may change the meaning of the path if it contains symbolic links!
221 .. function:: realpath(path)
223    Return the canonical path of the specified filename, eliminating any symbolic
224    links encountered in the path (if they are supported by the operating system).
226    .. versionadded:: 2.2
229 .. function:: relpath(path[, start])
231    Return a relative filepath to *path* either from the current directory or from
232    an optional *start* point.
234    *start* defaults to :attr:`os.curdir`. Availability:  Windows, Unix.
236    .. versionadded:: 2.6
239 .. function:: samefile(path1, path2)
241    Return ``True`` if both pathname arguments refer to the same file or directory
242    (as indicated by device number and i-node number). Raise an exception if a
243    :func:`os.stat` call on either pathname fails. Availability: Unix.
246 .. function:: sameopenfile(fp1, fp2)
248    Return ``True`` if the file descriptors *fp1* and *fp2* refer to the same file.
249    Availability: Unix.
252 .. function:: samestat(stat1, stat2)
254    Return ``True`` if the stat tuples *stat1* and *stat2* refer to the same file.
255    These structures may have been returned by :func:`fstat`, :func:`lstat`, or
256    :func:`stat`.  This function implements the underlying comparison used by
257    :func:`samefile` and :func:`sameopenfile`. Availability: Unix.
260 .. function:: split(path)
262    Split the pathname *path* into a pair, ``(head, tail)`` where *tail* is the last
263    pathname component and *head* is everything leading up to that.  The *tail* part
264    will never contain a slash; if *path* ends in a slash, *tail* will be empty.  If
265    there is no slash in *path*, *head* will be empty.  If *path* is empty, both
266    *head* and *tail* are empty.  Trailing slashes are stripped from *head* unless
267    it is the root (one or more slashes only).  In nearly all cases, ``join(head,
268    tail)`` equals *path* (the only exception being when there were multiple slashes
269    separating *head* from *tail*).
272 .. function:: splitdrive(path)
274    Split the pathname *path* into a pair ``(drive, tail)`` where *drive* is either
275    a drive specification or the empty string.  On systems which do not use drive
276    specifications, *drive* will always be the empty string.  In all cases, ``drive
277    + tail`` will be the same as *path*.
279    .. versionadded:: 1.3
282 .. function:: splitext(path)
284    Split the pathname *path* into a pair ``(root, ext)``  such that ``root + ext ==
285    path``, and *ext* is empty or begins with a period and contains at most one
286    period. Leading periods on the basename are  ignored; ``splitext('.cshrc')``
287    returns  ``('.cshrc', '')``.
289    .. versionchanged:: 2.6
290       Earlier versions could produce an empty root when the only period was the
291       first character.
294 .. function:: splitunc(path)
296    Split the pathname *path* into a pair ``(unc, rest)`` so that *unc* is the UNC
297    mount point (such as ``r'\\host\mount'``), if present, and *rest* the rest of
298    the path (such as  ``r'\path\file.ext'``).  For paths containing drive letters,
299    *unc* will always be the empty string. Availability:  Windows.
302 .. function:: walk(path, visit, arg)
304    Calls the function *visit* with arguments ``(arg, dirname, names)`` for each
305    directory in the directory tree rooted at *path* (including *path* itself, if it
306    is a directory).  The argument *dirname* specifies the visited directory, the
307    argument *names* lists the files in the directory (gotten from
308    ``os.listdir(dirname)``). The *visit* function may modify *names* to influence
309    the set of directories visited below *dirname*, e.g. to avoid visiting certain
310    parts of the tree.  (The object referred to by *names* must be modified in
311    place, using :keyword:`del` or slice assignment.)
313    .. note::
315       Symbolic links to directories are not treated as subdirectories, and that
316       :func:`walk` therefore will not visit them. To visit linked directories you must
317       identify them with ``os.path.islink(file)`` and ``os.path.isdir(file)``, and
318       invoke :func:`walk` as necessary.
320    .. warning::
322       This function is deprecated and has been removed in 3.0 in favor of
323       :func:`os.walk`.
326 .. data:: supports_unicode_filenames
328    True if arbitrary Unicode strings can be used as file names (within limitations
329    imposed by the file system), and if :func:`os.listdir` returns Unicode strings
330    for a Unicode argument.
332    .. versionadded:: 2.3