Mercurial > cpython-lru_cache-weakref

annotate Doc/libppath.tex @ 5817:48b94de85bf3 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Extensive changes by AMK.
author Guido van Rossum <guido@python.org>
date Thu, 17 Jul 1997 16:29:42 +0000
parents d4c6b4b0548c
children 3468ea8645ca
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
1 \section{Standard Module \sectcode{posixpath}}
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
2 \stmodindex{posixpath}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
3
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
4 This module implements some useful functions on POSIX pathnames.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
5
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
6 \strong{Do not import this module directly.} Instead, import the
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
7 module \code{os} and use \code{os.path}.
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
8 \stmodindex{os}
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
9
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
10 \renewcommand{\indexsubitem}{(in module posixpath)}
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
11
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
12 \begin{funcdesc}{basename}{p}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
13 Return the base name of pathname
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
14 \var{p}.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
15 This is the second half of the pair returned by
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
16 \code{posixpath.split(\var{p})}.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
17 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
18
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
19 \begin{funcdesc}{commonprefix}{list}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
20 Return the longest string that is a prefix of all strings in
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
21 \var{list}.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
22 If
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
23 \var{list}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
24 is empty, return the empty string (\code{''}).
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
25 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
26
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
27 \begin{funcdesc}{exists}{p}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
28 Return true if
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
29 \var{p}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
30 refers to an existing path.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
31 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
32
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
33 \begin{funcdesc}{expanduser}{p}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
34 Return the argument with an initial component of \samp{\~} or
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
35 \samp{\~\var{user}} replaced by that \var{user}'s home directory. An
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
36 initial \samp{\~{}} is replaced by the environment variable \code{\${}HOME};
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
37 an initial \samp{\~\var{user}} is looked up in the password directory through
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
38 the built-in module \code{pwd}. If the expansion fails, or if the
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
39 path does not begin with a tilde, the path is returned unchanged.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
40 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
41
1591
ac9e12b4ea8c Documented new built-in function vars().
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
42 \begin{funcdesc}{expandvars}{p}
ac9e12b4ea8c Documented new built-in function vars().
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
43 Return the argument with environment variables expanded. Substrings
ac9e12b4ea8c Documented new built-in function vars().
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
44 of the form \samp{\$\var{name}} or \samp{\$\{\var{name}\}} are
ac9e12b4ea8c Documented new built-in function vars().
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
45 replaced by the value of environment variable \var{name}. Malformed
ac9e12b4ea8c Documented new built-in function vars().
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
46 variable names and references to non-existing variables are left
ac9e12b4ea8c Documented new built-in function vars().
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
47 unchanged.
ac9e12b4ea8c Documented new built-in function vars().
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
48 \end{funcdesc}
ac9e12b4ea8c Documented new built-in function vars().
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
49
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
50 \begin{funcdesc}{isabs}{p}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
51 Return true if \var{p} is an absolute pathname (begins with a slash).
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
52 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
53
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
54 \begin{funcdesc}{isfile}{p}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
55 Return true if \var{p} is an existing regular file. This follows
2527
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 1591
diff changeset
56 symbolic links, so both \code{islink()} and \code{isfile()} can be true for the same
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
57 path.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
58 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
59
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
60 \begin{funcdesc}{isdir}{p}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
61 Return true if \var{p} is an existing directory. This follows
2527
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 1591
diff changeset
62 symbolic links, so both \code{islink()} and \code{isdir()} can be true for the same
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
63 path.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
64 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
65
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
66 \begin{funcdesc}{islink}{p}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
67 Return true if
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
68 \var{p}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
69 refers to a directory entry that is a symbolic link.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
70 Always false if symbolic links are not supported.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
71 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
72
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
73 \begin{funcdesc}{ismount}{p}
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
74 Return true if pathname \var{p} is a \dfn{mount point}: a point in a
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
75 file system where a different file system has been mounted. The
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
76 function checks whether \var{p}'s parent, \file{\var{p}/..}, is on a
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
77 different device than \var{p}, or whether \file{\var{p}/..} and
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
78 \var{p} point to the same i-node on the same device --- this should
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
79 detect mount points for all \UNIX{} and POSIX variants.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
80 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
81
5135
7fa9a644483e Document the new join() semantics.
Barry Warsaw <barry@python.org>
parents: 4051
diff changeset
82 \begin{funcdesc}{join}{p\optional{\, q\optional{\, ...}}}
7fa9a644483e Document the new join() semantics.
Barry Warsaw <barry@python.org>
parents: 4051
diff changeset
83 Joins one or more path components intelligently. If any component is
7fa9a644483e Document the new join() semantics.
Barry Warsaw <barry@python.org>
parents: 4051
diff changeset
84 an absolute path, all previous components are thrown away, and joining
7fa9a644483e Document the new join() semantics.
Barry Warsaw <barry@python.org>
parents: 4051
diff changeset
85 continues. The return value is the concatenation of \var{p}, and
7fa9a644483e Document the new join() semantics.
Barry Warsaw <barry@python.org>
parents: 4051
diff changeset
86 optionally \var{q}, etc., with exactly one slash (\code{'/'}) inserted
7fa9a644483e Document the new join() semantics.
Barry Warsaw <barry@python.org>
parents: 4051
diff changeset
87 between components, unless \var{p} is empty.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
88 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
89
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
90 \begin{funcdesc}{normcase}{p}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
91 Normalize the case of a pathname. This returns the path unchanged;
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
92 however, a similar function in \code{macpath} converts upper case to
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
93 lower case.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
94 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
95
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
96 \begin{funcdesc}{samefile}{p\, q}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
97 Return true if both pathname arguments refer to the same file or directory
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
98 (as indicated by device number and i-node number).
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
99 Raise an exception if a stat call on either pathname fails.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
100 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
101
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
102 \begin{funcdesc}{split}{p}
3712
8e4798d21915 Better and correct words for split().
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
103 Split the pathname \var{p} in a pair \code{(\var{head}, \var{tail})},
8e4798d21915 Better and correct words for split().
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
104 where \var{tail} is the last pathname component and \var{head} is
8e4798d21915 Better and correct words for split().
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
105 everything leading up to that. The \var{tail} part will never contain
8e4798d21915 Better and correct words for split().
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
106 a slash; if \var{p} ends in a slash, \var{tail} will be empty. If
8e4798d21915 Better and correct words for split().
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
107 there is no slash in \var{p}, \var{head} will be empty. If \var{p} is
8e4798d21915 Better and correct words for split().
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
108 empty, both \var{head} and \var{tail} are empty. Trailing slashes are
8e4798d21915 Better and correct words for split().
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
109 stripped from \var{head} unless it is the root (one or more slashes
8e4798d21915 Better and correct words for split().
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
110 only). In nearly all cases, \code{join(\var{head}, \var{tail})}
8e4798d21915 Better and correct words for split().
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
111 equals \var{p} (the only exception being when there were multiple
8e4798d21915 Better and correct words for split().
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
112 slashes separating \var{head} from \var{tail}).
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
113 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
114
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
115 \begin{funcdesc}{splitext}{p}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
116 Split the pathname \var{p} in a pair \code{(\var{root}, \var{ext})}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
117 such that \code{\var{root} + \var{ext} == \var{p}},
4051
d6ca6e207994 Document actual behavior of splitext().
Guido van Rossum <guido@python.org>
parents: 3712
diff changeset
118 and \var{ext} is empty or begins with a period and contains
d6ca6e207994 Document actual behavior of splitext().
Guido van Rossum <guido@python.org>
parents: 3712
diff changeset
119 at most one period.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
120 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
121
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
122 \begin{funcdesc}{walk}{p\, visit\, arg}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
123 Calls the function \var{visit} with arguments
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
124 \code{(\var{arg}, \var{dirname}, \var{names})} for each directory in the
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
125 directory tree rooted at \var{p} (including \var{p} itself, if it is a
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
126 directory). The argument \var{dirname} specifies the visited directory,
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
127 the argument \var{names} lists the files in the directory (gotten from
5210
d4c6b4b0548c Remove untrue statement about . and .. being included in list of names
Guido van Rossum <guido@python.org>
parents: 5135
diff changeset
128 \code{posix.listdir(\var{dirname})}).
d4c6b4b0548c Remove untrue statement about . and .. being included in list of names
Guido van Rossum <guido@python.org>
parents: 5135
diff changeset
129 The \var{visit} function may modify \var{names} to
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
130 influence the set of directories visited below \var{dirname}, e.g., to
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
131 avoid visiting certain parts of the tree. (The object referred to by
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
132 \var{names} must be modified in place, using \code{del} or slice
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
133 assignment.)
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
134 \end{funcdesc}