Version 1.0

[tomchristie]

Update: Everything we need to consider ought to now be milestoned... https://github.com/encode/httpx/milestone/1

---

API Reference

Here's a high-level API reference...

Helper functions

request, stream, get, options, head, post, put, patch, delete

Clients

Client, AsyncClient

Models

Response, Request, URL, QueryParams, Headers, Cookies

Configuration

Limits, Proxy, Timeout

Authentication

Auth, BasicAuth, DigestAuth

Transports

ASGITransport, WSGITransport

Status Codes

codes

---

Exceptions

• HTTPError
  • RequestError
    • TransportError
      • TimeoutException
        • ConnectTimeout
        • ReadTimeout
        • WriteTimeout
        • PoolTimeout
      • NetworkError
        • ConnectError
        • ReadError
        • WriteError
        • CloseError
      • ProtocolError
        • LocalProtocolError
        • RemoteProtocolError
      • UnsupportedProtocol
      • ProxyError
    • DecodingError
    • TooManyRedirects
  • HTTPStatusError
• NotRedirectResponse
• CookieConflict
• StreamError
  • StreamConsumed
  • ResponseNotRead
  • RequestNotRead
  • ResponseClosed

---

Dependencies

• httpcore
  • h11
  • sniffio
• rfc3986
  • idna
• certifi

Optionals: pip install httpx[http2], pip install httpx[brotli]

[florimondmanca]

I’d like to add a discussion point about our position wrt type hints would be. There’s been a couple of issues asking for them to be public API mainly for the use of third party library authors. I don’t have a strong position on this yet, but wondering if type hints (and more generally third party lib authoring experience, although that’s pretty broad) should be in our scope for 1.0?

[tomchristie]

Good call yup, we need to discuss that for sure!

[yeraydiazdiaz]

We have a version 1.0 milestone. Should we formalize these points into issues and add them?

[tomchristie]

The proxy DEFAULT_MODE discussion needs to be part of this too.

[tomchristie]

@yeraydiazdiaz Sure thing, yup.

[pikeas]

Having recently used httpx, I was very surprised that there's no rate-limiting (requests per second, not just max connections) built in. This greatly reduces the utility of the async mode.

[tomchristie]

Okay. Sure we can have a discussion about that, tho it's not strictly a 1.0 blocker.

[florimondmanca]

Something else to potentially consider for 1.0 that came to my mind: #302, aka dropping certifi in favor of the system defaults. I have a different approach in mind that what was originally suggested in the issue, will comment there to see if it makes sense.

[bwright1558]

I've had my eyes on this repository for a while and it looks very promising. The only thing preventing me from using this library is the lack of support for socks5 proxies. Gotta have this for connecting to Tor. It's also a lot easier to spin up a socks proxy server than it is an http proxy server (in my opinion).
There's already an open issue: #203. There's also a PR in httpcore: encode/httpcore#51. Would be nice to see this in a 1.0 release.

[florimondmanca]

@bwright1558 From my POV, SOCKS proxy support is a nice-to-have, but technically not a blocker for 1.0 (we can probably add it later as an incremental new feature, without having to break any existing API).

Note that there's been loads of work by Yeray and @sethmlarson to pull off a sans-io implementation, and as you mentioned Yeray started the integration within httpcore (which is indeed almost only additive). If you'd like to help out I'm sure Yeray will appreciate early-stage user feedback there, e.g. see if the API makes sense, etc. :-)

[yeraydiazdiaz]

I agree with @florimondmanca in that SOCKS support is not a blocker for 1.0, though I certainly see it coming sooner rather than later 🤞

Personally I think the two most requested features for 1.0 are:

• Built-in retries, for which Florimond already opened Retries for connection failures #784)
• Built-in throttling, which is partially addressed by the pool limits but has come up in the chat and Florimond suggested using https://github.com/florimondmanca/aiometer.

To me the latter feels more of a nice-to-have for 1.0, it could even be argued that it's better to leave it as a separate library completely.

[florimondmanca]

I think those are two interesting areas, but are they blockers for 1.0?

I’m still not super convinced we need to have retries built in (libraries like tenacity solve this problem brilliantly). But if we do want some basic functionality then I’d definitely make the case for making retries opt in (which makes it easier to bring in higher control via eg tenacity), in which case this would be a non breaking addition in all cases, so not a 1.0 blocker.

As for throttling, it seems we currently have expectations set wrong wrt pool limits. A lot of people seem to expect those to behave like throttling, when it’s really more about resource limiting. I guess we could address this with some docs revamp about pool limits (I remember Tom drafted a PR for this), and then perhaps recommend focused solutions like aiometer more prominently - at least as a first approach. (FWIW aiometer already has an HTTPX usage example in its README.) Like retries, I don’t see why we wouldn’t be able to bring this in incrementally (throttling should be opt in too), so not a 1.0 blocker in my mind.