#23040: Clarify treatment of encoding and errors when component is bytes.

Patch by Wojtek Ruszczewski.

diff --git a/Doc/library/urllib.parse.rst b/Doc/library/urllib.parse.rst
index 42aa4be170a492ae077477e3c2cfc3796e26a666..154a521fa1e42ef0fc31a2a31dd103a84b95595f 100644 (file)
--- a/Doc/library/urllib.parse.rst
+++ b/Doc/library/urllib.parse.rst
@@ -517,7 +517,7 @@ task isn't already covered by the URL parsing functions above.
 .. function:: urlencode(query, doseq=False, safe='', encoding=None, errors=None)
 
    Convert a mapping object or a sequence of two-element tuples, which may
-   either be a :class:`str` or a :class:`bytes`,  to a "percent-encoded"
+   contain :class:`str` or :class:`bytes` objects, to a "percent-encoded"
    string.  If the resultant string is to be used as a *data* for POST
    operation with :func:`~urllib.request.urlopen` function, then it should be
    properly encoded to bytes, otherwise it would result in a :exc:`TypeError`.
@@ -532,8 +532,9 @@ task isn't already covered by the URL parsing functions above.
    the value sequence for the key.  The order of parameters in the encoded
    string will match the order of parameter tuples in the sequence.
 
-   When *query* parameter is a :class:`str`, the *safe*, *encoding* and *error*
-   parameters are passed down to :func:`quote_plus` for encoding.
+   The *safe*, *encoding*, and *errors* parameters are passed down to
+   :func:`quote_plus` (the *encoding* and *errors* parameters are only passed
+   when a query element is a :class:`str`).
 
    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.

diff --git a/Lib/urllib/parse.py b/Lib/urllib/parse.py
index a2a912d2abced1ce601a5b7c7c91747fbe340394..d36833111fb9c18d010165a169cc808e9bd4da56 100644 (file)
--- a/Lib/urllib/parse.py
+++ b/Lib/urllib/parse.py
@@ -670,8 +670,8 @@ def quote(string, safe='/', encoding=None, errors=None):
     called on a path where the existing slash characters are used as
     reserved characters.
 
-    string and safe may be either str or bytes objects. encoding must
-    not be specified if string is a str.
+    string and safe may be either str or bytes objects. encoding and errors
+    must not be specified if string is a bytes object.
 
     The optional encoding and errors parameters specify how to deal with
     non-ASCII characters, as accepted by the str.encode method.
@@ -743,8 +743,9 @@ def urlencode(query, doseq=False, safe='', encoding=None, errors=None):
     input.
 
     The components of a query arg may each be either a string or a bytes type.
-    When a component is a string, the safe, encoding and error parameters are
-    sent to the quote_plus function for encoding.
+
+    The safe, encoding, and errors parameters are passed down to quote_plus()
+    (encoding and errors only if a component is a str).
     """
 
     if hasattr(query, "items"):