New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Better documentation for the urlencode safe parameter #67229
Comments
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 |
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? |
I was looking at the sentence: 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. |
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`). |
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: [2] https://hg.python.org/cpython/file/default/Lib/urllib/parse.py#l690 |
Updated the patch, additionally changing "be" to "contain" in the first sentence. |
New changeset 126aff7c6a33 by R David Murray in branch '3.4': New changeset 367ba031a743 by R David Murray in branch 'default': |
Thanks, Wojtek. |
Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.
Show more details
GitHub fields:
bugs.python.org fields:
The text was updated successfully, but these errors were encountered: