1:mod:`urllib.parse` --- Parse URLs into components 2================================================== 3 4.. module:: urllib.parse 5 :synopsis: Parse URLs into or assemble them from components. 6 7**Source code:** :source:`Lib/urllib/parse.py` 8 9.. index:: 10 single: WWW 11 single: World Wide Web 12 single: URL 13 pair: URL; parsing 14 pair: relative; URL 15 16-------------- 17 18This module defines a standard interface to break Uniform Resource Locator (URL) 19strings up in components (addressing scheme, network location, path etc.), to 20combine the components back into a URL string, and to convert a "relative URL" 21to an absolute URL given a "base URL." 22 23The module has been designed to match the Internet RFC on Relative Uniform 24Resource Locators. It supports the following URL schemes: ``file``, ``ftp``, 25``gopher``, ``hdl``, ``http``, ``https``, ``imap``, ``mailto``, ``mms``, 26``news``, ``nntp``, ``prospero``, ``rsync``, ``rtsp``, ``rtspu``, ``sftp``, 27``shttp``, ``sip``, ``sips``, ``snews``, ``svn``, ``svn+ssh``, ``telnet``, 28``wais``, ``ws``, ``wss``. 29 30The :mod:`urllib.parse` module defines functions that fall into two broad 31categories: URL parsing and URL quoting. These are covered in detail in 32the following sections. 33 34URL Parsing 35----------- 36 37The URL parsing functions focus on splitting a URL string into its components, 38or on combining URL components into a URL string. 39 40.. function:: urlparse(urlstring, scheme='', allow_fragments=True) 41 42 Parse a URL into six components, returning a 6-tuple. This corresponds to the 43 general structure of a URL: ``scheme://netloc/path;parameters?query#fragment``. 44 Each tuple item is a string, possibly empty. The components are not broken up in 45 smaller parts (for example, the network location is a single string), and % 46 escapes are not expanded. The delimiters as shown above are not part of the 47 result, except for a leading slash in the *path* component, which is retained if 48 present. For example: 49 50 >>> from urllib.parse import urlparse 51 >>> o = urlparse('http://www.cwi.nl:80/%7Eguido/Python.html') 52 >>> o # doctest: +NORMALIZE_WHITESPACE 53 ParseResult(scheme='http', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html', 54 params='', query='', fragment='') 55 >>> o.scheme 56 'http' 57 >>> o.port 58 80 59 >>> o.geturl() 60 'http://www.cwi.nl:80/%7Eguido/Python.html' 61 62 Following the syntax specifications in :rfc:`1808`, urlparse recognizes 63 a netloc only if it is properly introduced by '//'. Otherwise the 64 input is presumed to be a relative URL and thus to start with 65 a path component. 66 67 .. doctest:: 68 :options: +NORMALIZE_WHITESPACE 69 70 >>> from urllib.parse import urlparse 71 >>> urlparse('//www.cwi.nl:80/%7Eguido/Python.html') 72 ParseResult(scheme='', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html', 73 params='', query='', fragment='') 74 >>> urlparse('www.cwi.nl/%7Eguido/Python.html') 75 ParseResult(scheme='', netloc='', path='www.cwi.nl/%7Eguido/Python.html', 76 params='', query='', fragment='') 77 >>> urlparse('help/Python.html') 78 ParseResult(scheme='', netloc='', path='help/Python.html', params='', 79 query='', fragment='') 80 81 The *scheme* argument gives the default addressing scheme, to be 82 used only if the URL does not specify one. It should be the same type 83 (text or bytes) as *urlstring*, except that the default value ``''`` is 84 always allowed, and is automatically converted to ``b''`` if appropriate. 85 86 If the *allow_fragments* argument is false, fragment identifiers are not 87 recognized. Instead, they are parsed as part of the path, parameters 88 or query component, and :attr:`fragment` is set to the empty string in 89 the return value. 90 91 The return value is actually an instance of a subclass of :class:`tuple`. This 92 class has the following additional read-only convenience attributes: 93 94 +------------------+-------+--------------------------+----------------------+ 95 | Attribute | Index | Value | Value if not present | 96 +==================+=======+==========================+======================+ 97 | :attr:`scheme` | 0 | URL scheme specifier | *scheme* parameter | 98 +------------------+-------+--------------------------+----------------------+ 99 | :attr:`netloc` | 1 | Network location part | empty string | 100 +------------------+-------+--------------------------+----------------------+ 101 | :attr:`path` | 2 | Hierarchical path | empty string | 102 +------------------+-------+--------------------------+----------------------+ 103 | :attr:`params` | 3 | Parameters for last path | empty string | 104 | | | element | | 105 +------------------+-------+--------------------------+----------------------+ 106 | :attr:`query` | 4 | Query component | empty string | 107 +------------------+-------+--------------------------+----------------------+ 108 | :attr:`fragment` | 5 | Fragment identifier | empty string | 109 +------------------+-------+--------------------------+----------------------+ 110 | :attr:`username` | | User name | :const:`None` | 111 +------------------+-------+--------------------------+----------------------+ 112 | :attr:`password` | | Password | :const:`None` | 113 +------------------+-------+--------------------------+----------------------+ 114 | :attr:`hostname` | | Host name (lower case) | :const:`None` | 115 +------------------+-------+--------------------------+----------------------+ 116 | :attr:`port` | | Port number as integer, | :const:`None` | 117 | | | if present | | 118 +------------------+-------+--------------------------+----------------------+ 119 120 Reading the :attr:`port` attribute will raise a :exc:`ValueError` if 121 an invalid port is specified in the URL. See section 122 :ref:`urlparse-result-object` for more information on the result object. 123 124 Unmatched square brackets in the :attr:`netloc` attribute will raise a 125 :exc:`ValueError`. 126 127 Characters in the :attr:`netloc` attribute that decompose under NFKC 128 normalization (as used by the IDNA encoding) into any of ``/``, ``?``, 129 ``#``, ``@``, or ``:`` will raise a :exc:`ValueError`. If the URL is 130 decomposed before parsing, no error will be raised. 131 132 .. versionchanged:: 3.2 133 Added IPv6 URL parsing capabilities. 134 135 .. versionchanged:: 3.3 136 The fragment is now parsed for all URL schemes (unless *allow_fragment* is 137 false), in accordance with :rfc:`3986`. Previously, a whitelist of 138 schemes that support fragments existed. 139 140 .. versionchanged:: 3.6 141 Out-of-range port numbers now raise :exc:`ValueError`, instead of 142 returning :const:`None`. 143 144 .. versionchanged:: 3.7.3 145 Characters that affect netloc parsing under NFKC normalization will 146 now raise :exc:`ValueError`. 147 148 149.. function:: parse_qs(qs, keep_blank_values=False, strict_parsing=False, encoding='utf-8', errors='replace', max_num_fields=None) 150 151 Parse a query string given as a string argument (data of type 152 :mimetype:`application/x-www-form-urlencoded`). Data are returned as a 153 dictionary. The dictionary keys are the unique query variable names and the 154 values are lists of values for each name. 155 156 The optional argument *keep_blank_values* is a flag indicating whether blank 157 values in percent-encoded queries should be treated as blank strings. A true value 158 indicates that blanks should be retained as blank strings. The default false 159 value indicates that blank values are to be ignored and treated as if they were 160 not included. 161 162 The optional argument *strict_parsing* is a flag indicating what to do with 163 parsing errors. If false (the default), errors are silently ignored. If true, 164 errors raise a :exc:`ValueError` exception. 165 166 The optional *encoding* and *errors* parameters specify how to decode 167 percent-encoded sequences into Unicode characters, as accepted by the 168 :meth:`bytes.decode` method. 169 170 The optional argument *max_num_fields* is the maximum number of fields to 171 read. If set, then throws a :exc:`ValueError` if there are more than 172 *max_num_fields* fields read. 173 174 Use the :func:`urllib.parse.urlencode` function (with the ``doseq`` 175 parameter set to ``True``) to convert such dictionaries into query 176 strings. 177 178 .. versionchanged:: 3.2 179 Add *encoding* and *errors* parameters. 180 181 .. versionchanged:: 3.7.2 182 Added *max_num_fields* parameter. 183 184 185.. function:: parse_qsl(qs, keep_blank_values=False, strict_parsing=False, encoding='utf-8', errors='replace', max_num_fields=None) 186 187 Parse a query string given as a string argument (data of type 188 :mimetype:`application/x-www-form-urlencoded`). Data are returned as a list of 189 name, value pairs. 190 191 The optional argument *keep_blank_values* is a flag indicating whether blank 192 values in percent-encoded queries should be treated as blank strings. A true value 193 indicates that blanks should be retained as blank strings. The default false 194 value indicates that blank values are to be ignored and treated as if they were 195 not included. 196 197 The optional argument *strict_parsing* is a flag indicating what to do with 198 parsing errors. If false (the default), errors are silently ignored. If true, 199 errors raise a :exc:`ValueError` exception. 200 201 The optional *encoding* and *errors* parameters specify how to decode 202 percent-encoded sequences into Unicode characters, as accepted by the 203 :meth:`bytes.decode` method. 204 205 The optional argument *max_num_fields* is the maximum number of fields to 206 read. If set, then throws a :exc:`ValueError` if there are more than 207 *max_num_fields* fields read. 208 209 Use the :func:`urllib.parse.urlencode` function to convert such lists of pairs into 210 query strings. 211 212 .. versionchanged:: 3.2 213 Add *encoding* and *errors* parameters. 214 215 .. versionchanged:: 3.7.2 216 Added *max_num_fields* parameter. 217 218.. function:: urlunparse(parts) 219 220 Construct a URL from a tuple as returned by ``urlparse()``. The *parts* 221 argument can be any six-item iterable. This may result in a slightly 222 different, but equivalent URL, if the URL that was parsed originally had 223 unnecessary delimiters (for example, a ``?`` with an empty query; the RFC 224 states that these are equivalent). 225 226 227.. function:: urlsplit(urlstring, scheme='', allow_fragments=True) 228 229 This is similar to :func:`urlparse`, but does not split the params from the URL. 230 This should generally be used instead of :func:`urlparse` if the more recent URL 231 syntax allowing parameters to be applied to each segment of the *path* portion 232 of the URL (see :rfc:`2396`) is wanted. A separate function is needed to 233 separate the path segments and parameters. This function returns a 5-tuple: 234 (addressing scheme, network location, path, query, fragment identifier). 235 236 The return value is actually an instance of a subclass of :class:`tuple`. This 237 class has the following additional read-only convenience attributes: 238 239 +------------------+-------+-------------------------+----------------------+ 240 | Attribute | Index | Value | Value if not present | 241 +==================+=======+=========================+======================+ 242 | :attr:`scheme` | 0 | URL scheme specifier | *scheme* parameter | 243 +------------------+-------+-------------------------+----------------------+ 244 | :attr:`netloc` | 1 | Network location part | empty string | 245 +------------------+-------+-------------------------+----------------------+ 246 | :attr:`path` | 2 | Hierarchical path | empty string | 247 +------------------+-------+-------------------------+----------------------+ 248 | :attr:`query` | 3 | Query component | empty string | 249 +------------------+-------+-------------------------+----------------------+ 250 | :attr:`fragment` | 4 | Fragment identifier | empty string | 251 +------------------+-------+-------------------------+----------------------+ 252 | :attr:`username` | | User name | :const:`None` | 253 +------------------+-------+-------------------------+----------------------+ 254 | :attr:`password` | | Password | :const:`None` | 255 +------------------+-------+-------------------------+----------------------+ 256 | :attr:`hostname` | | Host name (lower case) | :const:`None` | 257 +------------------+-------+-------------------------+----------------------+ 258 | :attr:`port` | | Port number as integer, | :const:`None` | 259 | | | if present | | 260 +------------------+-------+-------------------------+----------------------+ 261 262 Reading the :attr:`port` attribute will raise a :exc:`ValueError` if 263 an invalid port is specified in the URL. See section 264 :ref:`urlparse-result-object` for more information on the result object. 265 266 Unmatched square brackets in the :attr:`netloc` attribute will raise a 267 :exc:`ValueError`. 268 269 Characters in the :attr:`netloc` attribute that decompose under NFKC 270 normalization (as used by the IDNA encoding) into any of ``/``, ``?``, 271 ``#``, ``@``, or ``:`` will raise a :exc:`ValueError`. If the URL is 272 decomposed before parsing, no error will be raised. 273 274 .. versionchanged:: 3.6 275 Out-of-range port numbers now raise :exc:`ValueError`, instead of 276 returning :const:`None`. 277 278 .. versionchanged:: 3.7.3 279 Characters that affect netloc parsing under NFKC normalization will 280 now raise :exc:`ValueError`. 281 282 283.. function:: urlunsplit(parts) 284 285 Combine the elements of a tuple as returned by :func:`urlsplit` into a 286 complete URL as a string. The *parts* argument can be any five-item 287 iterable. This may result in a slightly different, but equivalent URL, if the 288 URL that was parsed originally had unnecessary delimiters (for example, a ? 289 with an empty query; the RFC states that these are equivalent). 290 291 292.. function:: urljoin(base, url, allow_fragments=True) 293 294 Construct a full ("absolute") URL by combining a "base URL" (*base*) with 295 another URL (*url*). Informally, this uses components of the base URL, in 296 particular the addressing scheme, the network location and (part of) the 297 path, to provide missing components in the relative URL. For example: 298 299 >>> from urllib.parse import urljoin 300 >>> urljoin('http://www.cwi.nl/%7Eguido/Python.html', 'FAQ.html') 301 'http://www.cwi.nl/%7Eguido/FAQ.html' 302 303 The *allow_fragments* argument has the same meaning and default as for 304 :func:`urlparse`. 305 306 .. note:: 307 308 If *url* is an absolute URL (that is, starting with ``//`` or ``scheme://``), 309 the *url*'s host name and/or scheme will be present in the result. For example: 310 311 .. doctest:: 312 313 >>> urljoin('http://www.cwi.nl/%7Eguido/Python.html', 314 ... '//www.python.org/%7Eguido') 315 'http://www.python.org/%7Eguido' 316 317 If you do not want that behavior, preprocess the *url* with :func:`urlsplit` and 318 :func:`urlunsplit`, removing possible *scheme* and *netloc* parts. 319 320 321 .. versionchanged:: 3.5 322 323 Behaviour updated to match the semantics defined in :rfc:`3986`. 324 325 326.. function:: urldefrag(url) 327 328 If *url* contains a fragment identifier, return a modified version of *url* 329 with no fragment identifier, and the fragment identifier as a separate 330 string. If there is no fragment identifier in *url*, return *url* unmodified 331 and an empty string. 332 333 The return value is actually an instance of a subclass of :class:`tuple`. This 334 class has the following additional read-only convenience attributes: 335 336 +------------------+-------+-------------------------+----------------------+ 337 | Attribute | Index | Value | Value if not present | 338 +==================+=======+=========================+======================+ 339 | :attr:`url` | 0 | URL with no fragment | empty string | 340 +------------------+-------+-------------------------+----------------------+ 341 | :attr:`fragment` | 1 | Fragment identifier | empty string | 342 +------------------+-------+-------------------------+----------------------+ 343 344 See section :ref:`urlparse-result-object` for more information on the result 345 object. 346 347 .. versionchanged:: 3.2 348 Result is a structured object rather than a simple 2-tuple. 349 350.. _parsing-ascii-encoded-bytes: 351 352Parsing ASCII Encoded Bytes 353--------------------------- 354 355The URL parsing functions were originally designed to operate on character 356strings only. In practice, it is useful to be able to manipulate properly 357quoted and encoded URLs as sequences of ASCII bytes. Accordingly, the 358URL parsing functions in this module all operate on :class:`bytes` and 359:class:`bytearray` objects in addition to :class:`str` objects. 360 361If :class:`str` data is passed in, the result will also contain only 362:class:`str` data. If :class:`bytes` or :class:`bytearray` data is 363passed in, the result will contain only :class:`bytes` data. 364 365Attempting to mix :class:`str` data with :class:`bytes` or 366:class:`bytearray` in a single function call will result in a 367:exc:`TypeError` being raised, while attempting to pass in non-ASCII 368byte values will trigger :exc:`UnicodeDecodeError`. 369 370To support easier conversion of result objects between :class:`str` and 371:class:`bytes`, all return values from URL parsing functions provide 372either an :meth:`encode` method (when the result contains :class:`str` 373data) or a :meth:`decode` method (when the result contains :class:`bytes` 374data). The signatures of these methods match those of the corresponding 375:class:`str` and :class:`bytes` methods (except that the default encoding 376is ``'ascii'`` rather than ``'utf-8'``). Each produces a value of a 377corresponding type that contains either :class:`bytes` data (for 378:meth:`encode` methods) or :class:`str` data (for 379:meth:`decode` methods). 380 381Applications that need to operate on potentially improperly quoted URLs 382that may contain non-ASCII data will need to do their own decoding from 383bytes to characters before invoking the URL parsing methods. 384 385The behaviour described in this section applies only to the URL parsing 386functions. The URL quoting functions use their own rules when producing 387or consuming byte sequences as detailed in the documentation of the 388individual URL quoting functions. 389 390.. versionchanged:: 3.2 391 URL parsing functions now accept ASCII encoded byte sequences 392 393 394.. _urlparse-result-object: 395 396Structured Parse Results 397------------------------ 398 399The result objects from the :func:`urlparse`, :func:`urlsplit` and 400:func:`urldefrag` functions are subclasses of the :class:`tuple` type. 401These subclasses add the attributes listed in the documentation for 402those functions, the encoding and decoding support described in the 403previous section, as well as an additional method: 404 405.. method:: urllib.parse.SplitResult.geturl() 406 407 Return the re-combined version of the original URL as a string. This may 408 differ from the original URL in that the scheme may be normalized to lower 409 case and empty components may be dropped. Specifically, empty parameters, 410 queries, and fragment identifiers will be removed. 411 412 For :func:`urldefrag` results, only empty fragment identifiers will be removed. 413 For :func:`urlsplit` and :func:`urlparse` results, all noted changes will be 414 made to the URL returned by this method. 415 416 The result of this method remains unchanged if passed back through the original 417 parsing function: 418 419 >>> from urllib.parse import urlsplit 420 >>> url = 'HTTP://www.Python.org/doc/#' 421 >>> r1 = urlsplit(url) 422 >>> r1.geturl() 423 'http://www.Python.org/doc/' 424 >>> r2 = urlsplit(r1.geturl()) 425 >>> r2.geturl() 426 'http://www.Python.org/doc/' 427 428 429The following classes provide the implementations of the structured parse 430results when operating on :class:`str` objects: 431 432.. class:: DefragResult(url, fragment) 433 434 Concrete class for :func:`urldefrag` results containing :class:`str` 435 data. The :meth:`encode` method returns a :class:`DefragResultBytes` 436 instance. 437 438 .. versionadded:: 3.2 439 440.. class:: ParseResult(scheme, netloc, path, params, query, fragment) 441 442 Concrete class for :func:`urlparse` results containing :class:`str` 443 data. The :meth:`encode` method returns a :class:`ParseResultBytes` 444 instance. 445 446.. class:: SplitResult(scheme, netloc, path, query, fragment) 447 448 Concrete class for :func:`urlsplit` results containing :class:`str` 449 data. The :meth:`encode` method returns a :class:`SplitResultBytes` 450 instance. 451 452 453The following classes provide the implementations of the parse results when 454operating on :class:`bytes` or :class:`bytearray` objects: 455 456.. class:: DefragResultBytes(url, fragment) 457 458 Concrete class for :func:`urldefrag` results containing :class:`bytes` 459 data. The :meth:`decode` method returns a :class:`DefragResult` 460 instance. 461 462 .. versionadded:: 3.2 463 464.. class:: ParseResultBytes(scheme, netloc, path, params, query, fragment) 465 466 Concrete class for :func:`urlparse` results containing :class:`bytes` 467 data. The :meth:`decode` method returns a :class:`ParseResult` 468 instance. 469 470 .. versionadded:: 3.2 471 472.. class:: SplitResultBytes(scheme, netloc, path, query, fragment) 473 474 Concrete class for :func:`urlsplit` results containing :class:`bytes` 475 data. The :meth:`decode` method returns a :class:`SplitResult` 476 instance. 477 478 .. versionadded:: 3.2 479 480 481URL Quoting 482----------- 483 484The URL quoting functions focus on taking program data and making it safe 485for use as URL components by quoting special characters and appropriately 486encoding non-ASCII text. They also support reversing these operations to 487recreate the original data from the contents of a URL component if that 488task isn't already covered by the URL parsing functions above. 489 490.. function:: quote(string, safe='/', encoding=None, errors=None) 491 492 Replace special characters in *string* using the ``%xx`` escape. Letters, 493 digits, and the characters ``'_.-~'`` are never quoted. By default, this 494 function is intended for quoting the path section of URL. The optional *safe* 495 parameter specifies additional ASCII characters that should not be quoted 496 --- its default value is ``'/'``. 497 498 *string* may be either a :class:`str` or a :class:`bytes`. 499 500 .. versionchanged:: 3.7 501 Moved from :rfc:`2396` to :rfc:`3986` for quoting URL strings. "~" is now 502 included in the set of reserved characters. 503 504 The optional *encoding* and *errors* parameters specify how to deal with 505 non-ASCII characters, as accepted by the :meth:`str.encode` method. 506 *encoding* defaults to ``'utf-8'``. 507 *errors* defaults to ``'strict'``, meaning unsupported characters raise a 508 :class:`UnicodeEncodeError`. 509 *encoding* and *errors* must not be supplied if *string* is a 510 :class:`bytes`, or a :class:`TypeError` is raised. 511 512 Note that ``quote(string, safe, encoding, errors)`` is equivalent to 513 ``quote_from_bytes(string.encode(encoding, errors), safe)``. 514 515 Example: ``quote('/El Niño/')`` yields ``'/El%20Ni%C3%B1o/'``. 516 517 518.. function:: quote_plus(string, safe='', encoding=None, errors=None) 519 520 Like :func:`quote`, but also replace spaces by plus signs, as required for 521 quoting HTML form values when building up a query string to go into a URL. 522 Plus signs in the original string are escaped unless they are included in 523 *safe*. It also does not have *safe* default to ``'/'``. 524 525 Example: ``quote_plus('/El Niño/')`` yields ``'%2FEl+Ni%C3%B1o%2F'``. 526 527 528.. function:: quote_from_bytes(bytes, safe='/') 529 530 Like :func:`quote`, but accepts a :class:`bytes` object rather than a 531 :class:`str`, and does not perform string-to-bytes encoding. 532 533 Example: ``quote_from_bytes(b'a&\xef')`` yields 534 ``'a%26%EF'``. 535 536 537.. function:: unquote(string, encoding='utf-8', errors='replace') 538 539 Replace ``%xx`` escapes by their single-character equivalent. 540 The optional *encoding* and *errors* parameters specify how to decode 541 percent-encoded sequences into Unicode characters, as accepted by the 542 :meth:`bytes.decode` method. 543 544 *string* must be a :class:`str`. 545 546 *encoding* defaults to ``'utf-8'``. 547 *errors* defaults to ``'replace'``, meaning invalid sequences are replaced 548 by a placeholder character. 549 550 Example: ``unquote('/El%20Ni%C3%B1o/')`` yields ``'/El Niño/'``. 551 552 553.. function:: unquote_plus(string, encoding='utf-8', errors='replace') 554 555 Like :func:`unquote`, but also replace plus signs by spaces, as required for 556 unquoting HTML form values. 557 558 *string* must be a :class:`str`. 559 560 Example: ``unquote_plus('/El+Ni%C3%B1o/')`` yields ``'/El Niño/'``. 561 562 563.. function:: unquote_to_bytes(string) 564 565 Replace ``%xx`` escapes by their single-octet equivalent, and return a 566 :class:`bytes` object. 567 568 *string* may be either a :class:`str` or a :class:`bytes`. 569 570 If it is a :class:`str`, unescaped non-ASCII characters in *string* 571 are encoded into UTF-8 bytes. 572 573 Example: ``unquote_to_bytes('a%26%EF')`` yields ``b'a&\xef'``. 574 575 576.. function:: urlencode(query, doseq=False, safe='', encoding=None, \ 577 errors=None, quote_via=quote_plus) 578 579 Convert a mapping object or a sequence of two-element tuples, which may 580 contain :class:`str` or :class:`bytes` objects, to a percent-encoded ASCII 581 text string. If the resultant string is to be used as a *data* for POST 582 operation with the :func:`~urllib.request.urlopen` function, then 583 it should be encoded to bytes, otherwise it would result in a 584 :exc:`TypeError`. 585 586 The resulting string is a series of ``key=value`` pairs separated by ``'&'`` 587 characters, where both *key* and *value* are quoted using the *quote_via* 588 function. By default, :func:`quote_plus` is used to quote the values, which 589 means spaces are quoted as a ``'+'`` character and '/' characters are 590 encoded as ``%2F``, which follows the standard for GET requests 591 (``application/x-www-form-urlencoded``). An alternate function that can be 592 passed as *quote_via* is :func:`quote`, which will encode spaces as ``%20`` 593 and not encode '/' characters. For maximum control of what is quoted, use 594 ``quote`` and specify a value for *safe*. 595 596 When a sequence of two-element tuples is used as the *query* 597 argument, the first element of each tuple is a key and the second is a 598 value. The value element in itself can be a sequence and in that case, if 599 the optional parameter *doseq* is evaluates to ``True``, individual 600 ``key=value`` pairs separated by ``'&'`` are generated for each element of 601 the value sequence for the key. The order of parameters in the encoded 602 string will match the order of parameter tuples in the sequence. 603 604 The *safe*, *encoding*, and *errors* parameters are passed down to 605 *quote_via* (the *encoding* and *errors* parameters are only passed 606 when a query element is a :class:`str`). 607 608 To reverse this encoding process, :func:`parse_qs` and :func:`parse_qsl` are 609 provided in this module to parse query strings into Python data structures. 610 611 Refer to :ref:`urllib examples <urllib-examples>` to find out how urlencode 612 method can be used for generating query string for a URL or data for POST. 613 614 .. versionchanged:: 3.2 615 Query parameter supports bytes and string objects. 616 617 .. versionadded:: 3.5 618 *quote_via* parameter. 619 620 621.. seealso:: 622 623 :rfc:`3986` - Uniform Resource Identifiers 624 This is the current standard (STD66). Any changes to urllib.parse module 625 should conform to this. Certain deviations could be observed, which are 626 mostly for backward compatibility purposes and for certain de-facto 627 parsing requirements as commonly observed in major browsers. 628 629 :rfc:`2732` - Format for Literal IPv6 Addresses in URL's. 630 This specifies the parsing requirements of IPv6 URLs. 631 632 :rfc:`2396` - Uniform Resource Identifiers (URI): Generic Syntax 633 Document describing the generic syntactic requirements for both Uniform Resource 634 Names (URNs) and Uniform Resource Locators (URLs). 635 636 :rfc:`2368` - The mailto URL scheme. 637 Parsing requirements for mailto URL schemes. 638 639 :rfc:`1808` - Relative Uniform Resource Locators 640 This Request For Comments includes the rules for joining an absolute and a 641 relative URL, including a fair number of "Abnormal Examples" which govern the 642 treatment of border cases. 643 644 :rfc:`1738` - Uniform Resource Locators (URL) 645 This specifies the formal syntax and semantics of absolute URLs. 646