Fixed issue11082 - Reject str for POST data with a TypeError. Document the need to explicitly encode to bytes when using urlencode.
diff --git a/Doc/library/urllib.parse.rst b/Doc/library/urllib.parse.rst
index 6a143c5..a6d7267 100644
--- a/Doc/library/urllib.parse.rst
+++ b/Doc/library/urllib.parse.rst
@@ -140,6 +140,7 @@
Use the :func:`urllib.parse.urlencode` function to convert such
dictionaries into query strings.
+
.. versionchanged:: 3.2
Add *encoding* and *errors* parameters.
@@ -506,9 +507,10 @@
.. 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" string,
- suitable to pass to :func:`urlopen` above as the optional *data* argument.
- This is useful to pass a dictionary of form fields to a ``POST`` request.
+ either be a :class:`str` or a :class:`bytes`, to a "percent-encoded"
+ string. The resultant string must be converted to bytes using the
+ user-specified encoding before it is sent to :func:`urlopen` as the optional
+ *data* argument.
The resulting string is a series of ``key=value`` pairs separated by ``'&'``
characters, where both *key* and *value* are quoted using :func:`quote_plus`
above. When a sequence of two-element tuples is used as the *query*
@@ -525,6 +527,9 @@
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.
+
.. versionchanged:: 3.2
Query parameter supports bytes and string objects.
diff --git a/Doc/library/urllib.request.rst b/Doc/library/urllib.request.rst
index 724310b..2b98c83 100644
--- a/Doc/library/urllib.request.rst
+++ b/Doc/library/urllib.request.rst
@@ -967,7 +967,7 @@
>>> import urllib.request
>>> req = urllib.request.Request(url='https://localhost/cgi-bin/test.cgi',
- ... data='This data is passed to stdin of the CGI')
+ ... data=b'This data is passed to stdin of the CGI')
>>> f = urllib.request.urlopen(req)
>>> print(f.read().decode('utf-8'))
Got Data: "This data is passed to stdin of the CGI"
@@ -1043,11 +1043,13 @@
>>> f = urllib.request.urlopen("http://www.musi-cal.com/cgi-bin/query?%s" % params)
>>> print(f.read().decode('utf-8'))
-The following example uses the ``POST`` method instead::
+The following example uses the ``POST`` method instead. Note that params output
+from urlencode is encoded to bytes before it is sent to urlopen as data::
>>> import urllib.request
>>> import urllib.parse
>>> params = urllib.parse.urlencode({'spam': 1, 'eggs': 2, 'bacon': 0})
+ >>> params = params.encode('utf-8')
>>> f = urllib.request.urlopen("http://www.musi-cal.com/cgi-bin/query", params)
>>> print(f.read().decode('utf-8'))