From: Martin Panter <vadmium+py@gmail.com>
Date: Tue, 24 Nov 2015 22:57:46 +0000 (+0000)
Subject: Issue #25576: Merge www-form-urlencoded doc from 3.4 into 3.5
X-Git-Tag: v3.6.0a1~991^2
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=f7e8d07538a1734bdb0438ab53e0a54db456d4d9;p=python

Issue #25576: Merge www-form-urlencoded doc from 3.4 into 3.5
---

f7e8d07538a1734bdb0438ab53e0a54db456d4d9
diff --cc Doc/library/urllib.parse.rst
index 40098d0496,ac04f99deb..21c82f5262
--- a/Doc/library/urllib.parse.rst
+++ b/Doc/library/urllib.parse.rst
@@@ -521,26 -516,18 +521,27 @@@ task isn't already covered by the URL p
     Example: ``unquote_to_bytes('a%26%EF')`` yields ``b'a&\xef'``.
  
  
 -.. function:: urlencode(query, doseq=False, safe='', encoding=None, errors=None)
 +.. function:: urlencode(query, doseq=False, safe='', encoding=None, \
 +                        errors=None, quote_via=quote_plus)
  
     Convert a mapping object or a sequence of two-element tuples, which may
-    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`.
+    contain :class:`str` or :class:`bytes` objects, to a percent-encoded ASCII
+    text string.  If the resultant string is to be used as a *data* for POST
+    operation with the :func:`~urllib.request.urlopen` function, then
+    it should be encoded to bytes, otherwise it would result in a
+    :exc:`TypeError`.
  
     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*
 +   characters, where both *key* and *value* are quoted using the *quote_via*
 +   function.  By default, :func:`quote_plus` is used to quote the values, which
 +   means spaces are quoted as a ``'+'`` character and '/' characters are
 +   encoded as ``%2F``, which follows the standard for GET requests
 +   (``application/x-www-form-urlencoded``).  An alternate function that can be
 +   passed as *quote_via* is :func:`quote`, which will encode spaces as ``%20``
 +   and not encode '/' characters.  For maximum control of what is quoted, use
 +   ``quote`` and specify a value for *safe*.
 +
 +   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