Httpx: Version 1.0, working notes.

[tomchristie]

Here are my current working notes on our remaining 1.0 items...

HTTPX 1.0

• [x] Exception hierarchy. - See https://github.com/encode/httpx/issues/949#issuecomment-661804949, #1095
• [ ] Drop chardet. - See https://github.com/encode/httpx/pull/1078#issuecomment-662971297
• [x] Optional HTTP/2 installs. - See https://github.com/encode/httpcore/pull/121
• [x] Drop HSTS. - See https://github.com/encode/httpx/issues/1102
• [ ] Drop URLLib3Transport into external package.
• [ ] Context managed transports. - See https://github.com/encode/httpx/pull/998#issuecomment-653519294 tho I need to explain this one more thoroughly.

Minor:

• [x] Drop httpx.StatusCodes in favour of httpx.codes. See #1088
• [x] PoolLimits -> Limits, pool_limits -> limits.
• [x] Strict Timeout(...) defaults. Simplify keyword arguments. See #1085
• [ ] Review all methods/attributes on the models classes. Eg. See #1089. Also .call_next might need to be private. .timer might need looking at.
• [x] httpx.create_ssl_context(...) - See https://github.com/encode/httpx/issues/983

Not strictly required, but worth looking at:

• Review rfc3986 vs. irl vs. urlcore. - See https://github.com/encode/httpx/issues/328#issuecomment-664253854
• Mount API. - See #977. Not strictly required for 1.0, but we want to make sure we've handling managed transports properly, and not missing any low-level httpcore API required to support them.
• Expose ContentStream API. Perhaps?
• Upgrade API. - See https://github.com/encode/httpx/issues/304#issuecomment-664207367
• Server side requests and responses. - See #1091

---

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

• RequestError All exceptions that can occur during a .request()
  
  
  
  • TransportError These all have counterparts in httpcore
    
    
    
    
    
    • TimeoutException
      
      
      
      
      
      
      
      • ConnectTimeout
      
      
      
      
      • ReadTimeout
      
      
      
      
      • WriteTimeout
      
      
      
      
      • PoolTimeout
      
      
      
      
    
    
    
    • NetworkError
      
      
      
      
      
      
      
      • ConnectError
      
      
      
      
      • ReadError
      
      
      
      
      • WriteError
      
      
      
      
      • CloseError
      
      
      
      
    
    
    
    • ProxyError
    
    
    
    • ProtocolError
    
    
    
  
  
  • DecodingError
    
    
    
    
    
    • ContentDecodingError
    
    
    
    • TextDecodingError
    
    
    
  
  
  • TooManyRedirects
  
  
  • RequestBodyUnavailable
  
  
  • InvalidURL
  
  
• HTTPStatusError - Occurs during .raise_for_status
• NotRedirectResponse - Occurs if calling .next() without properly checking .is_redirect_response
• CookieConflict - Can occur with response.cookies.get(...)
• StreamError
  
  
  
  • StreamConsumed - Occurs if attempting to iterate over the stream twice
  
  
  • ResponseNotRead - Occurs if accessing .content without having .read() the stream
  
  
  • RequestNotRead - Occurs if accessing .content without having .read() the stream
  
  
  • ResponseClosed - Occurs if attempting to read the stream after response is already closed
  
  

---

Dependencies

Here's how our lovely & minimal core non-optional dependancies would look...
Depending on our assessment of https://github.com/encode/httpx/issues/328#issuecomment-664253854

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

[StephenBrown2]

Gonna put in another request for built-in retries, though I understand if the answer is still "no" or "not for 1.0".

[florimondmanca]

Went ahead and created https://github.com/encode/httpx/issues/1102 to better track the "Drop HSTS" item - also updated the description here.

[tomchristie]

@StephenBrown2 Fair question yup, seems to me that it's absolutely a 1.1 item. It's a great feature that we should look at, but I don't think there's any pressing need for it to block a release marked as 1.0, with the API stability that implies.

[tomchristie]

@StephenBrown2 Want to open an issue for retries so we can start discussing the API, and finer details of the expected behaviours? Even tho it's not strictly a 1.0 blocker, perhaps it's feasible it might still land in time for that.

Useful initial points to discuss:

• What API requests provides for retries. (I think you need to mount an adapter in order to get retry support right?)
• What exact behaviour requests uses through urllib3, when enabled without providing any finer-tuning details?
• What fine tuning options does urlilb3 offer in it's Retry config class?

[florimondmanca]

Also I think there’s lots of useful context and ideas already starting from #784 :-)

No adapter required - the idea was to loop around send_single_request() (I think?) in case of connection failures. The PR stopped at handling network errors only (so no retries on HTTP status errors or stuff like that) and I think there was a rationale behind that, but don’t have the exact thing off the top of my mind.

[StephenBrown2]

The original issue is https://github.com/encode/httpx/issues/108 (gosh, over 900 Issues/PRs ago). I can try to summarize in a bit, but @florimondmanca is right, the interface is just a parameter to the client or requester, similar to the Timeout we've got now. However, https://github.com/encode/httpx/pull/778 had a good idea with a retry_flow method to overwrite, similar to the auth_flow method httpx also has now.

[tomchristie]

Closing this one off, since I think everything we need to track is appropriately milestoned now.