cpython-lru_cache-weakref: Doc/lib/liburlparse.tex annotate

annotate Doc/lib/liburlparse.tex @ 39042:c02fa187e0f4 legacy-trunk

Part of SF patch #1484695. This removes dead code. The chksum was already verified in .frombuf() on the lines above. If there was a problem an exception is raised, so there was no way this condition could have been true.

author	Neal Norwitz <nnorwitz@gmail.com>
date	Mon, 10 Jul 2006 00:23:17 +0000
parents	a6bce7aebe05
children	d27e76326819

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},
37368 05914e8ded73 add support for the sips: scheme (identical to sip: except for scheme name) Fred Drake <fdrake@acm.org> parents: 36385 diff changeset	26 \code{sftp}, \code{shttp}, \code{sip}, \code{sips}, \code{snews}, \code{svn},
36356 04a96cc88583 Document supported schemes. Georg Brandl <georg@python.org> parents: 35490 diff changeset	27 \code{svn+ssh}, \code{telnet}, \code{wais}.
37393 a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	28
37368 05914e8ded73 add support for the sips: scheme (identical to sip: except for scheme name) Fred Drake <fdrake@acm.org> parents: 36385 diff changeset	29 \versionadded[Support for the \code{sftp} and \code{sips} schemes]{2.5}
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	30
36356 04a96cc88583 Document supported schemes. Georg Brandl <georg@python.org> parents: 35490 diff changeset	31 The \module{urlparse} module defines the following functions:
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	32
37393 a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	33 \begin{funcdesc}{urlparse}{urlstring\optional{,
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	34 default_scheme\optional{, allow_fragments}}}
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	35 Parse a URL into six components, returning a 6-tuple. This
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	36 corresponds to the general structure of a URL:
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	37 \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	38 Each tuple item is a string, possibly empty.
37393 a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	39 The components are not broken up in smaller parts (for example, the network
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	40 location is a single string), and \% escapes are not expanded.
37393 a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	41 The delimiters as shown above are not part of the result,
2576 f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2453 diff changeset	42 except for a leading slash in the \var{path} component, which is
37393 a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	43 retained if present. For example:
2647 9b7e6d9a528d typos, layout and other small things Guido van Rossum <guido@python.org> parents: 2576 diff changeset	44
7277 bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous Fred Drake <fdrake@acm.org> parents: 7219 diff changeset	45 \begin{verbatim}
37393 a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	46 >>> from urlparse import urlparse
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	47 >>> o = urlparse('http://www.cwi.nl:80/%7Eguido/Python.html')
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	48 >>> o
2647 9b7e6d9a528d typos, layout and other small things Guido van Rossum <guido@python.org> parents: 2576 diff changeset	49 ('http', 'www.cwi.nl:80', '/%7Eguido/Python.html', '', '', '')
37393 a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	50 >>> o.scheme
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	51 'http'
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	52 >>> o.port
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	53 80
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	54 >>> o.geturl()
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	55 '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	56 \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	57
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	58 If the \var{default_scheme} argument is specified, it gives the
37393 a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	59 default addressing scheme, to be used only if the URL does not
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	60 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	61
37393 a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	62 If the \var{allow_fragments} argument is false, fragment identifiers
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	63 are not allowed, even if the URL's addressing scheme normally does
37393 a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	64 support them. The default value for this argument is \constant{True}.
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	65
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	66 The return value is actually an instance of a subclass of
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	67 \pytype{tuple}. This class has the following additional read-only
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	68 convenience attributes:
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	69
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	70 \begin{tableiv}{l\|c\|l\|c}{member}{Attribute}{Index}{Value}{Value if not present}
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	71 \lineiv{scheme} {0} {URL scheme specifier} {empty string}
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	72 \lineiv{netloc} {1} {Network location part} {empty string}
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	73 \lineiv{path} {2} {Hierarchical path} {empty string}
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	74 \lineiv{params} {3} {Parameters for last path element} {empty string}
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	75 \lineiv{query} {4} {Query component} {empty string}
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	76 \lineiv{fragment}{5} {Fragment identifier} {empty string}
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	77 \lineiv{username}{ } {User name} {\constant{None}}
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	78 \lineiv{password}{ } {Password} {\constant{None}}
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	79 \lineiv{hostname}{ } {Host name (lower case)} {\constant{None}}
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	80 \lineiv{port} { } {Port number as integer, if present} {\constant{None}}
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	81 \end{tableiv}
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	82
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	83 See section~\ref{urlparse-result-object}, ``Results of
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	84 \function{urlparse()} and \function{urlsplit()},'' for more
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	85 information on the result object.
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	86
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	87 \versionchanged[Added attributes to return value]{2.5}
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	88 \end{funcdesc}
8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	89
37393 a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	90 \begin{funcdesc}{urlunparse}{parts}
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	91 Construct a URL from a tuple as returned by \code{urlparse()}.
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	92 The \var{parts} argument be any six-item iterable.
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	93 This may result in a slightly different, but equivalent URL, if the
37393 a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	94 URL that was parsed originally had unnecessary delimiters (for example,
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	95 a ? with an empty query; the RFC states that these are equivalent).
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	96 \end{funcdesc}
8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	97
20996 f0b575d6feaa Document the urlsplit() and urlunsplit() functions. Fred Drake <fdrake@acm.org> parents: 18574 diff changeset	98 \begin{funcdesc}{urlsplit}{urlstring\optional{,
f0b575d6feaa Document the urlsplit() and urlunsplit() functions. Fred Drake <fdrake@acm.org> parents: 18574 diff changeset	99 default_scheme\optional{, allow_fragments}}}
f0b575d6feaa Document the urlsplit() and urlunsplit() functions. Fred Drake <fdrake@acm.org> parents: 18574 diff changeset	100 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	101 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	102 \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	103 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	104 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	105 separate the path segments and parameters. This function returns a
3e6212113e82 Backport checkin: Walter Dörwald <walter@livinglogic.de> parents: 25822 diff changeset	106 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	107 identifier).
37393 a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	108
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	109 The return value is actually an instance of a subclass of
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	110 \pytype{tuple}. This class has the following additional read-only
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	111 convenience attributes:
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	112
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	113 \begin{tableiv}{l\|c\|l\|c}{member}{Attribute}{Index}{Value}{Value if not present}
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	114 \lineiv{scheme} {0} {URL scheme specifier} {empty string}
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	115 \lineiv{netloc} {1} {Network location part} {empty string}
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	116 \lineiv{path} {2} {Hierarchical path} {empty string}
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	117 \lineiv{query} {3} {Query component} {empty string}
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	118 \lineiv{fragment} {4} {Fragment identifier} {empty string}
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	119 \lineiv{username} { } {User name} {\constant{None}}
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	120 \lineiv{password} { } {Password} {\constant{None}}
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	121 \lineiv{hostname} { } {Host name (lower case)} {\constant{None}}
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	122 \lineiv{port} { } {Port number as integer, if present} {\constant{None}}
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	123 \end{tableiv}
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	124
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	125 See section~\ref{urlparse-result-object}, ``Results of
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	126 \function{urlparse()} and \function{urlsplit()},'' for more
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	127 information on the result object.
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	128
20996 f0b575d6feaa Document the urlsplit() and urlunsplit() functions. Fred Drake <fdrake@acm.org> parents: 18574 diff changeset	129 \versionadded{2.2}
37393 a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	130 \versionchanged[Added attributes to return value]{2.5}
20996 f0b575d6feaa Document the urlsplit() and urlunsplit() functions. Fred Drake <fdrake@acm.org> parents: 18574 diff changeset	131 \end{funcdesc}
f0b575d6feaa Document the urlsplit() and urlunsplit() functions. Fred Drake <fdrake@acm.org> parents: 18574 diff changeset	132
37393 a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	133 \begin{funcdesc}{urlunsplit}{parts}
20996 f0b575d6feaa Document the urlsplit() and urlunsplit() functions. Fred Drake <fdrake@acm.org> parents: 18574 diff changeset	134 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	135 into a complete URL as a string.
37393 a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	136 The \var{parts} argument be any five-item iterable.
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	137 This may result in a slightly different, but equivalent URL, if the
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	138 URL that was parsed originally had unnecessary delimiters (for example,
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	139 a ? with an empty query; the RFC states that these are equivalent).
20996 f0b575d6feaa Document the urlsplit() and urlunsplit() functions. Fred Drake <fdrake@acm.org> parents: 18574 diff changeset	140 \versionadded{2.2}
f0b575d6feaa Document the urlsplit() and urlunsplit() functions. Fred Drake <fdrake@acm.org> parents: 18574 diff changeset	141 \end{funcdesc}
f0b575d6feaa Document the urlsplit() and urlunsplit() functions. Fred Drake <fdrake@acm.org> parents: 18574 diff changeset	142
7712 0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain, Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	143 \begin{funcdesc}{urljoin}{base, url\optional{, allow_fragments}}
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	144 Construct a full (``absolute'') URL by combining a ``base URL''
8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	145 (\var{base}) with a ``relative URL'' (\var{url}). Informally, this
8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	146 uses components of the base URL, in particular the addressing scheme,
8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	147 the network location and (part of) the path, to provide missing
37393 a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	148 components in the relative URL. For example:
2647 9b7e6d9a528d typos, layout and other small things Guido van Rossum <guido@python.org> parents: 2576 diff changeset	149
7277 bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous Fred Drake <fdrake@acm.org> parents: 7219 diff changeset	150 \begin{verbatim}
37393 a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	151 >>> from urlparse import urljoin
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	152 >>> urljoin('http://www.cwi.nl/%7Eguido/Python.html', 'FAQ.html')
2647 9b7e6d9a528d typos, layout and other small things Guido van Rossum <guido@python.org> parents: 2576 diff changeset	153 '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	154 \end{verbatim}
14185 93013e4bbe02 Add reference to RFC 2396 in "See also" section. Fred Drake <fdrake@acm.org> parents: 14153 diff changeset	155
37393 a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	156 The \var{allow_fragments} argument has the same meaning and default as
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	157 for \function{urlparse()}.
2449 8eeecd233d56 added WWW sections Guido van Rossum <guido@python.org> parents: diff changeset	158 \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	159
25815 4a92c7d9d415 Document urldefrag(). Fred Drake <fdrake@acm.org> parents: 20996 diff changeset	160 \begin{funcdesc}{urldefrag}{url}
4a92c7d9d415 Document urldefrag(). Fred Drake <fdrake@acm.org> parents: 20996 diff changeset	161 If \var{url} contains a fragment identifier, returns a modified
4a92c7d9d415 Document urldefrag(). Fred Drake <fdrake@acm.org> parents: 20996 diff changeset	162 version of \var{url} with no fragment identifier, and the fragment
4a92c7d9d415 Document urldefrag(). Fred Drake <fdrake@acm.org> parents: 20996 diff changeset	163 identifier as a separate string. If there is no fragment identifier
4a92c7d9d415 Document urldefrag(). Fred Drake <fdrake@acm.org> parents: 20996 diff changeset	164 in \var{url}, returns \var{url} unmodified and an empty string.
4a92c7d9d415 Document urldefrag(). Fred Drake <fdrake@acm.org> parents: 20996 diff changeset	165 \end{funcdesc}
4a92c7d9d415 Document urldefrag(). Fred Drake <fdrake@acm.org> parents: 20996 diff changeset	166
14153 40447b672064 Move references to RFCs to a "See also" section for consistency with Fred Drake <fdrake@acm.org> parents: 13625 diff changeset	167
40447b672064 Move references to RFCs to a "See also" section for consistency with Fred Drake <fdrake@acm.org> parents: 13625 diff changeset	168 \begin{seealso}
40447b672064 Move references to RFCs to a "See also" section for consistency with Fred Drake <fdrake@acm.org> parents: 13625 diff changeset	169 \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	170 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	171 URLs.}
40447b672064 Move references to RFCs to a "See also" section for consistency with Fred Drake <fdrake@acm.org> parents: 13625 diff changeset	172 \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	173 This Request For Comments includes the rules for joining an
25822 032f196059aa Typo(!): "normal" -> "number" Fred Drake <fdrake@acm.org> parents: 25815 diff changeset	174 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	175 ``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	176 cases.}
14185 93013e4bbe02 Add reference to RFC 2396 in "See also" section. Fred Drake <fdrake@acm.org> parents: 14153 diff changeset	177 \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	178 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	179 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	180 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	181 \end{seealso}
37393 a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	182
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	183
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	184 \subsection{Results of \function{urlparse()} and \function{urlsplit()}
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	185 \label{urlparse-result-object}}
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	186
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	187 The result objects from the \function{urlparse()} and
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	188 \function{urlsplit()} functions are subclasses of the \pytype{tuple}
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	189 type. These subclasses add the attributes described in those
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	190 functions, as well as provide an additional method:
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	191
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	192 \begin{methoddesc}[ParseResult]{geturl}{}
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	193 Return the re-combined version of the original URL as a string.
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	194 This may differ from the original URL in that the scheme will always
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	195 be normalized to lower case and empty components may be dropped.
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	196 Specifically, empty parameters, queries, and fragment identifiers
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	197 will be removed.
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	198
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	199 The result of this method is a fixpoint if passed back through the
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	200 original parsing function:
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	201
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	202 \begin{verbatim}
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	203 >>> import urlparse
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	204 >>> url = 'HTTP://www.Python.org/doc/#'
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	205
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	206 >>> r1 = urlparse.urlsplit(url)
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	207 >>> r1.geturl()
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	208 'http://www.Python.org/doc/'
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	209
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	210 >>> r2 = urlparse.urlsplit(r1.geturl())
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	211 >>> r2.geturl()
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	212 'http://www.Python.org/doc/'
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	213 \end{verbatim}
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	214
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	215 \versionadded{2.5}
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	216 \end{methoddesc}
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	217
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	218 The following classes provide the implementations of the parse results::
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	219
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	220 \begin{classdesc*}{BaseResult}
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	221 Base class for the concrete result classes. This provides most of
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	222 the attribute definitions. It does not provide a \method{geturl()}
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	223 method. It is derived from \class{tuple}, but does not override the
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	224 \method{__init__()} or \method{__new__()} methods.
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	225 \end{classdesc*}
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	226
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	227
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	228 \begin{classdesc}{ParseResult}{scheme, netloc, path, params, query, fragment}
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	229 Concrete class for \function{urlparse()} results. The
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	230 \method{__new__()} method is overridden to support checking that the
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	231 right number of arguments are passed.
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	232 \end{classdesc}
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	233
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	234
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	235 \begin{classdesc}{SplitResult}{scheme, netloc, path, query, fragment}
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	236 Concrete class for \function{urlsplit()} results. The
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	237 \method{__new__()} method is overridden to support checking that the
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	238 right number of arguments are passed.
a6bce7aebe05 Patch #624325: urlparse.urlparse() and urlparse.urlsplit() results Fred Drake <fdrake@acm.org> parents: 37368 diff changeset	239 \end{classdesc}

Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/liburlparse.tex @ 39042:c02fa187e0f4 legacy-trunk