summaryrefslogtreecommitdiffstats
path: root/Doc/library
diff options
context:
space:
mode:
authorR David Murray <rdmurray@bitdance.com>2015-05-18 00:44:50 (GMT)
committerR David Murray <rdmurray@bitdance.com>2015-05-18 00:44:50 (GMT)
commitc17686f071c6f5b5d20366ae32188327a36e282e (patch)
tree70c6482b2a224313d4771917aff6f9b810e00fb8 /Doc/library
parent1dbee9460e6a242bfbdd701ce328f11f7dd69019 (diff)
downloadcpython-c17686f071c6f5b5d20366ae32188327a36e282e.zip
cpython-c17686f071c6f5b5d20366ae32188327a36e282e.tar.gz
cpython-c17686f071c6f5b5d20366ae32188327a36e282e.tar.bz2
Issue #13866: add *quote_via* argument to urlencode.
Patch by samwyse, completed by Arnon Yaari, and reviewed by Martin Panter.
Diffstat (limited to 'Doc/library')
-rw-r--r--Doc/library/urllib.parse.rst20
1 files changed, 16 insertions, 4 deletions
diff --git a/Doc/library/urllib.parse.rst b/Doc/library/urllib.parse.rst
index 3ecdda1..800f830 100644
--- a/Doc/library/urllib.parse.rst
+++ b/Doc/library/urllib.parse.rst
@@ -519,7 +519,8 @@ task isn't already covered by the URL parsing functions above.
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"
@@ -528,8 +529,16 @@ task isn't already covered by the URL parsing functions above.
properly 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
@@ -538,7 +547,7 @@ task isn't already covered by the URL parsing functions above.
string will match the order of parameter tuples in the sequence.
The *safe*, *encoding*, and *errors* parameters are passed down to
- :func:`quote_plus` (the *encoding* and *errors* parameters are only passed
+ *quote_via* (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
@@ -550,6 +559,9 @@ task isn't already covered by the URL parsing functions above.
.. versionchanged:: 3.2
Query parameter supports bytes and string objects.
+ .. versionadded:: 3.5
+ *quote_via* parameter.
+
.. seealso::