Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libposixpath.tex @ 21467:4e35fa5d5708 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add documentation for the help() built-in; contributed by Ka-Ping Yee. This is part of SF patch #494622.
author Fred Drake <fdrake@acm.org>
date Tue, 18 Dec 2001 16:31:08 +0000
parents bc02c3b09626
children 73d145bfd8e4
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}
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
45 Return 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}
575c4ea2542b Fix an amazing number of typos & malformed sentences reported by Detlef
Fred Drake <fdrake@acm.org>
parents: 10166
diff changeset
69 Return the time of last access of \var{filename}. The return
575c4ea2542b Fix an amazing number of typos & malformed sentences reported by Detlef
Fred Drake <fdrake@acm.org>
parents: 10166
diff changeset
70 value is integer giving the number of seconds since the epoch (see the
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}
8747
cd99520320a3 Document getsize(), getmtime(), getatime().
Guido van Rossum <guido@python.org>
parents: 8730
diff changeset
74 \end{funcdesc}
cd99520320a3 Document getsize(), getmtime(), getatime().
Guido van Rossum <guido@python.org>
parents: 8730
diff changeset
75
10079
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
76 \begin{funcdesc}{getmtime}{path}
8747
cd99520320a3 Document getsize(), getmtime(), getatime().
Guido van Rossum <guido@python.org>
parents: 8730
diff changeset
77 Return the time of last modification of \var{filename}. The return
cd99520320a3 Document getsize(), getmtime(), getatime().
Guido van Rossum <guido@python.org>
parents: 8730
diff changeset
78 value is integer 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
79 \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
80 not exist or is inaccessible.
10079
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
81 \versionadded{1.5.2}
8747
cd99520320a3 Document getsize(), getmtime(), getatime().
Guido van Rossum <guido@python.org>
parents: 8730
diff changeset
82 \end{funcdesc}
cd99520320a3 Document getsize(), getmtime(), getatime().
Guido van Rossum <guido@python.org>
parents: 8730
diff changeset
83
10243
575c4ea2542b Fix an amazing number of typos & malformed sentences reported by Detlef
Fred Drake <fdrake@acm.org>
parents: 10166
diff changeset
84 \begin{funcdesc}{getsize}{path}
575c4ea2542b Fix an amazing number of typos & malformed sentences reported by Detlef
Fred Drake <fdrake@acm.org>
parents: 10166
diff changeset
85 Return the size, in bytes, of \var{filename}. Raise
575c4ea2542b Fix an amazing number of typos & malformed sentences reported by Detlef
Fred Drake <fdrake@acm.org>
parents: 10166
diff changeset
86 \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
87 \versionadded{1.5.2}
8747
cd99520320a3 Document getsize(), getmtime(), getatime().
Guido van Rossum <guido@python.org>
parents: 8730
diff changeset
88 \end{funcdesc}
cd99520320a3 Document getsize(), getmtime(), getatime().
Guido van Rossum <guido@python.org>
parents: 8730
diff changeset
89
10079
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
90 \begin{funcdesc}{isabs}{path}
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
91 Return true if \var{path} is an absolute pathname (begins with a
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
92 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
93 \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
94
10079
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
95 \begin{funcdesc}{isfile}{path}
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
96 Return 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
97 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
98 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
99 \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
100
10079
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
101 \begin{funcdesc}{isdir}{path}
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
102 Return 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
103 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
104 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
105 \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
106
10079
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
107 \begin{funcdesc}{islink}{path}
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
108 Return true if \var{path} refers to a directory entry that is a
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
109 symbolic link. Always 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
110 \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
111
10079
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
112 \begin{funcdesc}{ismount}{path}
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
113 Return true if pathname \var{path} is a \dfn{mount point}: a point in
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
114 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
115 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
116 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
117 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
118 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
119 \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
120
10079
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
121 \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
122 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
123 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
124 continues. The return value is the concatenation of \var{path1}, and
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
125 optionally \var{path2}, etc., with exactly one slash (\code{'/'})
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
126 inserted between components, unless \var{path} is empty.
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
127 \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
128
10079
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
129 \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
130 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
131 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
132 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
133 slashes.
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
134 \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
135
10079
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
136 \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
137 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
138 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
139 \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
140 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
141 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
142 \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
143
19934
f2f25a738f7f SF patch #461781 by Chris Lawrence: os.path.realpath - Resolve symlinks:
Guido van Rossum <guido@python.org>
parents: 17967
diff changeset
144 \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
145 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
146 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
147 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
148 \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
149 \end{funcdesc}
f2f25a738f7f SF patch #461781 by Chris Lawrence: os.path.realpath - Resolve symlinks:
Guido van Rossum <guido@python.org>
parents: 17967
diff changeset
150
10079
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
151 \begin{funcdesc}{samefile}{path1, path2}
8730
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
152 Return true if both pathname arguments refer to the same file or
8a306dfd9f33 Move files around to get the names to match the module names except for
Fred Drake <fdrake@acm.org>
parents:
diff changeset
153 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
154 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
155 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
156 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
157 \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
158
10096
3ae03b9b65ed Document sameopenfile(), samestat().
Fred Drake <fdrake@acm.org>
parents: 10095
diff changeset
159 \begin{funcdesc}{sameopenfile}{fp1, fp2}
3ae03b9b65ed Document sameopenfile(), samestat().
Fred Drake <fdrake@acm.org>
parents: 10095
diff changeset
160 Return true if the file objects \var{fp1} and \var{fp2} refer to the
3ae03b9b65ed Document sameopenfile(), samestat().
Fred Drake <fdrake@acm.org>
parents: 10095
diff changeset
161 same file. The two file objects may represent different file
3ae03b9b65ed Document sameopenfile(), samestat().
Fred Drake <fdrake@acm.org>
parents: 10095
diff changeset
162 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
163 Availability: Macintosh, \UNIX.
10096
3ae03b9b65ed Document sameopenfile(), samestat().
Fred Drake <fdrake@acm.org>
parents: 10095
diff changeset
164 \end{funcdesc}
3ae03b9b65ed Document sameopenfile(), samestat().
Fred Drake <fdrake@acm.org>
parents: 10095
diff changeset
165
3ae03b9b65ed Document sameopenfile(), samestat().
Fred Drake <fdrake@acm.org>
parents: 10095
diff changeset
166 \begin{funcdesc}{samestat}{stat1, stat2}
3ae03b9b65ed Document sameopenfile(), samestat().
Fred Drake <fdrake@acm.org>
parents: 10095
diff changeset
167 Return true if the stat tuples \var{stat1} and \var{stat2} refer to
3ae03b9b65ed Document sameopenfile(), samestat().
Fred Drake <fdrake@acm.org>
parents: 10095
diff changeset
168 the same file. These structures may have been returned by
3ae03b9b65ed Document sameopenfile(), samestat().
Fred Drake <fdrake@acm.org>
parents: 10095
diff changeset
169 \function{fstat()}, \function{lstat()}, or \function{stat()}. This
3ae03b9b65ed Document sameopenfile(), samestat().
Fred Drake <fdrake@acm.org>
parents: 10095
diff changeset
170 function implements the underlying comparison used by
3ae03b9b65ed Document sameopenfile(), samestat().
Fred Drake <fdrake@acm.org>
parents: 10095
diff changeset
171 \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
172 Availability: Macintosh, \UNIX.
10096
3ae03b9b65ed Document sameopenfile(), samestat().
Fred Drake <fdrake@acm.org>
parents: 10095
diff changeset
173 \end{funcdesc}
3ae03b9b65ed Document sameopenfile(), samestat().
Fred Drake <fdrake@acm.org>
parents: 10095
diff changeset
174
10079
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
175 \begin{funcdesc}{split}{path}
10096
3ae03b9b65ed Document sameopenfile(), samestat().
Fred Drake <fdrake@acm.org>
parents: 10095
diff changeset
176 Split the pathname \var{path} into a pair, \code{(\var{head},
3ae03b9b65ed Document sameopenfile(), samestat().
Fred Drake <fdrake@acm.org>
parents: 10095
diff changeset
177 \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
178 \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
179 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
180 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
181 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
182 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
183 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
184 \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
185 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
186 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
187 \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
188
10095
7ead4a04427e Document splitdrive().
Fred Drake <fdrake@acm.org>
parents: 10079
diff changeset
189 \begin{funcdesc}{splitdrive}{path}
7ead4a04427e Document splitdrive().
Fred Drake <fdrake@acm.org>
parents: 10079
diff changeset
190 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
191 \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
192 empty string. On systems which do not use drive specifications,
7ead4a04427e Document splitdrive().
Fred Drake <fdrake@acm.org>
parents: 10079
diff changeset
193 \var{drive} will always be the empty string. In all cases,
7ead4a04427e Document splitdrive().
Fred Drake <fdrake@acm.org>
parents: 10079
diff changeset
194 \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
195 \versionadded{1.3}
10095
7ead4a04427e Document splitdrive().
Fred Drake <fdrake@acm.org>
parents: 10079
diff changeset
196 \end{funcdesc}
7ead4a04427e Document splitdrive().
Fred Drake <fdrake@acm.org>
parents: 10079
diff changeset
197
10079
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
198 \begin{funcdesc}{splitext}{path}
10095
7ead4a04427e Document splitdrive().
Fred Drake <fdrake@acm.org>
parents: 10079
diff changeset
199 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
200 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
201 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
202 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
203 \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
204
10079
bc3602a83ad3 Change this to be os.path.
Fred Drake <fdrake@acm.org>
parents: 10063
diff changeset
205 \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
206 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
207 \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
208 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
209 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
210 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
211 (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
212 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
213 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
214 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
215 \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
216 assignment.)
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}