Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libposixpath.tex @ 27998:e27f58a50737 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
SF bug #690377: Dud footnote reference in distutils docs
author Raymond Hettinger <python@rcn.com>
date Fri, 21 Feb 2003 02:47:09 +0000
parents d698c5623da0
children 60e722384d62
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
10063
8ffe450428b1 Make the text generic, and call it os.path instead of posixpath.
Fred Drake <fdrake@acm.org>
parents: 10017
diff changeset
1 \section{\module{os.path} ---
8ffe450428b1 Make the text generic, and call it os.path instead of posixpath.
Fred Drake <fdrake@acm.org>
parents: 10017
diff changeset
2 Common pathname manipulations}
8ffe450428b1 Make the text generic, and call it os.path instead of posixpath.
Fred Drake <fdrake@acm.org>
parents: 10017
diff changeset
3 \declaremodule{standard}{os.path}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
4
10063
8ffe450428b1 Make the text generic, and call it os.path instead of posixpath.
Fred Drake <fdrake@acm.org>
parents: 10017
diff changeset
5 \modulesynopsis{Common pathname manipulations.}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
6
10063
8ffe450428b1 Make the text generic, and call it os.path instead of posixpath.
Fred Drake <fdrake@acm.org>
parents: 10017
diff changeset
7 This module implements some useful functions on pathnames.
8ffe450428b1 Make the text generic, and call it os.path instead of posixpath.
Fred Drake <fdrake@acm.org>
parents: 10017
diff changeset
8 \index{path!operations}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
9
20580
376ee174ecd0 Use the \note and \warning macros where appropriate.
Fred Drake <fdrake@acm.org>
parents: 20145
diff changeset
10 \warning{On Windows, many of these functions do not properly
20145
c6fc87810551 Added note about non-support of UNC paths on Windows.
Fred Drake <fdrake@acm.org>
parents: 19934
diff changeset
11 support UNC pathnames. \function{splitunc()} and \function{ismount()}
20580
376ee174ecd0 Use the \note and \warning macros where appropriate.
Fred Drake <fdrake@acm.org>
parents: 20145
diff changeset
12 do handle them correctly.}
20145
c6fc87810551 Added note about non-support of UNC paths on Windows.
Fred Drake <fdrake@acm.org>
parents: 19934
diff changeset
13
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
14
10079
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
15 \begin{funcdesc}{abspath}{path}
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
16 Return a normalized absolutized version of the pathname \var{path}.
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
17 On most platforms, this is equivalent to
11386
1466280e6bb0 Fixed typo in explanation of abspath(); noticed by Paul Prescod
Fred Drake <fdrake@acm.org>
parents: 10415
diff changeset
18 \code{normpath(join(os.getcwd(), \var{path}))}.
10415
48fbc55c0553 Note that abspath() was added in 1.5.2.
Fred Drake <fdrake@acm.org>
parents: 10243
diff changeset
19 \versionadded{1.5.2}
10017
f2457d697a2a Document abspath() (implementation is forthcoming).
Guido van Rossum <guido@python.org>
parents: 8918
diff changeset
20 \end{funcdesc}
f2457d697a2a Document abspath() (implementation is forthcoming).
Guido van Rossum <guido@python.org>
parents: 8918
diff changeset
21
10079
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
22 \begin{funcdesc}{basename}{path}
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
23 Return the base name of pathname \var{path}. This is the second half
15351
a6224da7b4e4 Explained that os.path.basename() may return something different from the
Fred Drake <fdrake@acm.org>
parents: 14134
diff changeset
24 of the pair returned by \code{split(\var{path})}. Note that the
a6224da7b4e4 Explained that os.path.basename() may return something different from the
Fred Drake <fdrake@acm.org>
parents: 14134
diff changeset
25 result of this function is different from the
a6224da7b4e4 Explained that os.path.basename() may return something different from the
Fred Drake <fdrake@acm.org>
parents: 14134
diff changeset
26 \UNIX{} \program{basename} program; where \program{basename} for
a6224da7b4e4 Explained that os.path.basename() may return something different from the
Fred Drake <fdrake@acm.org>
parents: 14134
diff changeset
27 \code{'/foo/bar/'} returns \code{'bar'}, the \function{basename()}
a6224da7b4e4 Explained that os.path.basename() may return something different from the
Fred Drake <fdrake@acm.org>
parents: 14134
diff changeset
28 function returns an empty string (\code{''}).
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
29 \end{funcdesc}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
30
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
31 \begin{funcdesc}{commonprefix}{list}
14134
76e73389c340 update commonprefix doc to make sure user is aware it works
Skip Montanaro <skip@pobox.com>
parents: 12223
diff changeset
32 Return the longest path prefix (taken character-by-character) that is a
76e73389c340 update commonprefix doc to make sure user is aware it works
Skip Montanaro <skip@pobox.com>
parents: 12223
diff changeset
33 prefix of all paths in
10063
8ffe450428b1 Make the text generic, and call it os.path instead of posixpath.
Fred Drake <fdrake@acm.org>
parents: 10017
diff changeset
34 \var{list}. If \var{list} is empty, return the empty string
14134
76e73389c340 update commonprefix doc to make sure user is aware it works
Skip Montanaro <skip@pobox.com>
parents: 12223
diff changeset
35 (\code{''}). Note that this may return invalid paths because it works a
76e73389c340 update commonprefix doc to make sure user is aware it works
Skip Montanaro <skip@pobox.com>
parents: 12223
diff changeset
36 character at a time.
10063
8ffe450428b1 Make the text generic, and call it os.path instead of posixpath.
Fred Drake <fdrake@acm.org>
parents: 10017
diff changeset
37 \end{funcdesc}
8ffe450428b1 Make the text generic, and call it os.path instead of posixpath.
Fred Drake <fdrake@acm.org>
parents: 10017
diff changeset
38
10079
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
39 \begin{funcdesc}{dirname}{path}
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
40 Return the directory name of pathname \var{path}. This is the first
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
41 half of the pair returned by \code{split(\var{path})}.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
42 \end{funcdesc}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
43
10079
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
44 \begin{funcdesc}{exists}{path}
22835
73d145bfd8e4 Update doc to reflect Tim's changes to bool.
Neal Norwitz <nnorwitz@gmail.com>
parents: 21062
diff changeset
45 Return \code{True} if \var{path} refers to an existing path.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
46 \end{funcdesc}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
47
10079
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
48 \begin{funcdesc}{expanduser}{path}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
49 Return the argument with an initial component of \samp{\~} or
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
50 \samp{\~\var{user}} replaced by that \var{user}'s home directory. An
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
51 initial \samp{\~{}} is replaced by the environment variable
8851
534a1a437af3 Markup nit.
Fred Drake <fdrake@acm.org>
parents: 8766
diff changeset
52 \envvar{HOME}; an initial \samp{\~\var{user}} is looked up in the
534a1a437af3 Markup nit.
Fred Drake <fdrake@acm.org>
parents: 8766
diff changeset
53 password directory through the built-in module
10063
8ffe450428b1 Make the text generic, and call it os.path instead of posixpath.
Fred Drake <fdrake@acm.org>
parents: 10017
diff changeset
54 \refmodule{pwd}\refbimodindex{pwd}. If the expansion fails, or if the
8ffe450428b1 Make the text generic, and call it os.path instead of posixpath.
Fred Drake <fdrake@acm.org>
parents: 10017
diff changeset
55 path does not begin with a tilde, the path is returned unchanged. On
10079
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
56 the Macintosh, this always returns \var{path} unchanged.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
57 \end{funcdesc}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
58
10079
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
59 \begin{funcdesc}{expandvars}{path}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
60 Return the argument with environment variables expanded. Substrings
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
61 of the form \samp{\$\var{name}} or \samp{\$\{\var{name}\}} are
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
62 replaced by the value of environment variable \var{name}. Malformed
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
63 variable names and references to non-existing variables are left
10079
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
64 unchanged. On the Macintosh, this always returns \var{path}
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
65 unchanged.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
66 \end{funcdesc}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
67
10243
575c4ea2542b Fix an amazing number of typos & malformed sentences reported by Detlef
Fred Drake <fdrake@acm.org>
parents: 10166
diff changeset
68 \begin{funcdesc}{getatime}{path}
26948
be732e219ed1 Use the name (path) specified in the parameter list
Neal Norwitz <nnorwitz@gmail.com>
parents: 26946
diff changeset
69 Return the time of last access of \var{path}. The return
26946
acdb39b714b1 Patch #658927: Add getctime to os.path.
Martin v. Löwis <martin@v.loewis.de>
parents: 26595
diff changeset
70 value is a number giving the number of seconds since the epoch (see the
10243
575c4ea2542b Fix an amazing number of typos & malformed sentences reported by Detlef
Fred Drake <fdrake@acm.org>
parents: 10166
diff changeset
71 \refmodule{time} module). Raise \exception{os.error} if the file does
575c4ea2542b Fix an amazing number of typos & malformed sentences reported by Detlef
Fred Drake <fdrake@acm.org>
parents: 10166
diff changeset
72 not exist or is inaccessible.
10079
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
73 \versionadded{1.5.2}
26946
acdb39b714b1 Patch #658927: Add getctime to os.path.
Martin v. Löwis <martin@v.loewis.de>
parents: 26595
diff changeset
74 \versionchanged[If \function{os.stat_float_times()} returns True, the result is a floating point number]{2.3}
8747
cd99520320a3 Document getsize(), getmtime(), getatime().
Guido van Rossum <guido@python.org>
parents: 8730
diff changeset
75 \end{funcdesc}
cd99520320a3 Document getsize(), getmtime(), getatime().
Guido van Rossum <guido@python.org>
parents: 8730
diff changeset
76
10079
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
77 \begin{funcdesc}{getmtime}{path}
26948
be732e219ed1 Use the name (path) specified in the parameter list
Neal Norwitz <nnorwitz@gmail.com>
parents: 26946
diff changeset
78 Return the time of last modification of \var{path}. The return
26946
acdb39b714b1 Patch #658927: Add getctime to os.path.
Martin v. Löwis <martin@v.loewis.de>
parents: 26595
diff changeset
79 value is a number giving the number of seconds since the epoch (see the
10063
8ffe450428b1 Make the text generic, and call it os.path instead of posixpath.
Fred Drake <fdrake@acm.org>
parents: 10017
diff changeset
80 \refmodule{time} module). Raise \exception{os.error} if the file does
8ffe450428b1 Make the text generic, and call it os.path instead of posixpath.
Fred Drake <fdrake@acm.org>
parents: 10017
diff changeset
81 not exist or is inaccessible.
10079
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
82 \versionadded{1.5.2}
26946
acdb39b714b1 Patch #658927: Add getctime to os.path.
Martin v. Löwis <martin@v.loewis.de>
parents: 26595
diff changeset
83 \versionchanged[If \function{os.stat_float_times()} returns True, the result is a floating point number]{2.3}
acdb39b714b1 Patch #658927: Add getctime to os.path.
Martin v. Löwis <martin@v.loewis.de>
parents: 26595
diff changeset
84 \end{funcdesc}
acdb39b714b1 Patch #658927: Add getctime to os.path.
Martin v. Löwis <martin@v.loewis.de>
parents: 26595
diff changeset
85
acdb39b714b1 Patch #658927: Add getctime to os.path.
Martin v. Löwis <martin@v.loewis.de>
parents: 26595
diff changeset
86 \begin{funcdesc}{getctime}{path}
26948
be732e219ed1 Use the name (path) specified in the parameter list
Neal Norwitz <nnorwitz@gmail.com>
parents: 26946
diff changeset
87 Return the time of creation of \var{path}. The return
26946
acdb39b714b1 Patch #658927: Add getctime to os.path.
Martin v. Löwis <martin@v.loewis.de>
parents: 26595
diff changeset
88 value is a number giving the number of seconds since the epoch (see the
acdb39b714b1 Patch #658927: Add getctime to os.path.
Martin v. Löwis <martin@v.loewis.de>
parents: 26595
diff changeset
89 \refmodule{time} module). Raise \exception{os.error} if the file does
acdb39b714b1 Patch #658927: Add getctime to os.path.
Martin v. Löwis <martin@v.loewis.de>
parents: 26595
diff changeset
90 not exist or is inaccessible.
acdb39b714b1 Patch #658927: Add getctime to os.path.
Martin v. Löwis <martin@v.loewis.de>
parents: 26595
diff changeset
91 \versionadded{2.3}
8747
cd99520320a3 Document getsize(), getmtime(), getatime().
Guido van Rossum <guido@python.org>
parents: 8730
diff changeset
92 \end{funcdesc}
cd99520320a3 Document getsize(), getmtime(), getatime().
Guido van Rossum <guido@python.org>
parents: 8730
diff changeset
93
10243
575c4ea2542b Fix an amazing number of typos & malformed sentences reported by Detlef
Fred Drake <fdrake@acm.org>
parents: 10166
diff changeset
94 \begin{funcdesc}{getsize}{path}
26948
be732e219ed1 Use the name (path) specified in the parameter list
Neal Norwitz <nnorwitz@gmail.com>
parents: 26946
diff changeset
95 Return the size, in bytes, of \var{path}. Raise
10243
575c4ea2542b Fix an amazing number of typos & malformed sentences reported by Detlef
Fred Drake <fdrake@acm.org>
parents: 10166
diff changeset
96 \exception{os.error} if the file does not exist or is inaccessible.
10079
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
97 \versionadded{1.5.2}
8747
cd99520320a3 Document getsize(), getmtime(), getatime().
Guido van Rossum <guido@python.org>
parents: 8730
diff changeset
98 \end{funcdesc}
cd99520320a3 Document getsize(), getmtime(), getatime().
Guido van Rossum <guido@python.org>
parents: 8730
diff changeset
99
10079
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
100 \begin{funcdesc}{isabs}{path}
22835
73d145bfd8e4 Update doc to reflect Tim's changes to bool.
Neal Norwitz <nnorwitz@gmail.com>
parents: 21062
diff changeset
101 Return \code{True} if \var{path} is an absolute pathname (begins with a
10079
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
102 slash).
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
103 \end{funcdesc}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
104
10079
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
105 \begin{funcdesc}{isfile}{path}
22835
73d145bfd8e4 Update doc to reflect Tim's changes to bool.
Neal Norwitz <nnorwitz@gmail.com>
parents: 21062
diff changeset
106 Return \code{True} if \var{path} is an existing regular file. This follows
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
107 symbolic links, so both \function{islink()} and \function{isfile()}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
108 can be true for the same path.
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
109 \end{funcdesc}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
110
10079
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
111 \begin{funcdesc}{isdir}{path}
22835
73d145bfd8e4 Update doc to reflect Tim's changes to bool.
Neal Norwitz <nnorwitz@gmail.com>
parents: 21062
diff changeset
112 Return \code{True} if \var{path} is an existing directory. This follows
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
113 symbolic links, so both \function{islink()} and \function{isdir()} can
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
114 be true for the same path.
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
115 \end{funcdesc}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
116
10079
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
117 \begin{funcdesc}{islink}{path}
22835
73d145bfd8e4 Update doc to reflect Tim's changes to bool.
Neal Norwitz <nnorwitz@gmail.com>
parents: 21062
diff changeset
118 Return \code{True} if \var{path} refers to a directory entry that is a
73d145bfd8e4 Update doc to reflect Tim's changes to bool.
Neal Norwitz <nnorwitz@gmail.com>
parents: 21062
diff changeset
119 symbolic link. Always \code{False} if symbolic links are not supported.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
120 \end{funcdesc}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
121
10079
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
122 \begin{funcdesc}{ismount}{path}
22835
73d145bfd8e4 Update doc to reflect Tim's changes to bool.
Neal Norwitz <nnorwitz@gmail.com>
parents: 21062
diff changeset
123 Return \code{True} if pathname \var{path} is a \dfn{mount point}: a point in
10079
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
124 a file system where a different file system has been mounted. The
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
125 function checks whether \var{path}'s parent, \file{\var{path}/..}, is
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
126 on a different device than \var{path}, or whether \file{\var{path}/..}
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
127 and \var{path} point to the same i-node on the same device --- this
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
128 should detect mount points for all \UNIX{} and \POSIX{} variants.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
129 \end{funcdesc}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
130
10079
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
131 \begin{funcdesc}{join}{path1\optional{, path2\optional{, ...}}}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
132 Joins one or more path components intelligently. If any component is
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
133 an absolute path, all previous components are thrown away, and joining
10079
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
134 continues. The return value is the concatenation of \var{path1}, and
25237
a0f6419cb13f Minor revision to the "\\" patch, including updating the docs a little to
Fred Drake <fdrake@acm.org>
parents: 25236
diff changeset
135 optionally \var{path2}, etc., with exactly one directory separator
26595
c35768d7883e Patch #651006: Better explain what component might be empty.
Martin v. Löwis <martin@v.loewis.de>
parents: 25666
diff changeset
136 (\code{os.sep}) inserted between components, unless \var{path2} is
25237
a0f6419cb13f Minor revision to the "\\" patch, including updating the docs a little to
Fred Drake <fdrake@acm.org>
parents: 25236
diff changeset
137 empty. Note that on Windows, since there is a current directory for
a0f6419cb13f Minor revision to the "\\" patch, including updating the docs a little to
Fred Drake <fdrake@acm.org>
parents: 25236
diff changeset
138 each drive, \function{os.path.join("c:", "foo")} represents a path
a0f6419cb13f Minor revision to the "\\" patch, including updating the docs a little to
Fred Drake <fdrake@acm.org>
parents: 25236
diff changeset
139 relative to the current directory on drive \file{C:} (\file{c:foo}), not
a0f6419cb13f Minor revision to the "\\" patch, including updating the docs a little to
Fred Drake <fdrake@acm.org>
parents: 25236
diff changeset
140 \file{c:\textbackslash\textbackslash foo}.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
141 \end{funcdesc}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
142
10079
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
143 \begin{funcdesc}{normcase}{path}
21062
bc02c3b09626 Clean up some markup cruft. A number of the macros that take no
Fred Drake <fdrake@acm.org>
parents: 20580
diff changeset
144 Normalize the case of a pathname. On \UNIX, this returns the path
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
145 unchanged; on case-insensitive filesystems, it converts the path to
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
146 lowercase. On Windows, it also converts forward slashes to backward
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
147 slashes.
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
148 \end{funcdesc}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
149
10079
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
150 \begin{funcdesc}{normpath}{path}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
151 Normalize a pathname. This collapses redundant separators and
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
152 up-level references, e.g. \code{A//B}, \code{A/./B} and
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
153 \code{A/foo/../B} all become \code{A/B}. It does not normalize the
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11386
diff changeset
154 case (use \function{normcase()} for that). On Windows, it converts
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11386
diff changeset
155 forward slashes to backward slashes.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
156 \end{funcdesc}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
157
19934
f2f25a738f7f SF patch #461781 by Chris Lawrence: os.path.realpath - Resolve symlinks:
Guido van Rossum <guido@python.org>
parents: 17967
diff changeset
158 \begin{funcdesc}{realpath}{path}
f2f25a738f7f SF patch #461781 by Chris Lawrence: os.path.realpath - Resolve symlinks:
Guido van Rossum <guido@python.org>
parents: 17967
diff changeset
159 Return the canonical path of the specified filename, eliminating any
f2f25a738f7f SF patch #461781 by Chris Lawrence: os.path.realpath - Resolve symlinks:
Guido van Rossum <guido@python.org>
parents: 17967
diff changeset
160 symbolic links encountered in the path.
21062
bc02c3b09626 Clean up some markup cruft. A number of the macros that take no
Fred Drake <fdrake@acm.org>
parents: 20580
diff changeset
161 Availability: \UNIX.
19934
f2f25a738f7f SF patch #461781 by Chris Lawrence: os.path.realpath - Resolve symlinks:
Guido van Rossum <guido@python.org>
parents: 17967
diff changeset
162 \versionadded{2.2}
f2f25a738f7f SF patch #461781 by Chris Lawrence: os.path.realpath - Resolve symlinks:
Guido van Rossum <guido@python.org>
parents: 17967
diff changeset
163 \end{funcdesc}
f2f25a738f7f SF patch #461781 by Chris Lawrence: os.path.realpath - Resolve symlinks:
Guido van Rossum <guido@python.org>
parents: 17967
diff changeset
164
10079
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
165 \begin{funcdesc}{samefile}{path1, path2}
22835
73d145bfd8e4 Update doc to reflect Tim's changes to bool.
Neal Norwitz <nnorwitz@gmail.com>
parents: 21062
diff changeset
166 Return \code{True} if both pathname arguments refer to the same file or
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
167 directory (as indicated by device number and i-node number).
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
168 Raise an exception if a \function{os.stat()} call on either pathname
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
169 fails.
21062
bc02c3b09626 Clean up some markup cruft. A number of the macros that take no
Fred Drake <fdrake@acm.org>
parents: 20580
diff changeset
170 Availability: Macintosh, \UNIX.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
171 \end{funcdesc}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
172
10096
3ae03b9b65ed Document sameopenfile(), samestat().
Fred Drake <fdrake@acm.org>
parents: 10095
diff changeset
173 \begin{funcdesc}{sameopenfile}{fp1, fp2}
22835
73d145bfd8e4 Update doc to reflect Tim's changes to bool.
Neal Norwitz <nnorwitz@gmail.com>
parents: 21062
diff changeset
174 Return \code{True} if the file objects \var{fp1} and \var{fp2} refer to the
10096
3ae03b9b65ed Document sameopenfile(), samestat().
Fred Drake <fdrake@acm.org>
parents: 10095
diff changeset
175 same file. The two file objects may represent different file
3ae03b9b65ed Document sameopenfile(), samestat().
Fred Drake <fdrake@acm.org>
parents: 10095
diff changeset
176 descriptors.
21062
bc02c3b09626 Clean up some markup cruft. A number of the macros that take no
Fred Drake <fdrake@acm.org>
parents: 20580
diff changeset
177 Availability: Macintosh, \UNIX.
10096
3ae03b9b65ed Document sameopenfile(), samestat().
Fred Drake <fdrake@acm.org>
parents: 10095
diff changeset
178 \end{funcdesc}
3ae03b9b65ed Document sameopenfile(), samestat().
Fred Drake <fdrake@acm.org>
parents: 10095
diff changeset
179
3ae03b9b65ed Document sameopenfile(), samestat().
Fred Drake <fdrake@acm.org>
parents: 10095
diff changeset
180 \begin{funcdesc}{samestat}{stat1, stat2}
22835
73d145bfd8e4 Update doc to reflect Tim's changes to bool.
Neal Norwitz <nnorwitz@gmail.com>
parents: 21062
diff changeset
181 Return \code{True} if the stat tuples \var{stat1} and \var{stat2} refer to
10096
3ae03b9b65ed Document sameopenfile(), samestat().
Fred Drake <fdrake@acm.org>
parents: 10095
diff changeset
182 the same file. These structures may have been returned by
3ae03b9b65ed Document sameopenfile(), samestat().
Fred Drake <fdrake@acm.org>
parents: 10095
diff changeset
183 \function{fstat()}, \function{lstat()}, or \function{stat()}. This
3ae03b9b65ed Document sameopenfile(), samestat().
Fred Drake <fdrake@acm.org>
parents: 10095
diff changeset
184 function implements the underlying comparison used by
3ae03b9b65ed Document sameopenfile(), samestat().
Fred Drake <fdrake@acm.org>
parents: 10095
diff changeset
185 \function{samefile()} and \function{sameopenfile()}.
21062
bc02c3b09626 Clean up some markup cruft. A number of the macros that take no
Fred Drake <fdrake@acm.org>
parents: 20580
diff changeset
186 Availability: Macintosh, \UNIX.
10096
3ae03b9b65ed Document sameopenfile(), samestat().
Fred Drake <fdrake@acm.org>
parents: 10095
diff changeset
187 \end{funcdesc}
3ae03b9b65ed Document sameopenfile(), samestat().
Fred Drake <fdrake@acm.org>
parents: 10095
diff changeset
188
10079
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
189 \begin{funcdesc}{split}{path}
10096
3ae03b9b65ed Document sameopenfile(), samestat().
Fred Drake <fdrake@acm.org>
parents: 10095
diff changeset
190 Split the pathname \var{path} into a pair, \code{(\var{head},
3ae03b9b65ed Document sameopenfile(), samestat().
Fred Drake <fdrake@acm.org>
parents: 10095
diff changeset
191 \var{tail})} where \var{tail} is the last pathname component and
10079
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
192 \var{head} is everything leading up to that. The \var{tail} part will
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
193 never contain a slash; if \var{path} ends in a slash, \var{tail} will
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
194 be empty. If there is no slash in \var{path}, \var{head} will be
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
195 empty. If \var{path} is empty, both \var{head} and \var{tail} are
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
196 empty. Trailing slashes are stripped from \var{head} unless it is the
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
197 root (one or more slashes only). In nearly all cases,
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
198 \code{join(\var{head}, \var{tail})} equals \var{path} (the only
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
199 exception being when there were multiple slashes separating \var{head}
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
200 from \var{tail}).
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
201 \end{funcdesc}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
202
10095
7ead4a04427e Document splitdrive().
Fred Drake <fdrake@acm.org>
parents: 10079
diff changeset
203 \begin{funcdesc}{splitdrive}{path}
7ead4a04427e Document splitdrive().
Fred Drake <fdrake@acm.org>
parents: 10079
diff changeset
204 Split the pathname \var{path} into a pair \code{(\var{drive},
10096
3ae03b9b65ed Document sameopenfile(), samestat().
Fred Drake <fdrake@acm.org>
parents: 10095
diff changeset
205 \var{tail})} where \var{drive} is either a drive specification or the
10095
7ead4a04427e Document splitdrive().
Fred Drake <fdrake@acm.org>
parents: 10079
diff changeset
206 empty string. On systems which do not use drive specifications,
7ead4a04427e Document splitdrive().
Fred Drake <fdrake@acm.org>
parents: 10079
diff changeset
207 \var{drive} will always be the empty string. In all cases,
7ead4a04427e Document splitdrive().
Fred Drake <fdrake@acm.org>
parents: 10079
diff changeset
208 \code{\var{drive} + \var{tail}} will be the same as \var{path}.
17967
05ab0a714e4c Add a version annotation for splitdrive(); old, but as long as I managed
Fred Drake <fdrake@acm.org>
parents: 15351
diff changeset
209 \versionadded{1.3}
10095
7ead4a04427e Document splitdrive().
Fred Drake <fdrake@acm.org>
parents: 10079
diff changeset
210 \end{funcdesc}
7ead4a04427e Document splitdrive().
Fred Drake <fdrake@acm.org>
parents: 10079
diff changeset
211
10079
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
212 \begin{funcdesc}{splitext}{path}
10095
7ead4a04427e Document splitdrive().
Fred Drake <fdrake@acm.org>
parents: 10079
diff changeset
213 Split the pathname \var{path} into a pair \code{(\var{root}, \var{ext})}
10079
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
214 such that \code{\var{root} + \var{ext} == \var{path}},
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
215 and \var{ext} is empty or begins with a period and contains
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
216 at most one period.
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
217 \end{funcdesc}
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
218
10079
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
219 \begin{funcdesc}{walk}{path, visit, arg}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
220 Calls the function \var{visit} with arguments
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
221 \code{(\var{arg}, \var{dirname}, \var{names})} for each directory in the
10079
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
222 directory tree rooted at \var{path} (including \var{path} itself, if it
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
223 is a directory). The argument \var{dirname} specifies the visited
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
224 directory, the argument \var{names} lists the files in the directory
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
225 (gotten from \code{os.listdir(\var{dirname})}).
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
226 The \var{visit} function may modify \var{names} to
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
227 influence the set of directories visited below \var{dirname}, e.g., to
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
228 avoid visiting certain parts of the tree. (The object referred to by
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
229 \var{names} must be modified in place, using \keyword{del} or slice
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
230 assignment.)
24596
a02aba72cbb2 Add comment about os.path.walk()'s behavior with symbolic links.
Steve Holden <steve@holdenweb.com>
parents: 22835
diff changeset
231
24625
482c941d593f Change the markup a bit more; the parameter was not marked as \var in the
Fred Drake <fdrake@acm.org>
parents: 24623
diff changeset
232 \begin{notice}
482c941d593f Change the markup a bit more; the parameter was not marked as \var in the
Fred Drake <fdrake@acm.org>
parents: 24623
diff changeset
233 Symbolic links to directories are not treated as subdirectories, and
482c941d593f Change the markup a bit more; the parameter was not marked as \var in the
Fred Drake <fdrake@acm.org>
parents: 24623
diff changeset
234 that \function{walk()} therefore will not visit them. To visit linked
482c941d593f Change the markup a bit more; the parameter was not marked as \var in the
Fred Drake <fdrake@acm.org>
parents: 24623
diff changeset
235 directories you must identify them with
482c941d593f Change the markup a bit more; the parameter was not marked as \var in the
Fred Drake <fdrake@acm.org>
parents: 24623
diff changeset
236 \code{os.path.islink(\var{file})} and
482c941d593f Change the markup a bit more; the parameter was not marked as \var in the
Fred Drake <fdrake@acm.org>
parents: 24623
diff changeset
237 \code{os.path.isdir(\var{file})}, and invoke \function{walk()} as
482c941d593f Change the markup a bit more; the parameter was not marked as \var in the
Fred Drake <fdrake@acm.org>
parents: 24623
diff changeset
238 necessary.
482c941d593f Change the markup a bit more; the parameter was not marked as \var in the
Fred Drake <fdrake@acm.org>
parents: 24623
diff changeset
239 \end{notice}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
240 \end{funcdesc}
27679
d698c5623da0 supports_unicode_filenames was not in the right location.
Fred Drake <fdrake@acm.org>
parents: 26948
diff changeset
241
d698c5623da0 supports_unicode_filenames was not in the right location.
Fred Drake <fdrake@acm.org>
parents: 26948
diff changeset
242 \begin{datadesc}{supports_unicode_filenames}
d698c5623da0 supports_unicode_filenames was not in the right location.
Fred Drake <fdrake@acm.org>
parents: 26948
diff changeset
243 True if arbitrary Unicode strings can be used as file names (within
d698c5623da0 supports_unicode_filenames was not in the right location.
Fred Drake <fdrake@acm.org>
parents: 26948
diff changeset
244 limitations imposed by the file system), and if
d698c5623da0 supports_unicode_filenames was not in the right location.
Fred Drake <fdrake@acm.org>
parents: 26948
diff changeset
245 \function{os.listdir()} returns Unicode strings for a Unicode
d698c5623da0 supports_unicode_filenames was not in the right location.
Fred Drake <fdrake@acm.org>
parents: 26948
diff changeset
246 argument.
d698c5623da0 supports_unicode_filenames was not in the right location.
Fred Drake <fdrake@acm.org>
parents: 26948
diff changeset
247 \versionadded{2.3}
d698c5623da0 supports_unicode_filenames was not in the right location.
Fred Drake <fdrake@acm.org>
parents: 26948
diff changeset
248 \end{datadesc}