httpcore 0.14 redesign

[tomchristie]

See discussion #419

I'm breaking my own rules here with a mega PR that's pulling in all of https://github.com/tomchristie/httpcore-the-directors-cut but there we are. Sometimes these things need doing.

• Code updates
• Test updates
• Docs updates
• README update

[florimondmanca]

Some comments

• I see we added models such as URL and Origin, which also exist currently in HTTPX. What's the cohabitation strategy? Will these be re-exposed in HTTPX? If they are copies from HTTPX then fine, otherwise are there API changes?
• Should we ping some folks of extensions/libraries building upon on httpcore? For community purposes and also to assess that the new API still fits the bill for existing use cases?
• I'm not sure about py.typed -- the diff shows it as deleted? We should make sure to keep it, I believe?

[tomchristie]

I see we added models such as URL and Origin, which also exist currently in HTTPX. What's the cohabitation strategy? Will these be re-exposed in HTTPX? If they are copies from HTTPX then fine, otherwise are there API changes?

There are httpcore.Request, httpcore.Response, and httpcore.URL models. Unlike httpx they're just very slim wrappers around the basic (status, headers, content, extensions) = send(method, url, headers, content, extensions) API, but it ends up being much nicer to work with from a developer UX perspective, and it also ends up feeling neater in the internal implementation. I'd like to drop Origin from the public API really. It's not mentioned anywhere in the docs that I've got so far, and I only haven't dropped it yet because I wanted to push on with getting this PR live, rather than delaying.

(Trying to find a good balance between "low-level API that doesn't deal with any fancy-pants models that just introduce extra surface area to wrangle, and hide from the developer what actual byte representations are like going to go out over the wire" vs. "user friendly API". I've not doc'ed up the models yet, but there's a starter on it, here)

Should we ping some folks of extensions/libraries building upon on httpcore? For community purposes and also to assess that the new API still fits the bill for existing use cases?

Sure - any suggestions beyond this discussion?

I'm not sure about py.typed -- the diff shows it as deleted? We should make sure to keep it, I believe?

Good catch - sorted!

[tomchristie]

Right come on then, best just push on with this, eh?