#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 42aa4be..154a521 100644
--- a/Doc/library/urllib.parse.rst
+++ b/Doc/library/urllib.parse.rst
@@ -517,7 +517,7 @@
.. 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 @@
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 a2a912d..d368331 100644
--- a/Lib/urllib/parse.py
+++ b/Lib/urllib/parse.py
@@ -670,8 +670,8 @@
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 @@
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"):