Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/liburlparse.tex @ 37850:ebe59cd18273

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Use explicit relative import for an, ehm, relative import.
author Thomas Wouters <thomas@python.org>
date Tue, 18 Apr 2006 21:41:36 +0000
parents 838b5f5924ee
children 05914e8ded73 f731859e9b3b
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
8918
acfffe14628e New section header style.
Fred Drake <fdrake@acm.org>
parents: 8855
diff changeset
1 \section{\module{urlparse} ---
14185
93013e4bbe02 Add reference to RFC 2396 in "See also" section.
Fred Drake <fdrake@acm.org>
parents: 14153
diff changeset
2 Parse URLs into components}
8716
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
3 \declaremodule{standard}{urlparse}
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
4
8855
354cd24e5dfe Shorten the module synopsis.
Fred Drake <fdrake@acm.org>
parents: 8716
diff changeset
5 \modulesynopsis{Parse URLs into components.}
8716
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
6
2449
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
7 \index{WWW}
18574
346dcafc878b Minor changes to match the style guide.
Fred Drake <fdrake@acm.org>
parents: 14185
diff changeset
8 \index{World Wide Web}
2449
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
9 \index{URL}
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
10 \indexii{URL}{parsing}
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
11 \indexii{relative}{URL}
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
12
2453
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
13
14185
93013e4bbe02 Add reference to RFC 2396 in "See also" section.
Fred Drake <fdrake@acm.org>
parents: 14153
diff changeset
14 This module defines a standard interface to break Uniform Resource
93013e4bbe02 Add reference to RFC 2396 in "See also" section.
Fred Drake <fdrake@acm.org>
parents: 14153
diff changeset
15 Locator (URL) strings up in components (addressing scheme, network
93013e4bbe02 Add reference to RFC 2396 in "See also" section.
Fred Drake <fdrake@acm.org>
parents: 14153
diff changeset
16 location, path etc.), to combine the components back into a URL
93013e4bbe02 Add reference to RFC 2396 in "See also" section.
Fred Drake <fdrake@acm.org>
parents: 14153
diff changeset
17 string, and to convert a ``relative URL'' to an absolute URL given a
93013e4bbe02 Add reference to RFC 2396 in "See also" section.
Fred Drake <fdrake@acm.org>
parents: 14153
diff changeset
18 ``base URL.''
2449
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
19
7144
4ef6a83b2e62 Update comment about relative URL internet draft to reflect current RFC status;
Fred Drake <fdrake@acm.org>
parents: 6963
diff changeset
20 The module has been designed to match the Internet RFC on Relative
4ef6a83b2e62 Update comment about relative URL internet draft to reflect current RFC status;
Fred Drake <fdrake@acm.org>
parents: 6963
diff changeset
21 Uniform Resource Locators (and discovered a bug in an earlier
36356
04a96cc88583 Document supported schemes.
Georg Brandl <georg@python.org>
parents: 35490
diff changeset
22 draft!). It supports the following URL schemes:
04a96cc88583 Document supported schemes.
Georg Brandl <georg@python.org>
parents: 35490
diff changeset
23 \code{file}, \code{ftp}, \code{gopher}, \code{hdl}, \code{http},
04a96cc88583 Document supported schemes.
Georg Brandl <georg@python.org>
parents: 35490
diff changeset
24 \code{https}, \code{imap}, \code{mailto}, \code{mms}, \code{news},
04a96cc88583 Document supported schemes.
Georg Brandl <georg@python.org>
parents: 35490
diff changeset
25 \code{nntp}, \code{prospero}, \code{rsync}, \code{rtsp}, \code{rtspu},
04a96cc88583 Document supported schemes.
Georg Brandl <georg@python.org>
parents: 35490
diff changeset
26 \code{sftp}, \code{shttp}, \code{sip}, \code{snews}, \code{svn},
04a96cc88583 Document supported schemes.
Georg Brandl <georg@python.org>
parents: 35490
diff changeset
27 \code{svn+ssh}, \code{telnet}, \code{wais}.
36385
838b5f5924ee Add \versionadded for sftp scheme
Georg Brandl <georg@python.org>
parents: 36356
diff changeset
28 \versionadded[Support for the \code{sftp} scheme]{2.5}
2449
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
29
36356
04a96cc88583 Document supported schemes.
Georg Brandl <georg@python.org>
parents: 35490
diff changeset
30 The \module{urlparse} module defines the following functions:
2449
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
31
6963
10f2921a091e Reduce warning count from partparse.py.
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
32 \begin{funcdesc}{urlparse}{urlstring\optional{, default_scheme\optional{, allow_fragments}}}
2449
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
33 Parse a URL into 6 components, returning a 6-tuple: (addressing
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
34 scheme, network location, path, parameters, query, fragment
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
35 identifier). This corresponds to the general structure of a URL:
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
36 \code{\var{scheme}://\var{netloc}/\var{path};\var{parameters}?\var{query}\#\var{fragment}}.
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
37 Each tuple item is a string, possibly empty.
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
38 The components are not broken up in smaller parts (e.g. the network
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
39 location is a single string), and \% escapes are not expanded.
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2453
diff changeset
40 The delimiters as shown above are not part of the tuple items,
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2453
diff changeset
41 except for a leading slash in the \var{path} component, which is
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2453
diff changeset
42 retained if present.
2449
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
43
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
44 Example:
2647
9b7e6d9a528d typos, layout and other small things
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
45
7277
bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents: 7219
diff changeset
46 \begin{verbatim}
2647
9b7e6d9a528d typos, layout and other small things
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
47 urlparse('http://www.cwi.nl:80/%7Eguido/Python.html')
7277
bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents: 7219
diff changeset
48 \end{verbatim}
14153
40447b672064 Move references to RFCs to a "See also" section for consistency with
Fred Drake <fdrake@acm.org>
parents: 13625
diff changeset
49
2449
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
50 yields the tuple
2647
9b7e6d9a528d typos, layout and other small things
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
51
7277
bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents: 7219
diff changeset
52 \begin{verbatim}
2647
9b7e6d9a528d typos, layout and other small things
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
53 ('http', 'www.cwi.nl:80', '/%7Eguido/Python.html', '', '', '')
7277
bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents: 7219
diff changeset
54 \end{verbatim}
14153
40447b672064 Move references to RFCs to a "See also" section for consistency with
Fred Drake <fdrake@acm.org>
parents: 13625
diff changeset
55
2449
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
56 If the \var{default_scheme} argument is specified, it gives the
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
57 default addressing scheme, to be used only if the URL string does not
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
58 specify one. The default value for this argument is the empty string.
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
59
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
60 If the \var{allow_fragments} argument is zero, fragment identifiers
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
61 are not allowed, even if the URL's addressing scheme normally does
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
62 support them. The default value for this argument is \code{1}.
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
63 \end{funcdesc}
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
64
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
65 \begin{funcdesc}{urlunparse}{tuple}
7144
4ef6a83b2e62 Update comment about relative URL internet draft to reflect current RFC status;
Fred Drake <fdrake@acm.org>
parents: 6963
diff changeset
66 Construct a URL string from a tuple as returned by \code{urlparse()}.
2449
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
67 This may result in a slightly different, but equivalent URL, if the
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
68 URL that was parsed originally had redundant delimiters, e.g. a ? with
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
69 an empty query (the draft states that these are equivalent).
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
70 \end{funcdesc}
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
71
20996
f0b575d6feaa Document the urlsplit() and urlunsplit() functions.
Fred Drake <fdrake@acm.org>
parents: 18574
diff changeset
72 \begin{funcdesc}{urlsplit}{urlstring\optional{,
f0b575d6feaa Document the urlsplit() and urlunsplit() functions.
Fred Drake <fdrake@acm.org>
parents: 18574
diff changeset
73 default_scheme\optional{, allow_fragments}}}
f0b575d6feaa Document the urlsplit() and urlunsplit() functions.
Fred Drake <fdrake@acm.org>
parents: 18574
diff changeset
74 This is similar to \function{urlparse()}, but does not split the
f0b575d6feaa Document the urlsplit() and urlunsplit() functions.
Fred Drake <fdrake@acm.org>
parents: 18574
diff changeset
75 params from the URL. This should generally be used instead of
f0b575d6feaa Document the urlsplit() and urlunsplit() functions.
Fred Drake <fdrake@acm.org>
parents: 18574
diff changeset
76 \function{urlparse()} if the more recent URL syntax allowing
f0b575d6feaa Document the urlsplit() and urlunsplit() functions.
Fred Drake <fdrake@acm.org>
parents: 18574
diff changeset
77 parameters to be applied to each segment of the \var{path} portion of
35490
3e6212113e82 Backport checkin:
Walter Dörwald <walter@livinglogic.de>
parents: 25822
diff changeset
78 the URL (see \rfc{2396}) is wanted. A separate function is needed to
3e6212113e82 Backport checkin:
Walter Dörwald <walter@livinglogic.de>
parents: 25822
diff changeset
79 separate the path segments and parameters. This function returns a
3e6212113e82 Backport checkin:
Walter Dörwald <walter@livinglogic.de>
parents: 25822
diff changeset
80 5-tuple: (addressing scheme, network location, path, query, fragment
20996
f0b575d6feaa Document the urlsplit() and urlunsplit() functions.
Fred Drake <fdrake@acm.org>
parents: 18574
diff changeset
81 identifier).
f0b575d6feaa Document the urlsplit() and urlunsplit() functions.
Fred Drake <fdrake@acm.org>
parents: 18574
diff changeset
82 \versionadded{2.2}
f0b575d6feaa Document the urlsplit() and urlunsplit() functions.
Fred Drake <fdrake@acm.org>
parents: 18574
diff changeset
83 \end{funcdesc}
f0b575d6feaa Document the urlsplit() and urlunsplit() functions.
Fred Drake <fdrake@acm.org>
parents: 18574
diff changeset
84
f0b575d6feaa Document the urlsplit() and urlunsplit() functions.
Fred Drake <fdrake@acm.org>
parents: 18574
diff changeset
85 \begin{funcdesc}{urlunsplit}{tuple}
f0b575d6feaa Document the urlsplit() and urlunsplit() functions.
Fred Drake <fdrake@acm.org>
parents: 18574
diff changeset
86 Combine the elements of a tuple as returned by \function{urlsplit()}
f0b575d6feaa Document the urlsplit() and urlunsplit() functions.
Fred Drake <fdrake@acm.org>
parents: 18574
diff changeset
87 into a complete URL as a string.
f0b575d6feaa Document the urlsplit() and urlunsplit() functions.
Fred Drake <fdrake@acm.org>
parents: 18574
diff changeset
88 \versionadded{2.2}
f0b575d6feaa Document the urlsplit() and urlunsplit() functions.
Fred Drake <fdrake@acm.org>
parents: 18574
diff changeset
89 \end{funcdesc}
f0b575d6feaa Document the urlsplit() and urlunsplit() functions.
Fred Drake <fdrake@acm.org>
parents: 18574
diff changeset
90
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
91 \begin{funcdesc}{urljoin}{base, url\optional{, allow_fragments}}
2449
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
92 Construct a full (``absolute'') URL by combining a ``base URL''
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
93 (\var{base}) with a ``relative URL'' (\var{url}). Informally, this
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
94 uses components of the base URL, in particular the addressing scheme,
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
95 the network location and (part of) the path, to provide missing
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
96 components in the relative URL.
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
97
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
98 Example:
2647
9b7e6d9a528d typos, layout and other small things
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
99
7277
bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents: 7219
diff changeset
100 \begin{verbatim}
2647
9b7e6d9a528d typos, layout and other small things
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
101 urljoin('http://www.cwi.nl/%7Eguido/Python.html', 'FAQ.html')
7277
bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents: 7219
diff changeset
102 \end{verbatim}
14153
40447b672064 Move references to RFCs to a "See also" section for consistency with
Fred Drake <fdrake@acm.org>
parents: 13625
diff changeset
103
2647
9b7e6d9a528d typos, layout and other small things
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
104 yields the string
9b7e6d9a528d typos, layout and other small things
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
105
7277
bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents: 7219
diff changeset
106 \begin{verbatim}
2647
9b7e6d9a528d typos, layout and other small things
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
107 'http://www.cwi.nl/%7Eguido/FAQ.html'
7277
bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents: 7219
diff changeset
108 \end{verbatim}
14185
93013e4bbe02 Add reference to RFC 2396 in "See also" section.
Fred Drake <fdrake@acm.org>
parents: 14153
diff changeset
109
2449
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
110 The \var{allow_fragments} argument has the same meaning as for
7144
4ef6a83b2e62 Update comment about relative URL internet draft to reflect current RFC status;
Fred Drake <fdrake@acm.org>
parents: 6963
diff changeset
111 \code{urlparse()}.
2449
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
112 \end{funcdesc}
14153
40447b672064 Move references to RFCs to a "See also" section for consistency with
Fred Drake <fdrake@acm.org>
parents: 13625
diff changeset
113
25815
4a92c7d9d415 Document urldefrag().
Fred Drake <fdrake@acm.org>
parents: 20996
diff changeset
114 \begin{funcdesc}{urldefrag}{url}
4a92c7d9d415 Document urldefrag().
Fred Drake <fdrake@acm.org>
parents: 20996
diff changeset
115 If \var{url} contains a fragment identifier, returns a modified
4a92c7d9d415 Document urldefrag().
Fred Drake <fdrake@acm.org>
parents: 20996
diff changeset
116 version of \var{url} with no fragment identifier, and the fragment
4a92c7d9d415 Document urldefrag().
Fred Drake <fdrake@acm.org>
parents: 20996
diff changeset
117 identifier as a separate string. If there is no fragment identifier
4a92c7d9d415 Document urldefrag().
Fred Drake <fdrake@acm.org>
parents: 20996
diff changeset
118 in \var{url}, returns \var{url} unmodified and an empty string.
4a92c7d9d415 Document urldefrag().
Fred Drake <fdrake@acm.org>
parents: 20996
diff changeset
119 \end{funcdesc}
4a92c7d9d415 Document urldefrag().
Fred Drake <fdrake@acm.org>
parents: 20996
diff changeset
120
14153
40447b672064 Move references to RFCs to a "See also" section for consistency with
Fred Drake <fdrake@acm.org>
parents: 13625
diff changeset
121
40447b672064 Move references to RFCs to a "See also" section for consistency with
Fred Drake <fdrake@acm.org>
parents: 13625
diff changeset
122 \begin{seealso}
40447b672064 Move references to RFCs to a "See also" section for consistency with
Fred Drake <fdrake@acm.org>
parents: 13625
diff changeset
123 \seerfc{1738}{Uniform Resource Locators (URL)}{
40447b672064 Move references to RFCs to a "See also" section for consistency with
Fred Drake <fdrake@acm.org>
parents: 13625
diff changeset
124 This specifies the formal syntax and semantics of absolute
40447b672064 Move references to RFCs to a "See also" section for consistency with
Fred Drake <fdrake@acm.org>
parents: 13625
diff changeset
125 URLs.}
40447b672064 Move references to RFCs to a "See also" section for consistency with
Fred Drake <fdrake@acm.org>
parents: 13625
diff changeset
126 \seerfc{1808}{Relative Uniform Resource Locators}{
40447b672064 Move references to RFCs to a "See also" section for consistency with
Fred Drake <fdrake@acm.org>
parents: 13625
diff changeset
127 This Request For Comments includes the rules for joining an
25822
032f196059aa Typo(!): "normal" -> "number"
Fred Drake <fdrake@acm.org>
parents: 25815
diff changeset
128 absolute and a relative URL, including a fair number of
14153
40447b672064 Move references to RFCs to a "See also" section for consistency with
Fred Drake <fdrake@acm.org>
parents: 13625
diff changeset
129 ``Abnormal Examples'' which govern the treatment of border
40447b672064 Move references to RFCs to a "See also" section for consistency with
Fred Drake <fdrake@acm.org>
parents: 13625
diff changeset
130 cases.}
14185
93013e4bbe02 Add reference to RFC 2396 in "See also" section.
Fred Drake <fdrake@acm.org>
parents: 14153
diff changeset
131 \seerfc{2396}{Uniform Resource Identifiers (URI): Generic Syntax}{
93013e4bbe02 Add reference to RFC 2396 in "See also" section.
Fred Drake <fdrake@acm.org>
parents: 14153
diff changeset
132 Document describing the generic syntactic requirements for
93013e4bbe02 Add reference to RFC 2396 in "See also" section.
Fred Drake <fdrake@acm.org>
parents: 14153
diff changeset
133 both Uniform Resource Names (URNs) and Uniform Resource
93013e4bbe02 Add reference to RFC 2396 in "See also" section.
Fred Drake <fdrake@acm.org>
parents: 14153
diff changeset
134 Locators (URLs).}
14153
40447b672064 Move references to RFCs to a "See also" section for consistency with
Fred Drake <fdrake@acm.org>
parents: 13625
diff changeset
135 \end{seealso}