Mercurial > cpython-lru_cache-weakref

annotate Doc/library/urlparse.rst @ 79675:c0a2294de787 2.7

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Issue #16199: Backport 2to3 typo fix from 3.2.
author Chris Jerdonek <chris.jerdonek@gmail.com>
date Thu, 11 Oct 2012 16:15:46 -0700
parents bbfee24e5ad2
children 33895c474b4d
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1 :mod:`urlparse` --- Parse URLs into components
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2 ==============================================
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
4 .. module:: urlparse
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
5 :synopsis: Parse URLs into or assemble them from components.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
6
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
7
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
8 .. index::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
9 single: WWW
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
10 single: World Wide Web
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
11 single: URL
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
12 pair: URL; parsing
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
13 pair: relative; URL
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
14
47928
e16384e3ee22 Doc that urlparse is named urllib.parse in Python 3.0.
Brett Cannon <bcannon@gmail.com>
parents: 46014
diff changeset
15 .. note::
76732
8aab13719c02 Use Python 3 instead of 3.0.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 71952
diff changeset
16 The :mod:`urlparse` module is renamed to :mod:`urllib.parse` in Python 3.
47928
e16384e3ee22 Doc that urlparse is named urllib.parse in Python 3.0.
Brett Cannon <bcannon@gmail.com>
parents: 46014
diff changeset
17 The :term:`2to3` tool will automatically adapt imports when converting
76732
8aab13719c02 Use Python 3 instead of 3.0.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 71952
diff changeset
18 your sources to Python 3.
47928
e16384e3ee22 Doc that urlparse is named urllib.parse in Python 3.0.
Brett Cannon <bcannon@gmail.com>
parents: 46014
diff changeset
19
71952
b5674229d0f9 Backport source links from 3.x.
Éric Araujo <merwok@netwok.org>
parents: 68256
diff changeset
20 **Source code:** :source:`Lib/urlparse.py`
b5674229d0f9 Backport source links from 3.x.
Éric Araujo <merwok@netwok.org>
parents: 68256
diff changeset
21
b5674229d0f9 Backport source links from 3.x.
Éric Araujo <merwok@netwok.org>
parents: 68256
diff changeset
22 --------------
47928
e16384e3ee22 Doc that urlparse is named urllib.parse in Python 3.0.
Brett Cannon <bcannon@gmail.com>
parents: 46014
diff changeset
23
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
24 This module defines a standard interface to break Uniform Resource Locator (URL)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
25 strings up in components (addressing scheme, network location, path etc.), to
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
26 combine the components back into a URL string, and to convert a "relative URL"
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
27 to an absolute URL given a "base URL."
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
28
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
29 The module has been designed to match the Internet RFC on Relative Uniform
77843
bbfee24e5ad2 urlparse docs clean up
Senthil Kumaran <senthil@uthcode.com>
parents: 76732
diff changeset
30 Resource Locators. It supports the following URL schemes: ``file``, ``ftp``,
bbfee24e5ad2 urlparse docs clean up
Senthil Kumaran <senthil@uthcode.com>
parents: 76732
diff changeset
31 ``gopher``, ``hdl``, ``http``, ``https``, ``imap``, ``mailto``, ``mms``,
bbfee24e5ad2 urlparse docs clean up
Senthil Kumaran <senthil@uthcode.com>
parents: 76732
diff changeset
32 ``news``, ``nntp``, ``prospero``, ``rsync``, ``rtsp``, ``rtspu``, ``sftp``,
bbfee24e5ad2 urlparse docs clean up
Senthil Kumaran <senthil@uthcode.com>
parents: 76732
diff changeset
33 ``shttp``, ``sip``, ``sips``, ``snews``, ``svn``, ``svn+ssh``, ``telnet``,
bbfee24e5ad2 urlparse docs clean up
Senthil Kumaran <senthil@uthcode.com>
parents: 76732
diff changeset
34 ``wais``.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
35
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
36 .. versionadded:: 2.5
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
37 Support for the ``sftp`` and ``sips`` schemes.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
38
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
39 The :mod:`urlparse` module defines the following functions:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
40
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
41
61906
e8a9393a0748 Merged revisions 81521 via svnmerge from
R. David Murray <rdmurray@bitdance.com>
parents: 60837
diff changeset
42 .. function:: urlparse(urlstring[, scheme[, allow_fragments]])
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
43
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
44 Parse a URL into six components, returning a 6-tuple. This corresponds to the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
45 general structure of a URL: ``scheme://netloc/path;parameters?query#fragment``.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
46 Each tuple item is a string, possibly empty. The components are not broken up in
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
47 smaller parts (for example, the network location is a single string), and %
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
48 escapes are not expanded. The delimiters as shown above are not part of the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
49 result, except for a leading slash in the *path* component, which is retained if
46014
31cf38bdaac0 Enable doctest running for several other documents.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
50 present. For example:
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
51
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
52 >>> from urlparse import urlparse
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
53 >>> o = urlparse('http://www.cwi.nl:80/%7Eguido/Python.html')
46014
31cf38bdaac0 Enable doctest running for several other documents.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
54 >>> o # doctest: +NORMALIZE_WHITESPACE
31cf38bdaac0 Enable doctest running for several other documents.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
55 ParseResult(scheme='http', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',
31cf38bdaac0 Enable doctest running for several other documents.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
56 params='', query='', fragment='')
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
57 >>> o.scheme
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
58 'http'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
59 >>> o.port
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
60 80
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
61 >>> o.geturl()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
62 'http://www.cwi.nl:80/%7Eguido/Python.html'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
63
63714
1489f399aba1 Fix Issue754016 - urlparse goes wrong with IP:port without scheme
Senthil Kumaran <orsenthil@gmail.com>
parents: 61904
diff changeset
64
66063
8f09eedcd70a Merged revisions 86296 via svnmerge from
Senthil Kumaran <orsenthil@gmail.com>
parents: 66024
diff changeset
65 Following the syntax specifications in :rfc:`1808`, urlparse recognizes
8f09eedcd70a Merged revisions 86296 via svnmerge from
Senthil Kumaran <orsenthil@gmail.com>
parents: 66024
diff changeset
66 a netloc only if it is properly introduced by '//'. Otherwise the
8f09eedcd70a Merged revisions 86296 via svnmerge from
Senthil Kumaran <orsenthil@gmail.com>
parents: 66024
diff changeset
67 input is presumed to be a relative URL and thus to start with
8f09eedcd70a Merged revisions 86296 via svnmerge from
Senthil Kumaran <orsenthil@gmail.com>
parents: 66024
diff changeset
68 a path component.
63714
1489f399aba1 Fix Issue754016 - urlparse goes wrong with IP:port without scheme
Senthil Kumaran <orsenthil@gmail.com>
parents: 61904
diff changeset
69
1489f399aba1 Fix Issue754016 - urlparse goes wrong with IP:port without scheme
Senthil Kumaran <orsenthil@gmail.com>
parents: 61904
diff changeset
70 >>> from urlparse import urlparse
1489f399aba1 Fix Issue754016 - urlparse goes wrong with IP:port without scheme
Senthil Kumaran <orsenthil@gmail.com>
parents: 61904
diff changeset
71 >>> urlparse('//www.cwi.nl:80/%7Eguido/Python.html')
1489f399aba1 Fix Issue754016 - urlparse goes wrong with IP:port without scheme
Senthil Kumaran <orsenthil@gmail.com>
parents: 61904
diff changeset
72 ParseResult(scheme='', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',
1489f399aba1 Fix Issue754016 - urlparse goes wrong with IP:port without scheme
Senthil Kumaran <orsenthil@gmail.com>
parents: 61904
diff changeset
73 params='', query='', fragment='')
1489f399aba1 Fix Issue754016 - urlparse goes wrong with IP:port without scheme
Senthil Kumaran <orsenthil@gmail.com>
parents: 61904
diff changeset
74 >>> urlparse('www.cwi.nl:80/%7Eguido/Python.html')
1489f399aba1 Fix Issue754016 - urlparse goes wrong with IP:port without scheme
Senthil Kumaran <orsenthil@gmail.com>
parents: 61904
diff changeset
75 ParseResult(scheme='', netloc='', path='www.cwi.nl:80/%7Eguido/Python.html',
1489f399aba1 Fix Issue754016 - urlparse goes wrong with IP:port without scheme
Senthil Kumaran <orsenthil@gmail.com>
parents: 61904
diff changeset
76 params='', query='', fragment='')
1489f399aba1 Fix Issue754016 - urlparse goes wrong with IP:port without scheme
Senthil Kumaran <orsenthil@gmail.com>
parents: 61904
diff changeset
77 >>> urlparse('help/Python.html')
1489f399aba1 Fix Issue754016 - urlparse goes wrong with IP:port without scheme
Senthil Kumaran <orsenthil@gmail.com>
parents: 61904
diff changeset
78 ParseResult(scheme='', netloc='', path='help/Python.html', params='',
1489f399aba1 Fix Issue754016 - urlparse goes wrong with IP:port without scheme
Senthil Kumaran <orsenthil@gmail.com>
parents: 61904
diff changeset
79 query='', fragment='')
1489f399aba1 Fix Issue754016 - urlparse goes wrong with IP:port without scheme
Senthil Kumaran <orsenthil@gmail.com>
parents: 61904
diff changeset
80
61906
e8a9393a0748 Merged revisions 81521 via svnmerge from
R. David Murray <rdmurray@bitdance.com>
parents: 60837
diff changeset
81 If the *scheme* argument is specified, it gives the default addressing
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
82 scheme, to be used only if the URL does not specify one. The default value for
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
83 this argument is the empty string.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
84
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
85 If the *allow_fragments* argument is false, fragment identifiers are not
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
86 allowed, even if the URL's addressing scheme normally does support them. The
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
87 default value for this argument is :const:`True`.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
88
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
89 The return value is actually an instance of a subclass of :class:`tuple`. This
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
90 class has the following additional read-only convenience attributes:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
91
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
92 +------------------+-------+--------------------------+----------------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
93 | Attribute | Index | Value | Value if not present |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
94 +==================+=======+==========================+======================+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
95 | :attr:`scheme` | 0 | URL scheme specifier | empty string |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
96 +------------------+-------+--------------------------+----------------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
97 | :attr:`netloc` | 1 | Network location part | empty string |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
98 +------------------+-------+--------------------------+----------------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
99 | :attr:`path` | 2 | Hierarchical path | empty string |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
100 +------------------+-------+--------------------------+----------------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
101 | :attr:`params` | 3 | Parameters for last path | empty string |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
102 | | | element | |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
103 +------------------+-------+--------------------------+----------------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
104 | :attr:`query` | 4 | Query component | empty string |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
105 +------------------+-------+--------------------------+----------------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
106 | :attr:`fragment` | 5 | Fragment identifier | empty string |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
107 +------------------+-------+--------------------------+----------------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
108 | :attr:`username` | | User name | :const:`None` |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
109 +------------------+-------+--------------------------+----------------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
110 | :attr:`password` | | Password | :const:`None` |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
111 +------------------+-------+--------------------------+----------------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
112 | :attr:`hostname` | | Host name (lower case) | :const:`None` |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
113 +------------------+-------+--------------------------+----------------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
114 | :attr:`port` | | Port number as integer, | :const:`None` |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
115 | | | if present | |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
116 +------------------+-------+--------------------------+----------------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
117
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
118 See section :ref:`urlparse-result-object` for more information on the result
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
119 object.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
120
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
121 .. versionchanged:: 2.5
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
122 Added attributes to return value.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
123
60857
9dc864ef6425 Changed tests to only urlparse one, which was enough, addressed Ezio's comment
Senthil Kumaran <orsenthil@gmail.com>
parents: 60835
diff changeset
124 .. versionchanged:: 2.7
9dc864ef6425 Changed tests to only urlparse one, which was enough, addressed Ezio's comment
Senthil Kumaran <orsenthil@gmail.com>
parents: 60835
diff changeset
125 Added IPv6 URL parsing capabilities.
9dc864ef6425 Changed tests to only urlparse one, which was enough, addressed Ezio's comment
Senthil Kumaran <orsenthil@gmail.com>
parents: 60835
diff changeset
126
9dc864ef6425 Changed tests to only urlparse one, which was enough, addressed Ezio's comment
Senthil Kumaran <orsenthil@gmail.com>
parents: 60835
diff changeset
127
48995
2b855a947f0f Issue 600362: Relocated parse_qs() and parse_qsl(), from the cgi module
Facundo Batista <facundobatista@gmail.com>
parents: 47928
diff changeset
128 .. function:: parse_qs(qs[, keep_blank_values[, strict_parsing]])
2b855a947f0f Issue 600362: Relocated parse_qs() and parse_qsl(), from the cgi module
Facundo Batista <facundobatista@gmail.com>
parents: 47928
diff changeset
129
2b855a947f0f Issue 600362: Relocated parse_qs() and parse_qsl(), from the cgi module
Facundo Batista <facundobatista@gmail.com>
parents: 47928
diff changeset
130 Parse a query string given as a string argument (data of type
2b855a947f0f Issue 600362: Relocated parse_qs() and parse_qsl(), from the cgi module
Facundo Batista <facundobatista@gmail.com>
parents: 47928
diff changeset
131 :mimetype:`application/x-www-form-urlencoded`). Data are returned as a
2b855a947f0f Issue 600362: Relocated parse_qs() and parse_qsl(), from the cgi module
Facundo Batista <facundobatista@gmail.com>
parents: 47928
diff changeset
132 dictionary. The dictionary keys are the unique query variable names and the
2b855a947f0f Issue 600362: Relocated parse_qs() and parse_qsl(), from the cgi module
Facundo Batista <facundobatista@gmail.com>
parents: 47928
diff changeset
133 values are lists of values for each name.
2b855a947f0f Issue 600362: Relocated parse_qs() and parse_qsl(), from the cgi module
Facundo Batista <facundobatista@gmail.com>
parents: 47928
diff changeset
134
2b855a947f0f Issue 600362: Relocated parse_qs() and parse_qsl(), from the cgi module
Facundo Batista <facundobatista@gmail.com>
parents: 47928
diff changeset
135 The optional argument *keep_blank_values* is a flag indicating whether blank
63887
0ae706a71a3a Merged revisions 83900 via svnmerge from
Senthil Kumaran <orsenthil@gmail.com>
parents: 63714
diff changeset
136 values in percent-encoded queries should be treated as blank strings. A true value
48995
2b855a947f0f Issue 600362: Relocated parse_qs() and parse_qsl(), from the cgi module
Facundo Batista <facundobatista@gmail.com>
parents: 47928
diff changeset
137 indicates that blanks should be retained as blank strings. The default false
2b855a947f0f Issue 600362: Relocated parse_qs() and parse_qsl(), from the cgi module
Facundo Batista <facundobatista@gmail.com>
parents: 47928
diff changeset
138 value indicates that blank values are to be ignored and treated as if they were
2b855a947f0f Issue 600362: Relocated parse_qs() and parse_qsl(), from the cgi module
Facundo Batista <facundobatista@gmail.com>
parents: 47928
diff changeset
139 not included.
2b855a947f0f Issue 600362: Relocated parse_qs() and parse_qsl(), from the cgi module
Facundo Batista <facundobatista@gmail.com>
parents: 47928
diff changeset
140
2b855a947f0f Issue 600362: Relocated parse_qs() and parse_qsl(), from the cgi module
Facundo Batista <facundobatista@gmail.com>
parents: 47928
diff changeset
141 The optional argument *strict_parsing* is a flag indicating what to do with
2b855a947f0f Issue 600362: Relocated parse_qs() and parse_qsl(), from the cgi module
Facundo Batista <facundobatista@gmail.com>
parents: 47928
diff changeset
142 parsing errors. If false (the default), errors are silently ignored. If true,
2b855a947f0f Issue 600362: Relocated parse_qs() and parse_qsl(), from the cgi module
Facundo Batista <facundobatista@gmail.com>
parents: 47928
diff changeset
143 errors raise a :exc:`ValueError` exception.
2b855a947f0f Issue 600362: Relocated parse_qs() and parse_qsl(), from the cgi module
Facundo Batista <facundobatista@gmail.com>
parents: 47928
diff changeset
144
2b855a947f0f Issue 600362: Relocated parse_qs() and parse_qsl(), from the cgi module
Facundo Batista <facundobatista@gmail.com>
parents: 47928
diff changeset
145 Use the :func:`urllib.urlencode` function to convert such dictionaries into
2b855a947f0f Issue 600362: Relocated parse_qs() and parse_qsl(), from the cgi module
Facundo Batista <facundobatista@gmail.com>
parents: 47928
diff changeset
146 query strings.
2b855a947f0f Issue 600362: Relocated parse_qs() and parse_qsl(), from the cgi module
Facundo Batista <facundobatista@gmail.com>
parents: 47928
diff changeset
147
57104
c94e3bf8392b Merged revisions 76095 via svnmerge from
Georg Brandl <georg@python.org>
parents: 50522
diff changeset
148 .. versionadded:: 2.6
c94e3bf8392b Merged revisions 76095 via svnmerge from
Georg Brandl <georg@python.org>
parents: 50522
diff changeset
149 Copied from the :mod:`cgi` module.
c94e3bf8392b Merged revisions 76095 via svnmerge from
Georg Brandl <georg@python.org>
parents: 50522
diff changeset
150
48995
2b855a947f0f Issue 600362: Relocated parse_qs() and parse_qsl(), from the cgi module
Facundo Batista <facundobatista@gmail.com>
parents: 47928
diff changeset
151
2b855a947f0f Issue 600362: Relocated parse_qs() and parse_qsl(), from the cgi module
Facundo Batista <facundobatista@gmail.com>
parents: 47928
diff changeset
152 .. function:: parse_qsl(qs[, keep_blank_values[, strict_parsing]])
2b855a947f0f Issue 600362: Relocated parse_qs() and parse_qsl(), from the cgi module
Facundo Batista <facundobatista@gmail.com>
parents: 47928
diff changeset
153
2b855a947f0f Issue 600362: Relocated parse_qs() and parse_qsl(), from the cgi module
Facundo Batista <facundobatista@gmail.com>
parents: 47928
diff changeset
154 Parse a query string given as a string argument (data of type
2b855a947f0f Issue 600362: Relocated parse_qs() and parse_qsl(), from the cgi module
Facundo Batista <facundobatista@gmail.com>
parents: 47928
diff changeset
155 :mimetype:`application/x-www-form-urlencoded`). Data are returned as a list of
2b855a947f0f Issue 600362: Relocated parse_qs() and parse_qsl(), from the cgi module
Facundo Batista <facundobatista@gmail.com>
parents: 47928
diff changeset
156 name, value pairs.
2b855a947f0f Issue 600362: Relocated parse_qs() and parse_qsl(), from the cgi module
Facundo Batista <facundobatista@gmail.com>
parents: 47928
diff changeset
157
2b855a947f0f Issue 600362: Relocated parse_qs() and parse_qsl(), from the cgi module
Facundo Batista <facundobatista@gmail.com>
parents: 47928
diff changeset
158 The optional argument *keep_blank_values* is a flag indicating whether blank
63887
0ae706a71a3a Merged revisions 83900 via svnmerge from
Senthil Kumaran <orsenthil@gmail.com>
parents: 63714
diff changeset
159 values in percent-encoded queries should be treated as blank strings. A true value
48995
2b855a947f0f Issue 600362: Relocated parse_qs() and parse_qsl(), from the cgi module
Facundo Batista <facundobatista@gmail.com>
parents: 47928
diff changeset
160 indicates that blanks should be retained as blank strings. The default false
2b855a947f0f Issue 600362: Relocated parse_qs() and parse_qsl(), from the cgi module
Facundo Batista <facundobatista@gmail.com>
parents: 47928
diff changeset
161 value indicates that blank values are to be ignored and treated as if they were
2b855a947f0f Issue 600362: Relocated parse_qs() and parse_qsl(), from the cgi module
Facundo Batista <facundobatista@gmail.com>
parents: 47928
diff changeset
162 not included.
2b855a947f0f Issue 600362: Relocated parse_qs() and parse_qsl(), from the cgi module
Facundo Batista <facundobatista@gmail.com>
parents: 47928
diff changeset
163
2b855a947f0f Issue 600362: Relocated parse_qs() and parse_qsl(), from the cgi module
Facundo Batista <facundobatista@gmail.com>
parents: 47928
diff changeset
164 The optional argument *strict_parsing* is a flag indicating what to do with
2b855a947f0f Issue 600362: Relocated parse_qs() and parse_qsl(), from the cgi module
Facundo Batista <facundobatista@gmail.com>
parents: 47928
diff changeset
165 parsing errors. If false (the default), errors are silently ignored. If true,
2b855a947f0f Issue 600362: Relocated parse_qs() and parse_qsl(), from the cgi module
Facundo Batista <facundobatista@gmail.com>
parents: 47928
diff changeset
166 errors raise a :exc:`ValueError` exception.
2b855a947f0f Issue 600362: Relocated parse_qs() and parse_qsl(), from the cgi module
Facundo Batista <facundobatista@gmail.com>
parents: 47928
diff changeset
167
2b855a947f0f Issue 600362: Relocated parse_qs() and parse_qsl(), from the cgi module
Facundo Batista <facundobatista@gmail.com>
parents: 47928
diff changeset
168 Use the :func:`urllib.urlencode` function to convert such lists of pairs into
2b855a947f0f Issue 600362: Relocated parse_qs() and parse_qsl(), from the cgi module
Facundo Batista <facundobatista@gmail.com>
parents: 47928
diff changeset
169 query strings.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
170
57104
c94e3bf8392b Merged revisions 76095 via svnmerge from
Georg Brandl <georg@python.org>
parents: 50522
diff changeset
171 .. versionadded:: 2.6
c94e3bf8392b Merged revisions 76095 via svnmerge from
Georg Brandl <georg@python.org>
parents: 50522
diff changeset
172 Copied from the :mod:`cgi` module.
c94e3bf8392b Merged revisions 76095 via svnmerge from
Georg Brandl <georg@python.org>
parents: 50522
diff changeset
173
c94e3bf8392b Merged revisions 76095 via svnmerge from
Georg Brandl <georg@python.org>
parents: 50522
diff changeset
174
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
175 .. function:: urlunparse(parts)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
176
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
177 Construct a URL from a tuple as returned by ``urlparse()``. The *parts* argument
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
178 can be any six-item iterable. This may result in a slightly different, but
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
179 equivalent URL, if the URL that was parsed originally had unnecessary delimiters
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
180 (for example, a ? with an empty query; the RFC states that these are
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
181 equivalent).
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
182
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
183
61906
e8a9393a0748 Merged revisions 81521 via svnmerge from
R. David Murray <rdmurray@bitdance.com>
parents: 60837
diff changeset
184 .. function:: urlsplit(urlstring[, scheme[, allow_fragments]])
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
185
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
186 This is similar to :func:`urlparse`, but does not split the params from the URL.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
187 This should generally be used instead of :func:`urlparse` if the more recent URL
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
188 syntax allowing parameters to be applied to each segment of the *path* portion
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
189 of the URL (see :rfc:`2396`) is wanted. A separate function is needed to
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
190 separate the path segments and parameters. This function returns a 5-tuple:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
191 (addressing scheme, network location, path, query, fragment identifier).
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
192
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
193 The return value is actually an instance of a subclass of :class:`tuple`. This
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
194 class has the following additional read-only convenience attributes:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
195
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
196 +------------------+-------+-------------------------+----------------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
197 | Attribute | Index | Value | Value if not present |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
198 +==================+=======+=========================+======================+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
199 | :attr:`scheme` | 0 | URL scheme specifier | empty string |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
200 +------------------+-------+-------------------------+----------------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
201 | :attr:`netloc` | 1 | Network location part | empty string |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
202 +------------------+-------+-------------------------+----------------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
203 | :attr:`path` | 2 | Hierarchical path | empty string |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
204 +------------------+-------+-------------------------+----------------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
205 | :attr:`query` | 3 | Query component | empty string |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
206 +------------------+-------+-------------------------+----------------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
207 | :attr:`fragment` | 4 | Fragment identifier | empty string |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
208 +------------------+-------+-------------------------+----------------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
209 | :attr:`username` | | User name | :const:`None` |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
210 +------------------+-------+-------------------------+----------------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
211 | :attr:`password` | | Password | :const:`None` |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
212 +------------------+-------+-------------------------+----------------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
213 | :attr:`hostname` | | Host name (lower case) | :const:`None` |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
214 +------------------+-------+-------------------------+----------------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
215 | :attr:`port` | | Port number as integer, | :const:`None` |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
216 | | | if present | |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
217 +------------------+-------+-------------------------+----------------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
218
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
219 See section :ref:`urlparse-result-object` for more information on the result
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
220 object.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
221
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
222 .. versionadded:: 2.2
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
223
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
224 .. versionchanged:: 2.5
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
225 Added attributes to return value.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
226
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
227
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
228 .. function:: urlunsplit(parts)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
229
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
230 Combine the elements of a tuple as returned by :func:`urlsplit` into a complete
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
231 URL as a string. The *parts* argument can be any five-item iterable. This may
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
232 result in a slightly different, but equivalent URL, if the URL that was parsed
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
233 originally had unnecessary delimiters (for example, a ? with an empty query; the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
234 RFC states that these are equivalent).
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
235
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
236 .. versionadded:: 2.2
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
237
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
238
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
239 .. function:: urljoin(base, url[, allow_fragments])
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
240
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
241 Construct a full ("absolute") URL by combining a "base URL" (*base*) with
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
242 another URL (*url*). Informally, this uses components of the base URL, in
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
243 particular the addressing scheme, the network location and (part of) the path,
46014
31cf38bdaac0 Enable doctest running for several other documents.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
244 to provide missing components in the relative URL. For example:
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
245
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
246 >>> from urlparse import urljoin
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
247 >>> urljoin('http://www.cwi.nl/%7Eguido/Python.html', 'FAQ.html')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
248 'http://www.cwi.nl/%7Eguido/FAQ.html'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
249
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
250 The *allow_fragments* argument has the same meaning and default as for
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
251 :func:`urlparse`.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
252
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
253 .. note::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
254
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
255 If *url* is an absolute URL (that is, starting with ``//`` or ``scheme://``),
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
256 the *url*'s host name and/or scheme will be present in the result. For example:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
257
46014
31cf38bdaac0 Enable doctest running for several other documents.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
258 .. doctest::
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
259
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
260 >>> urljoin('http://www.cwi.nl/%7Eguido/Python.html',
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
261 ... '//www.python.org/%7Eguido')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
262 'http://www.python.org/%7Eguido'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
263
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
264 If you do not want that behavior, preprocess the *url* with :func:`urlsplit` and
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
265 :func:`urlunsplit`, removing possible *scheme* and *netloc* parts.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
266
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
267
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
268 .. function:: urldefrag(url)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
269
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
270 If *url* contains a fragment identifier, returns a modified version of *url*
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
271 with no fragment identifier, and the fragment identifier as a separate string.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
272 If there is no fragment identifier in *url*, returns *url* unmodified and an
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
273 empty string.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
274
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
275
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
276 .. seealso::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
277
60837
4b01e80d6c1f Merged revisions 80336 via svnmerge from
Senthil Kumaran <orsenthil@gmail.com>
parents: 57104
diff changeset
278 :rfc:`3986` - Uniform Resource Identifiers
4b01e80d6c1f Merged revisions 80336 via svnmerge from
Senthil Kumaran <orsenthil@gmail.com>
parents: 57104
diff changeset
279 This is the current standard (STD66). Any changes to urlparse module
4b01e80d6c1f Merged revisions 80336 via svnmerge from
Senthil Kumaran <orsenthil@gmail.com>
parents: 57104
diff changeset
280 should conform to this. Certain deviations could be observed, which are
60857
9dc864ef6425 Changed tests to only urlparse one, which was enough, addressed Ezio's comment
Senthil Kumaran <orsenthil@gmail.com>
parents: 60835
diff changeset
281 mostly due backward compatiblity purposes and for certain de-facto
60837
4b01e80d6c1f Merged revisions 80336 via svnmerge from
Senthil Kumaran <orsenthil@gmail.com>
parents: 57104
diff changeset
282 parsing requirements as commonly observed in major browsers.
4b01e80d6c1f Merged revisions 80336 via svnmerge from
Senthil Kumaran <orsenthil@gmail.com>
parents: 57104
diff changeset
283
60835
2b09d821bce1 Updated the RFCs list in the See Also section of urlparse.rst
Senthil Kumaran <orsenthil@gmail.com>
parents: 57104
diff changeset
284 :rfc:`2732` - Format for Literal IPv6 Addresses in URL's.
2b09d821bce1 Updated the RFCs list in the See Also section of urlparse.rst
Senthil Kumaran <orsenthil@gmail.com>
parents: 57104
diff changeset
285 This specifies the parsing requirements of IPv6 URLs.
2b09d821bce1 Updated the RFCs list in the See Also section of urlparse.rst
Senthil Kumaran <orsenthil@gmail.com>
parents: 57104
diff changeset
286
60837
4b01e80d6c1f Merged revisions 80336 via svnmerge from
Senthil Kumaran <orsenthil@gmail.com>
parents: 57104
diff changeset
287 :rfc:`2396` - Uniform Resource Identifiers (URI): Generic Syntax
4b01e80d6c1f Merged revisions 80336 via svnmerge from
Senthil Kumaran <orsenthil@gmail.com>
parents: 57104
diff changeset
288 Document describing the generic syntactic requirements for both Uniform Resource
4b01e80d6c1f Merged revisions 80336 via svnmerge from
Senthil Kumaran <orsenthil@gmail.com>
parents: 57104
diff changeset
289 Names (URNs) and Uniform Resource Locators (URLs).
4b01e80d6c1f Merged revisions 80336 via svnmerge from
Senthil Kumaran <orsenthil@gmail.com>
parents: 57104
diff changeset
290
4b01e80d6c1f Merged revisions 80336 via svnmerge from
Senthil Kumaran <orsenthil@gmail.com>
parents: 57104
diff changeset
291 :rfc:`2368` - The mailto URL scheme.
4b01e80d6c1f Merged revisions 80336 via svnmerge from
Senthil Kumaran <orsenthil@gmail.com>
parents: 57104
diff changeset
292 Parsing requirements for mailto url schemes.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
293
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
294 :rfc:`1808` - Relative Uniform Resource Locators
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
295 This Request For Comments includes the rules for joining an absolute and a
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
296 relative URL, including a fair number of "Abnormal Examples" which govern the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
297 treatment of border cases.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
298
60837
4b01e80d6c1f Merged revisions 80336 via svnmerge from
Senthil Kumaran <orsenthil@gmail.com>
parents: 57104
diff changeset
299 :rfc:`1738` - Uniform Resource Locators (URL)
4b01e80d6c1f Merged revisions 80336 via svnmerge from
Senthil Kumaran <orsenthil@gmail.com>
parents: 57104
diff changeset
300 This specifies the formal syntax and semantics of absolute URLs.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
301
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
302
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
303 .. _urlparse-result-object:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
304
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
305 Results of :func:`urlparse` and :func:`urlsplit`
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
306 ------------------------------------------------
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
307
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
308 The result objects from the :func:`urlparse` and :func:`urlsplit` functions are
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
309 subclasses of the :class:`tuple` type. These subclasses add the attributes
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
310 described in those functions, as well as provide an additional method:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
311
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
312
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
313 .. method:: ParseResult.geturl()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
314
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
315 Return the re-combined version of the original URL as a string. This may differ
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
316 from the original URL in that the scheme will always be normalized to lower case
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
317 and empty components may be dropped. Specifically, empty parameters, queries,
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
318 and fragment identifiers will be removed.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
319
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
320 The result of this method is a fixpoint if passed back through the original
46014
31cf38bdaac0 Enable doctest running for several other documents.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
321 parsing function:
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
322
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
323 >>> import urlparse
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
324 >>> url = 'HTTP://www.Python.org/doc/#'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
325
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
326 >>> r1 = urlparse.urlsplit(url)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
327 >>> r1.geturl()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
328 'http://www.Python.org/doc/'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
329
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
330 >>> r2 = urlparse.urlsplit(r1.geturl())
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
331 >>> r2.geturl()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
332 'http://www.Python.org/doc/'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
333
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
334 .. versionadded:: 2.5
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
335
50522
ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48995
diff changeset
336 The following classes provide the implementations of the parse results:
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
337
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
338
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
339 .. class:: BaseResult
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
340
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
341 Base class for the concrete result classes. This provides most of the attribute
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
342 definitions. It does not provide a :meth:`geturl` method. It is derived from
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
343 :class:`tuple`, but does not override the :meth:`__init__` or :meth:`__new__`
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
344 methods.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
345
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
346
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
347 .. class:: ParseResult(scheme, netloc, path, params, query, fragment)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
348
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
349 Concrete class for :func:`urlparse` results. The :meth:`__new__` method is
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
350 overridden to support checking that the right number of arguments are passed.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
351
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
352
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
353 .. class:: SplitResult(scheme, netloc, path, query, fragment)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
354
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
355 Concrete class for :func:`urlsplit` results. The :meth:`__new__` method is
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
356 overridden to support checking that the right number of arguments are passed.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
357