/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
  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
 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``) 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`.
203
204
205.. function:: normcase(path)
206
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.
210
211
212.. function:: normpath(path)
213
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!
219
220
221.. function:: realpath(path)
222
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).
225
226   .. versionadded:: 2.2
227
228
229.. function:: relpath(path[, start])
230
231   Return a relative filepath to *path* either from the current directory or from
232   an optional *start* point.
233
234   *start* defaults to :attr:`os.curdir`. Availability:  Windows, Unix.
235
236   .. versionadded:: 2.6
237
238
239.. function:: samefile(path1, path2)
240
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.
244
245
246.. function:: sameopenfile(fp1, fp2)
247
248   Return ``True`` if the file descriptors *fp1* and *fp2* refer to the same file.
249   Availability: Unix.
250
251
252.. function:: samestat(stat1, stat2)
253
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.
258
259
260.. function:: split(path)
261
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*).
270
271
272.. function:: splitdrive(path)
273
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*.
278
279   .. versionadded:: 1.3
280
281
282.. function:: splitext(path)
283
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', '')``.
288
289   .. versionchanged:: 2.6
290      Earlier versions could produce an empty root when the only period was the
291      first character.
292
293
294.. function:: splitunc(path)
295
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.
300
301
302.. function:: walk(path, visit, arg)
303
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.)
312
313   .. note::
314
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.
319
320   .. note::
321
322      This function is deprecated and has been removed in 3.0 in favor of
323      :func:`os.walk`.
324
325
326.. data:: supports_unicode_filenames
327
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.
331
332   .. versionadded:: 2.3
333