2 :mod:`os.path` --- Common pathname manipulations
3 ================================================
6 :synopsis: Operations on pathnames.
9 .. index:: single: path; operations
11 This module implements some useful functions on pathnames. To read or
12 write files see :func:`open`, and for accessing the filesystem see the
17 On Windows, many of these functions do not properly support UNC pathnames.
18 :func:`splitunc` and :func:`ismount` do handle them correctly.
21 .. function:: abspath(path)
23 Return a normalized absolutized version of the pathname *path*. On most
24 platforms, this is equivalent to ``normpath(join(os.getcwd(), path))``.
26 .. versionadded:: 1.5.2
29 .. function:: basename(path)
31 Return the base name of pathname *path*. This is the second half of the pair
32 returned by ``split(path)``. Note that the result of this function is different
33 from the Unix :program:`basename` program; where :program:`basename` for
34 ``'/foo/bar/'`` returns ``'bar'``, the :func:`basename` function returns an
35 empty string (``''``).
38 .. function:: commonprefix(list)
40 Return the longest path prefix (taken character-by-character) that is a prefix
41 of all paths in *list*. If *list* is empty, return the empty string (``''``).
42 Note that this may return invalid paths because it works a character at a time.
45 .. function:: dirname(path)
47 Return the directory name of pathname *path*. This is the first half of the
48 pair returned by ``split(path)``.
51 .. function:: exists(path)
53 Return ``True`` if *path* refers to an existing path. Returns ``False`` for
54 broken symbolic links. On some platforms, this function may return ``False`` if
55 permission is not granted to execute :func:`os.stat` on the requested file, even
56 if the *path* physically exists.
59 .. function:: lexists(path)
61 Return ``True`` if *path* refers to an existing path. Returns ``True`` for
62 broken symbolic links. Equivalent to :func:`exists` on platforms lacking
68 .. function:: expanduser(path)
70 On Unix and Windows, return the argument with an initial component of ``~`` or
71 ``~user`` replaced by that *user*'s home directory.
73 .. index:: module: pwd
75 On Unix, an initial ``~`` is replaced by the environment variable :envvar:`HOME`
76 if it is set; otherwise the current user's home directory is looked up in the
77 password directory through the built-in module :mod:`pwd`. An initial ``~user``
78 is looked up directly in the password directory.
80 On Windows, :envvar:`HOME` and :envvar:`USERPROFILE` will be used if set,
81 otherwise a combination of :envvar:`HOMEPATH` and :envvar:`HOMEDRIVE` will be
82 used. An initial ``~user`` is handled by stripping the last directory component
83 from the created user path derived above.
85 If the expansion fails or if the path does not begin with a tilde, the path is
89 .. function:: expandvars(path)
91 Return the argument with environment variables expanded. Substrings of the form
92 ``$name`` or ``${name}`` are replaced by the value of environment variable
93 *name*. Malformed variable names and references to non-existing variables are
96 On Windows, ``%name%`` expansions are supported in addition to ``$name`` and
100 .. function:: getatime(path)
102 Return the time of last access of *path*. The return value is a number giving
103 the number of seconds since the epoch (see the :mod:`time` module). Raise
104 :exc:`os.error` if the file does not exist or is inaccessible.
106 .. versionadded:: 1.5.2
108 .. versionchanged:: 2.3
109 If :func:`os.stat_float_times` returns True, the result is a floating point
113 .. function:: getmtime(path)
115 Return the time of last modification of *path*. The return value is a number
116 giving the number of seconds since the epoch (see the :mod:`time` module).
117 Raise :exc:`os.error` if the file does not exist or is inaccessible.
119 .. versionadded:: 1.5.2
121 .. versionchanged:: 2.3
122 If :func:`os.stat_float_times` returns True, the result is a floating point
126 .. function:: getctime(path)
128 Return the system's ctime which, on some systems (like Unix) is the time of the
129 last change, and, on others (like Windows), is the creation time for *path*.
130 The return value is a number giving the number of seconds since the epoch (see
131 the :mod:`time` module). Raise :exc:`os.error` if the file does not exist or
134 .. versionadded:: 2.3
137 .. function:: getsize(path)
139 Return the size, in bytes, of *path*. Raise :exc:`os.error` if the file does
140 not exist or is inaccessible.
142 .. versionadded:: 1.5.2
145 .. function:: isabs(path)
147 Return ``True`` if *path* is an absolute pathname (begins with a slash).
150 .. function:: isfile(path)
152 Return ``True`` if *path* is an existing regular file. This follows symbolic
153 links, so both :func:`islink` and :func:`isfile` can be true for the same path.
156 .. function:: isdir(path)
158 Return ``True`` if *path* is an existing directory. This follows symbolic
159 links, so both :func:`islink` and :func:`isdir` can be true for the same path.
162 .. function:: islink(path)
164 Return ``True`` if *path* refers to a directory entry that is a symbolic link.
165 Always ``False`` if symbolic links are not supported.
168 .. function:: ismount(path)
170 Return ``True`` if pathname *path* is a :dfn:`mount point`: a point in a file
171 system where a different file system has been mounted. The function checks
172 whether *path*'s parent, :file:`path/..`, is on a different device than *path*,
173 or whether :file:`path/..` and *path* point to the same i-node on the same
174 device --- this should detect mount points for all Unix and POSIX variants.
177 .. function:: join(path1[, path2[, ...]])
179 Join one or more path components intelligently. If any component is an absolute
180 path, all previous components (on Windows, including the previous drive letter,
181 if there was one) are thrown away, and joining continues. The return value is
182 the concatenation of *path1*, and optionally *path2*, etc., with exactly one
183 directory separator (``os.sep``) inserted between components, unless *path2* is
184 empty. Note that on Windows, since there is a current directory for each drive,
185 ``os.path.join("c:", "foo")`` represents a path relative to the current
186 directory on drive :file:`C:` (:file:`c:foo`), not :file:`c:\\foo`.
189 .. function:: normcase(path)
191 Normalize the case of a pathname. On Unix, this returns the path unchanged; on
192 case-insensitive filesystems, it converts the path to lowercase. On Windows, it
193 also converts forward slashes to backward slashes.
196 .. function:: normpath(path)
198 Normalize a pathname. This collapses redundant separators and up-level
199 references so that ``A//B``, ``A/./B`` and ``A/foo/../B`` all become ``A/B``.
200 It does not normalize the case (use :func:`normcase` for that). On Windows, it
201 converts forward slashes to backward slashes. It should be understood that this
202 may change the meaning of the path if it contains symbolic links!
205 .. function:: realpath(path)
207 Return the canonical path of the specified filename, eliminating any symbolic
208 links encountered in the path (if they are supported by the operating system).
210 .. versionadded:: 2.2
213 .. function:: relpath(path[, start])
215 Return a relative filepath to *path* either from the current directory or from
216 an optional *start* point.
218 *start* defaults to :attr:`os.curdir`. Availability: Windows, Unix.
220 .. versionadded:: 2.6
223 .. function:: samefile(path1, path2)
225 Return ``True`` if both pathname arguments refer to the same file or directory
226 (as indicated by device number and i-node number). Raise an exception if a
227 :func:`os.stat` call on either pathname fails. Availability: Macintosh, Unix.
230 .. function:: sameopenfile(fp1, fp2)
232 Return ``True`` if the file descriptors *fp1* and *fp2* refer to the same file.
233 Availability: Macintosh, Unix.
236 .. function:: samestat(stat1, stat2)
238 Return ``True`` if the stat tuples *stat1* and *stat2* refer to the same file.
239 These structures may have been returned by :func:`fstat`, :func:`lstat`, or
240 :func:`stat`. This function implements the underlying comparison used by
241 :func:`samefile` and :func:`sameopenfile`. Availability: Macintosh, Unix.
244 .. function:: split(path)
246 Split the pathname *path* into a pair, ``(head, tail)`` where *tail* is the last
247 pathname component and *head* is everything leading up to that. The *tail* part
248 will never contain a slash; if *path* ends in a slash, *tail* will be empty. If
249 there is no slash in *path*, *head* will be empty. If *path* is empty, both
250 *head* and *tail* are empty. Trailing slashes are stripped from *head* unless
251 it is the root (one or more slashes only). In nearly all cases, ``join(head,
252 tail)`` equals *path* (the only exception being when there were multiple slashes
253 separating *head* from *tail*).
256 .. function:: splitdrive(path)
258 Split the pathname *path* into a pair ``(drive, tail)`` where *drive* is either
259 a drive specification or the empty string. On systems which do not use drive
260 specifications, *drive* will always be the empty string. In all cases, ``drive
261 + tail`` will be the same as *path*.
263 .. versionadded:: 1.3
266 .. function:: splitext(path)
268 Split the pathname *path* into a pair ``(root, ext)`` such that ``root + ext ==
269 path``, and *ext* is empty or begins with a period and contains at most one
270 period. Leading periods on the basename are ignored; ``splitext('.cshrc')``
271 returns ``('.cshrc', '')``.
273 .. versionchanged:: 2.6
274 Earlier versions could produce an empty root when the only period was the
278 .. function:: splitunc(path)
280 Split the pathname *path* into a pair ``(unc, rest)`` so that *unc* is the UNC
281 mount point (such as ``r'\\host\mount'``), if present, and *rest* the rest of
282 the path (such as ``r'\path\file.ext'``). For paths containing drive letters,
283 *unc* will always be the empty string. Availability: Windows.
286 .. function:: walk(path, visit, arg)
288 Calls the function *visit* with arguments ``(arg, dirname, names)`` for each
289 directory in the directory tree rooted at *path* (including *path* itself, if it
290 is a directory). The argument *dirname* specifies the visited directory, the
291 argument *names* lists the files in the directory (gotten from
292 ``os.listdir(dirname)``). The *visit* function may modify *names* to influence
293 the set of directories visited below *dirname*, e.g. to avoid visiting certain
294 parts of the tree. (The object referred to by *names* must be modified in
295 place, using :keyword:`del` or slice assignment.)
299 Symbolic links to directories are not treated as subdirectories, and that
300 :func:`walk` therefore will not visit them. To visit linked directories you must
301 identify them with ``os.path.islink(file)`` and ``os.path.isdir(file)``, and
302 invoke :func:`walk` as necessary.
306 The newer :func:`os.walk` :term:`generator` supplies similar functionality
307 and can be easier to use.
310 .. data:: supports_unicode_filenames
312 True if arbitrary Unicode strings can be used as file names (within limitations
313 imposed by the file system), and if :func:`os.listdir` returns Unicode strings
314 for a Unicode argument.
316 .. versionadded:: 2.3