Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/liburlparse.tex @ 8831:00a6bb65ff29 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Getting rid of this ancient stuff.
author Guido van Rossum <guido@python.org>
date Wed, 05 Aug 1998 21:10:09 +0000
parents 760dcf197048
children 354cd24e5dfe
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
7877
8e5223680a9d Remove all uses of \sectcode; we can now use logical markup everywhere.
Fred Drake <fdrake@acm.org>
parents: 7863
diff changeset
1 \section{Standard Module \module{urlparse}}
8716
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
2 \declaremodule{standard}{urlparse}
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
3
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
4 \modulesynopsis{Parse a URL string into a tuple (addressing scheme identifier, network
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
5 location, path, parameters, query string, fragment identifier).}
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}
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2453
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
2449
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
14 This module defines a standard interface to break URL strings up in
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
15 components (addessing scheme, network location, path etc.), to combine
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
16 the components back into a URL string, and to convert a ``relative
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
17 URL'' to an absolute URL given a ``base URL''.
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
18
7144
4ef6a83b2e62 Update comment about relative URL internet draft to reflect current RFC status;
Fred Drake <fdrake@acm.org>
parents: 6963
diff changeset
19 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
20 Uniform Resource Locators (and discovered a bug in an earlier
7219
640b97d105df Use the new RFC macros wherever RFCs are referenced by number. No other
Fred Drake <fdrake@acm.org>
parents: 7144
diff changeset
21 draft!). Refer to \rfc{1808} for details on relative
640b97d105df Use the new RFC macros wherever RFCs are referenced by number. No other
Fred Drake <fdrake@acm.org>
parents: 7144
diff changeset
22 URLs and \rfc{1738} for information on basic URL syntax.
2449
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
23
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
24 It defines the following functions:
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
25
6963
10f2921a091e Reduce warning count from partparse.py.
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
26 \begin{funcdesc}{urlparse}{urlstring\optional{, default_scheme\optional{, allow_fragments}}}
2449
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
27 Parse a URL into 6 components, returning a 6-tuple: (addressing
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
28 scheme, network location, path, parameters, query, fragment
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
29 identifier). This corresponds to the general structure of a URL:
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
30 \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
31 Each tuple item is a string, possibly empty.
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
32 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
33 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
34 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
35 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
36 retained if present.
2449
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
37
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
38 Example:
2647
9b7e6d9a528d typos, layout and other small things
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
39
7277
bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents: 7219
diff changeset
40 \begin{verbatim}
2647
9b7e6d9a528d typos, layout and other small things
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
41 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
42 \end{verbatim}
5818
3468ea8645ca AMK's megapatch:
Guido van Rossum <guido@python.org>
parents: 2647
diff changeset
43 %
2449
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
44 yields the tuple
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 ('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}
5818
3468ea8645ca AMK's megapatch:
Guido van Rossum <guido@python.org>
parents: 2647
diff changeset
49 %
2449
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
50 If the \var{default_scheme} argument is specified, it gives the
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
51 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
52 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
53
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
54 If the \var{allow_fragments} argument is zero, fragment identifiers
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
55 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
56 support them. The default value for this argument is \code{1}.
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
57 \end{funcdesc}
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
58
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
59 \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
60 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
61 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
62 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
63 an empty query (the draft states that these are equivalent).
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
64 \end{funcdesc}
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
65
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
66 \begin{funcdesc}{urljoin}{base, url\optional{, allow_fragments}}
2449
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
67 Construct a full (``absolute'') URL by combining a ``base URL''
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
68 (\var{base}) with a ``relative URL'' (\var{url}). Informally, this
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
69 uses components of the base URL, in particular the addressing scheme,
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
70 the network location and (part of) the path, to provide missing
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
71 components in the relative URL.
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
72
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
73 Example:
2647
9b7e6d9a528d typos, layout and other small things
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
74
7277
bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents: 7219
diff changeset
75 \begin{verbatim}
2647
9b7e6d9a528d typos, layout and other small things
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
76 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
77 \end{verbatim}
5818
3468ea8645ca AMK's megapatch:
Guido van Rossum <guido@python.org>
parents: 2647
diff changeset
78 %
2647
9b7e6d9a528d typos, layout and other small things
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
79 yields the string
9b7e6d9a528d typos, layout and other small things
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
80
7277
bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents: 7219
diff changeset
81 \begin{verbatim}
2647
9b7e6d9a528d typos, layout and other small things
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
82 '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
83 \end{verbatim}
5818
3468ea8645ca AMK's megapatch:
Guido van Rossum <guido@python.org>
parents: 2647
diff changeset
84 %
2449
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
85 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
86 \code{urlparse()}.
2449
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
87 \end{funcdesc}