Skip to content

Commit 3c04f9f

Browse files
[PR #12202/07bd8c1d backport][3.14] docs: clarify params query canonicalization behavior (#12369)
**This is a backport of PR #12202 as merged into master (07bd8c1).** Co-authored-by: Dr Alex Mitre <[email protected]>
1 parent 0544166 commit 3c04f9f

1 file changed

Lines changed: 6 additions & 3 deletions

File tree

docs/client_quickstart.rst

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -119,8 +119,9 @@ that case you can specify multiple values for each key::
119119
expect = 'http://httpbin.org/get?key=value2&key=value1'
120120
assert str(r.url) == expect
121121

122-
You can also pass :class:`str` content as param, but beware -- content
123-
is not encoded by library. Note that ``+`` is not encoded::
122+
You can also pass :class:`str` content as param. The value is used as a
123+
query string, but passing ``params`` does not disable URL
124+
canonicalization. Note that ``+`` is not encoded::
124125

125126
async with session.get('http://httpbin.org/get',
126127
params='key=value+1') as r:
@@ -146,7 +147,9 @@ is not encoded by library. Note that ``+`` is not encoded::
146147

147148
.. warning::
148149

149-
Passing *params* overrides ``encoded=True``, never use both options.
150+
Passing *params* overrides ``encoded=True``. Never use both options
151+
if you need to preserve exact query-string bytes.
152+
Build the full URL (including query) instead.
150153

151154
Response Content and Status Code
152155
================================

0 commit comments

Comments
 (0)