Repository navigation
Separate httpx.post(content=...) from httpx(data=...)? #1210
Description
Currently we're following the requests API, with data=... representing one of:
str/bytes/byte iterator/byte aiterator- Content to send in the body of the request.dict- Data to send in either a URLEncoded or Multipart request.
These are really two very different types of cases. One is for submitting HTML form data, the other is for uploading raw byte content. It's possible that we should consider if we want to diverge from requests here, in order to provide a more clear, consistent interface?
For example...
# Send a POST request, with "abc" as the request body.
httpx.post(content=b'abc')
# Send a POST request, with URLEncoded data.
httpx.post(data={"field": "value"})
# Send a POST request, with MultiPart encoded data.
httpx.post(data={"field": "value"}, files=...)Would be interested to see what others think of this?...
(Obviously we'd want a gradual deprecation if we did decide to take this on.)
Activity
florimondmanca commentedon Aug 21, 2020
Hmm, not sure about this, I'm on a "probably no" position I think.
The biggest drawback I'd see is this introduces an extra little subtle API difference from Requests, for benefits that aren't super clear to me. It's probably good (maybe?) that this would make it explicit that passing text vs passing a dict does a different thing, but on the other hand this alternative 2-separate-params somehow does not feel obviously more intuitive or pleasant to use. Eg after all, str or bytes is some kind of
data, and if I know that passing it as such sends it in the request body, vs URLEncoded or MultiPart, then we're good right?I think we probably want to stick to the Requests API here in the name of familiarity and the principle of least surprise?
[-]Separate `httpx.post(content=...)` from `httpx(data=...)`.[/-][+]Separate `httpx.post(content=...)` from `httpx(data=...)`?[/+]lovelydinosaur commentedon Aug 21, 2020
I think you've got to be right wrt. consistency with requests here, yup.
lovelydinosaur commentedon Sep 3, 2020
So I'm starting to think that we might want to reopen this, and move towards
content=...for byte content vsdata=...for form encoded data only. Here's why I'm thinking that'll end up being able to give us a more consistent API throughout...Response(content=...), it'd be nice ifRequest(content=...)mirrored that.Response(stream=...)and have thecontent=...allowed types bebytes|byte iterator|byte aiterator|ByteStreamRequest(stream=...)and have thecontent=...allowed types bebytes|byte iterator|byte aiterator|ByteStreamWe could still support
data=<bytes|byte iterator>but only for backwards compat purposes with requests, giving us a nice clear split between form data vs. json data vs. raw byte content.Anyways, just getting my thoughts down here for now.
florimondmanca commentedon Sep 4, 2020
Yes — I'm not against us adding support for
content=...at all - that sounds like a very sensible naming, and nothing similar in Requests territory there, so all good.What I was warning against was removing the
data=<bytes>usage, which I believe we should keep for Requests compatibility purposes.If we'd be to support
content=<bytes>anddata=<bytes (for compat)|byte iterator>, then that'd sound about right to me. :-)Switch to content=… as we're POSTing bytes