Debian Codegraph @

Doc/library/urllib.parse.rst

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