[florimondmanca]

Refs #830

A proof-of-concept (but working) PR to illustrate #830 (comment)

• Add context manager capabilities to Response. (This brings us closer to what Requests does.)
• Make .stream() return a Response, allowing both context-managed and non-context-managed usage with an equivalent level of user experience.

The high-level httpx.stream() is kept to context-managed only because we also need to close the client on exit (and it would be awkward to eg implement a close callback API on the Response class just for this internal use case).

The breaking change here is that users would need to use async with await client.stream() in the async context-managed use case (extra await). This usage might be surprising but in line with other things such as trio's open_file() API.

[yeraydiazdiaz]

This looks really nice but I have to admit I did a double take reading async with await ... 😄

I like the approach and don't mind paying the price of a breaking change pre 1.0, it's worth it.

Nice job as always @florimondmanca 💯

[florimondmanca]

Thanks!

I need to do a pass on docs (and highlight that the extra await there isn’t a typo 🤣).

[lovelydinosaur]

Grand. Will aim to take a look this week. Potentially some mixed thoughts about it, but needs a proper look! 🙂

[lovelydinosaur]

So my reservations around this are to do with the .stream API already being deliberately designed to ensure that it's not possible that incorrectly use it, and fail to close connections as a result.

Changing things this way around would mean that...

• It becomes easy for developers to mis-use the .stream API, by using the sequential style, without an enforced final close.
• It becomes possible for developers to use context managed style on the plain calls, eg async with await client.get() as response which is superfluous and misleading.

So I'm not yet convinced that it's clear if we shouldn't just stick with helping developers down the straight and narrow path, while allowing .build_request and .send if you really need to break out of that.

The pointer to trio's open_file API is a decent counter-point although there's a somewhat different set of concerns there, in that they'll want to be mirroring stdlib's open style as closely as possible, so it naturally leads to distinct async with and await components.

[florimondmanca]

Those are valid points @tomchristie, thanks. Opened #1046 to explore the "just document how to use manual streaming" path, and I think it's the most convincing option. Closing this in favor of #1046 for now…