classification
Title: Better documentation for the urlencode safe parameter
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.4, Python 3.5
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, python-dev, r.david.murray, wrwrwr
Priority: normal Keywords: patch

Created on 2014-12-12 15:34 by wrwrwr, last changed 2014-12-25 02:25 by r.david.murray. This issue is now closed.

Files
File name Uploaded Description Edit
urlencode-safe.diff wrwrwr, 2014-12-12 15:34 review
urlencode-safe-v2.diff wrwrwr, 2014-12-13 11:51 review
Messages (8)
msg232556 - (view) Author: Wojtek Ruszczewski (wrwrwr) * Date: 2014-12-12 15:34
The documentation for urlencode() [1] isn't very clear on how the safe parameter is used, it would better not list it together with encoding and error as only applying to strings.

[1] https://docs.python.org/3.5/library/urllib.parse.html#urllib.parse.urlencode
msg232558 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2014-12-12 16:26
The current documentation looks very clear to me, and I don't understand your changed version.  Can you give an example of how the existing text is inaccurate or results in confusion?
msg232565 - (view) Author: Wojtek Ruszczewski (wrwrwr) * Date: 2014-12-12 17:30
I was looking at the sentence:
"When query parameter is a str, the safe, encoding and error parameters are passed down to quote_plus() for encoding."

The query argument can't be a string itself (gives a TypeError with 3.5a0 and I think it's only intended to accept dicts or sequences of 2-tuples). The "parameter" then must refer to a component of the query -- a key or a value.

The safe argument is passed down and is effective no matter if a component is of str or bytes type (or a sequence with doseq), for example:

>>> urlencode({b'/ n': ''}, safe='/')
'/+n='
(note the "b"; without "safe" the slash would get encoded as %2F).

Maybe it would also be good to change "query parameter" to "query component" in that sentence.
msg232576 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2014-12-12 21:07
OK, now I understand.  How about this phrasing:

"The *safe*, *encoding*, and *error* parameters are passed down to :func:`quote_plus` (the *encoding* and *error* parameters are only passed when the query element is a :class:`str`).
msg232579 - (view) Author: Wojtek Ruszczewski (wrwrwr) * Date: 2014-12-12 23:35
Thanks, that's right and better, as it doesn't replicate the safe explanation.

I've just noticed another small one, the docstring for quote() [2] says:
"encoding must not be specified if string is a str" -- that should be "... is a bytes".

[2] https://hg.python.org/cpython/file/default/Lib/urllib/parse.py#l690
msg232606 - (view) Author: Wojtek Ruszczewski (wrwrwr) * Date: 2014-12-13 11:51
Updated the patch, additionally changing "be" to "contain" in the first sentence.
msg233089 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2014-12-25 02:24
New changeset 126aff7c6a33 by R David Murray in branch '3.4':
#23040: Clarify treatment of encoding and errors when component is bytes.
https://hg.python.org/cpython/rev/126aff7c6a33

New changeset 367ba031a743 by R David Murray in branch 'default':
Merge: #23040: Clarify treatment of encoding and errors when component is bytes.
https://hg.python.org/cpython/rev/367ba031a743
msg233090 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2014-12-25 02:25
Thanks, Wojtek.
History
Date User Action Args
2014-12-25 02:25:08r.david.murraysetstatus: open -> closed
versions: + Python 3.4
messages: + msg233090

resolution: fixed
stage: resolved
2014-12-25 02:24:23python-devsetnosy: + python-dev
messages: + msg233089
2014-12-13 11:51:36wrwrwrsetfiles: + urlencode-safe-v2.diff

messages: + msg232606
2014-12-12 23:35:02wrwrwrsetmessages: + msg232579
2014-12-12 21:07:38r.david.murraysetmessages: + msg232576
2014-12-12 17:30:20wrwrwrsetmessages: + msg232565
2014-12-12 16:26:16r.david.murraysetnosy: + r.david.murray
messages: + msg232558
2014-12-12 15:34:59wrwrwrcreate