https://github.com/python/cpython/commit/8e1f26e4f06c43cf52afa26ce30f27d2c11... commit: 8e1f26e4f06c43cf52afa26ce30f27d2c1129c4a branch: master author: Борис Верховский <boris.verk@gmail.com> committer: Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com> date: 2019-12-31T04:28:18-08:00 summary: Minor doc fixes in urllib.parse (GH-17745) files: M Doc/library/urllib.parse.rst diff --git a/Doc/library/urllib.parse.rst b/Doc/library/urllib.parse.rst index 2d4d5a9e60969..02f0c01e224dd 100644 --- a/Doc/library/urllib.parse.rst +++ b/Doc/library/urllib.parse.rst @@ -42,8 +42,8 @@ or on combining URL components into a URL string. Parse a URL into six components, returning a 6-item :term:`named tuple`. This corresponds to the general structure of a URL: ``scheme://netloc/path;parameters?query#fragment``. - Each tuple item is a string, possibly empty. The components are not broken up in - smaller parts (for example, the network location is a single string), and % + Each tuple item is a string, possibly empty. The components are not broken up + into smaller parts (for example, the network location is a single string), and % escapes are not expanded. The delimiters as shown above are not part of the result, except for a leading slash in the *path* component, which is retained if present. For example: @@ -328,22 +328,22 @@ or on combining URL components into a URL string. .. note:: - If *url* is an absolute URL (that is, starting with ``//`` or ``scheme://``), - the *url*'s host name and/or scheme will be present in the result. For example: + If *url* is an absolute URL (that is, it starts with ``//`` or ``scheme://``), + the *url*'s hostname and/or scheme will be present in the result. For example: - .. doctest:: + .. doctest:: - >>> urljoin('http://www.cwi.nl/%7Eguido/Python.html', - ... '//www.python.org/%7Eguido') - 'http://www.python.org/%7Eguido' + >>> urljoin('http://www.cwi.nl/%7Eguido/Python.html', + ... '//www.python.org/%7Eguido') + 'http://www.python.org/%7Eguido' - If you do not want that behavior, preprocess the *url* with :func:`urlsplit` and - :func:`urlunsplit`, removing possible *scheme* and *netloc* parts. + If you do not want that behavior, preprocess the *url* with :func:`urlsplit` and + :func:`urlunsplit`, removing possible *scheme* and *netloc* parts. .. versionchanged:: 3.5 - Behaviour updated to match the semantics defined in :rfc:`3986`. + Behavior updated to match the semantics defined in :rfc:`3986`. .. function:: urldefrag(url) @@ -521,11 +521,11 @@ task isn't already covered by the URL parsing functions above. Replace special characters in *string* using the ``%xx`` escape. Letters, digits, and the characters ``'_.-~'`` are never quoted. By default, this - function is intended for quoting the path section of URL. The optional *safe* - parameter specifies additional ASCII characters that should not be quoted - --- its default value is ``'/'``. + function is intended for quoting the path section of a URL. The optional + *safe* parameter specifies additional ASCII characters that should not be + quoted --- its default value is ``'/'``. - *string* may be either a :class:`str` or a :class:`bytes`. + *string* may be either a :class:`str` or a :class:`bytes` object. .. versionchanged:: 3.7 Moved from :rfc:`2396` to :rfc:`3986` for quoting URL strings. "~" is now @@ -547,7 +547,7 @@ task isn't already covered by the URL parsing functions above. .. function:: quote_plus(string, safe='', encoding=None, errors=None) - Like :func:`quote`, but also replace spaces by plus signs, as required for + Like :func:`quote`, but also replace spaces with plus signs, as required for quoting HTML form values when building up a query string to go into a URL. Plus signs in the original string are escaped unless they are included in *safe*. It also does not have *safe* default to ``'/'``. @@ -566,12 +566,12 @@ task isn't already covered by the URL parsing functions above. .. function:: unquote(string, encoding='utf-8', errors='replace') - Replace ``%xx`` escapes by their single-character equivalent. + Replace ``%xx`` escapes with their single-character equivalent. The optional *encoding* and *errors* parameters specify how to decode percent-encoded sequences into Unicode characters, as accepted by the :meth:`bytes.decode` method. - *string* may be either a :class:`str` or a :class:`bytes`. + *string* may be either a :class:`str` or a :class:`bytes` object. *encoding* defaults to ``'utf-8'``. *errors* defaults to ``'replace'``, meaning invalid sequences are replaced @@ -587,8 +587,8 @@ task isn't already covered by the URL parsing functions above. .. function:: unquote_plus(string, encoding='utf-8', errors='replace') - Like :func:`unquote`, but also replace plus signs by spaces, as required for - unquoting HTML form values. + Like :func:`unquote`, but also replace plus signs with spaces, as required + for unquoting HTML form values. *string* must be a :class:`str`. @@ -597,10 +597,10 @@ task isn't already covered by the URL parsing functions above. .. function:: unquote_to_bytes(string) - Replace ``%xx`` escapes by their single-octet equivalent, and return a + Replace ``%xx`` escapes with their single-octet equivalent, and return a :class:`bytes` object. - *string* may be either a :class:`str` or a :class:`bytes`. + *string* may be either a :class:`str` or a :class:`bytes` object. If it is a :class:`str`, unescaped non-ASCII characters in *string* are encoded into UTF-8 bytes. @@ -631,7 +631,7 @@ task isn't already covered by the URL parsing functions above. When a sequence of two-element tuples is used as the *query* argument, the first element of each tuple is a key and the second is a value. The value element in itself can be a sequence and in that case, if - the optional parameter *doseq* is evaluates to ``True``, individual + the optional parameter *doseq* evaluates to ``True``, individual ``key=value`` pairs separated by ``'&'`` are generated for each element of the value sequence for the key. The order of parameters in the encoded string will match the order of parameter tuples in the sequence. @@ -643,11 +643,12 @@ task isn't already covered by the URL parsing functions above. To reverse this encoding process, :func:`parse_qs` and :func:`parse_qsl` are provided in this module to parse query strings into Python data structures. - Refer to :ref:`urllib examples <urllib-examples>` to find out how urlencode - method can be used for generating query string for a URL or data for POST. + Refer to :ref:`urllib examples <urllib-examples>` to find out how the + :func:`urllib.parse.urlencode` method can be used for generating the query + string of a URL or data for a POST request. .. versionchanged:: 3.2 - Query parameter supports bytes and string objects. + *query* supports bytes and string objects. .. versionadded:: 3.5 *quote_via* parameter.