rest25/library/os.path.rst => rest262/library/os.path.rst
n1- 
2:mod:`os.path` --- Common pathname manipulations
3================================================
4
5.. module:: os.path
n6- 
n5+   :synopsis: Operations on pathnames.
7- 
8- 
9
10.. index:: single: path; operations
11
n12-This module implements some useful functions on pathnames.
n9+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
14.. warning::
15
16   On Windows, many of these functions do not properly support UNC pathnames.
17   :func:`splitunc` and :func:`ismount` do handle them correctly.
n17+ 
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
18
19
20.. function:: abspath(path)
21
22   Return a normalized absolutized version of the pathname *path*. On most
23   platforms, this is equivalent to ``normpath(join(os.getcwd(), path))``.
24
25   .. versionadded:: 1.5.2
61   broken symbolic links.   Equivalent to :func:`exists` on platforms lacking
62   :func:`os.lstat`.
63
64   .. versionadded:: 2.4
65
66
67.. function:: expanduser(path)
68
n84+   On Unix and Windows, return the argument with an initial component of ``~`` or
85+   ``~user`` replaced by that *user*'s home directory.
86+ 
69   .. index:: module: pwd
70
n71-   On Unix, return the argument with an initial component of ``~`` or ``~user``
n89+   On Unix, an initial ``~`` is replaced by the environment variable :envvar:`HOME`
72-   replaced by that *user*'s home directory. An initial ``~`` is replaced by the
90+   if it is set; otherwise the current user's home directory is looked up in the
73-   environment variable :envvar:`HOME` if it is set; otherwise the current user's
91+   password directory through the built-in module :mod:`pwd`. An initial ``~user``
74-   home directory is looked up in the password directory through the built-in
92+   is looked up directly in the password directory.
75-   module :mod:`pwd`. An initial ``~user`` is looked up directly in the password
76-   directory.
77
n78-   On Windows, only ``~`` is supported; it is replaced by the environment variable
n94+   On Windows, :envvar:`HOME` and :envvar:`USERPROFILE` will be used if set,
79-   :envvar:`HOME` or by a combination of :envvar:`HOMEDRIVE` and
95+   otherwise a combination of :envvar:`HOMEPATH` and :envvar:`HOMEDRIVE` will be
80-   :envvar:`HOMEPATH`.
96+   used.  An initial ``~user`` is handled by stripping the last directory component
97+   from the created user path derived above.
81
82   If the expansion fails or if the path does not begin with a tilde, the path is
83   returned unchanged.
84
85
86.. function:: expandvars(path)
87
88   Return the argument with environment variables expanded.  Substrings of the form
89   ``$name`` or ``${name}`` are replaced by the value of environment variable
90   *name*.  Malformed variable names and references to non-existing variables are
91   left unchanged.
n109+ 
110+   On Windows, ``%name%`` expansions are supported in addition to ``$name`` and
111+   ``${name}``.
92
93
94.. function:: getatime(path)
95
96   Return the time of last access of *path*.  The return value is a number giving
97   the number of seconds since the epoch (see the  :mod:`time` module).  Raise
98   :exc:`os.error` if the file does not exist or is inaccessible.
99
133   Return the size, in bytes, of *path*.  Raise :exc:`os.error` if the file does
134   not exist or is inaccessible.
135
136   .. versionadded:: 1.5.2
137
138
139.. function:: isabs(path)
140
n141-   Return ``True`` if *path* is an absolute pathname (begins with a slash).
n161+   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.
142
143
144.. function:: isfile(path)
145
146   Return ``True`` if *path* is an existing regular file.  This follows symbolic
147   links, so both :func:`islink` and :func:`isfile` can be true for the same path.
148
149
171.. function:: join(path1[, path2[, ...]])
172
173   Join one or more path components intelligently.  If any component is an absolute
174   path, all previous components (on Windows, including the previous drive letter,
175   if there was one) are thrown away, and joining continues.  The return value is
176   the concatenation of *path1*, and optionally *path2*, etc., with exactly one
177   directory separator (``os.sep``) inserted between components, unless *path2* is
178   empty.  Note that on Windows, since there is a current directory for each drive,
n179-   :func:`os.path.join("c:", "foo")` represents a path relative to the current
n201+   ``os.path.join("c:", "foo")`` represents a path relative to the current
180-   directory on drive :file:`C:` (:file:`c:foo`), not :file:`c:\\\\foo`.
202+   directory on drive :file:`C:` (:file:`c:foo`), not :file:`c:\\foo`.
181
182
183.. function:: normcase(path)
184
n185-   Normalize the case of a pathname.  On Unix, this returns the path unchanged; on
n207+   Normalize the case of a pathname.  On Unix and Mac OS X, this returns the
186-   case-insensitive filesystems, it converts the path to lowercase.  On Windows, it
208+   path unchanged; on case-insensitive filesystems, it converts the path to
187-   also converts forward slashes to backward slashes.
209+   lowercase.  On Windows, it also converts forward slashes to backward slashes.
188
189
190.. function:: normpath(path)
191
192   Normalize a pathname.  This collapses redundant separators and up-level
193   references so that ``A//B``, ``A/./B`` and ``A/foo/../B`` all become ``A/B``.
194   It does not normalize the case (use :func:`normcase` for that).  On Windows, it
195   converts forward slashes to backward slashes. It should be understood that this
199.. function:: realpath(path)
200
201   Return the canonical path of the specified filename, eliminating any symbolic
202   links encountered in the path (if they are supported by the operating system).
203
204   .. versionadded:: 2.2
205
206
n229+.. 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+ 
207.. function:: samefile(path1, path2)
208
209   Return ``True`` if both pathname arguments refer to the same file or directory
210   (as indicated by device number and i-node number). Raise an exception if a
n211-   :func:`os.stat` call on either pathname fails. Availability:  Macintosh, Unix.
n243+   :func:`os.stat` call on either pathname fails. Availability: Unix.
212
213
214.. function:: sameopenfile(fp1, fp2)
215
216   Return ``True`` if the file descriptors *fp1* and *fp2* refer to the same file.
n217-   Availability:  Macintosh, Unix.
n249+   Availability: Unix.
218
219
220.. function:: samestat(stat1, stat2)
221
222   Return ``True`` if the stat tuples *stat1* and *stat2* refer to the same file.
223   These structures may have been returned by :func:`fstat`, :func:`lstat`, or
224   :func:`stat`.  This function implements the underlying comparison used by
n225-   :func:`samefile` and :func:`sameopenfile`. Availability:  Macintosh, Unix.
n257+   :func:`samefile` and :func:`sameopenfile`. Availability: Unix.
226
227
228.. function:: split(path)
229
230   Split the pathname *path* into a pair, ``(head, tail)`` where *tail* is the last
231   pathname component and *head* is everything leading up to that.  The *tail* part
232   will never contain a slash; if *path* ends in a slash, *tail* will be empty.  If
233   there is no slash in *path*, *head* will be empty.  If *path* is empty, both
246
247   .. versionadded:: 1.3
248
249
250.. function:: splitext(path)
251
252   Split the pathname *path* into a pair ``(root, ext)``  such that ``root + ext ==
253   path``, and *ext* is empty or begins with a period and contains at most one
n254-   period.
n286+   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.
255
256
257.. function:: splitunc(path)
258
259   Split the pathname *path* into a pair ``(unc, rest)`` so that *unc* is the UNC
260   mount point (such as ``r'\\host\mount'``), if present, and *rest* the rest of
261   the path (such as  ``r'\path\file.ext'``).  For paths containing drive letters,
262   *unc* will always be the empty string. Availability:  Windows.
275
276   .. note::
277
278      Symbolic links to directories are not treated as subdirectories, and that
279      :func:`walk` therefore will not visit them. To visit linked directories you must
280      identify them with ``os.path.islink(file)`` and ``os.path.isdir(file)``, and
281      invoke :func:`walk` as necessary.
282
n283-   .. note::
n320+   .. warning::
284
t285-      The newer :func:`os.walk` generator supplies similar functionality and can be
t322+      This function is deprecated and has been removed in 3.0 in favor of
286-      easier to use.
323+      :func:`os.walk`.
287
288
289.. data:: supports_unicode_filenames
290
291   True if arbitrary Unicode strings can be used as file names (within limitations
292   imposed by the file system), and if :func:`os.listdir` returns Unicode strings
293   for a Unicode argument.
294
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op