Version 0.14.0

[tomchristie]

0.14.0 (August 7th, 2020)

The 0.14 release includes a range of improvements to the public API, intended on preparing for our upcoming 1.0 release.

• Our HTTP/2 support is now fully optional. You now need to use pip install httpx[http2] if you want to include the HTTP/2 dependancies.
• Our HSTS support has now been removed. Rewriting URLs from http to https if the host is on the HSTS list can be beneficial in avoiding roundtrips to incorrectly formed URLs, but on balance we've decided to remove this feature, on the principle of least surprise. Most programmatic clients do not include HSTS support, and for now we're opting to remove our support for it.
• Our exception hierarchy has been overhauled. Most users will want to stick with their existing httpx.HTTPError usage, but we've got a clearer overall structure now. See https://www.python-httpx.org/exceptions/ for more details.

When upgrading you should be aware of the following public API changes. Note that deprecated usages will currently continue to function, but will issue warnings.

• You should now use httpx.codes consistently in favour of httpx.StatusCodes.
• Usage of httpx.Timeout() should now always include an explicit default. Eg. httpx.Timeout(None, pool=5.0).
• When using httpx.Timeout(), we now have more concisely named keyword arguments. Eg. read=5.0, instead of read_timeout=5.0.
• Use httpx.Limits() instead of httpx.PoolLimits(), and limits=... instead of pool_limits=....
• The httpx.Limits(max_keepalive=...) argument is now deprecated in favour of a more explicit httpx.Limits(max_keepalive_connections=...)
• Keys used with Client(proxies={...}) should now be in the style of {"http://": ...}, rather than {"http": ...}.
• The multidict methods Headers.getlist() and QueryParams.getlist() are deprecated in favour of more consistent .get_list() variants.
• The URL.is_ssl property is deprecated in favour of URL.scheme == "https".
• The URL.join(relative_url=...) method is now URL.join(url=...). This change does not support warnings for the deprecated usage style.

One notable aspect of the 0.14.0 release is that it tightens up the public API for httpx, by ensuring that several internal attributes and methods have now become strictly private.

The following previously had nominally public names on the client, but were all undocumented and intended solely for internal usage. They are all now replaced with underscored names, and should not be relied on or accessed.

These changes should not affect users who have been working from the httpx documentation.

• .merge_url(), .merge_headers(), .merge_cookies(), .merge_queryparams()
• .build_auth(), .build_redirect_request()
• .redirect_method(), .redirect_url(), .redirect_headers(), .redirect_stream()
• .send_handling_redirects(), .send_handling_auth(), .send_single_request()
• .init_transport(), .init_proxy_transport()
• .proxies, .transport, .netrc, .get_proxy_map()

See pull requests #997, #1065, #1071.

Some areas of API which were already on the deprecation path, and were raising warnings or errors in 0.13.x have now been escalated to being fully removed.

• Drop ASGIDispatch, WSGIDispatch, which have been replaced by ASGITransport, WSGITransport.
• Drop dispatch=...`` on client, which has been replaced by transport=...``
• Drop soft_limit, hard_limit, which have been replaced by max_keepalive and max_connections.
• Drop Response.stream and Response.raw, which have been replaced by ``.aiter_bytes and .aiter_raw.
• Drop proxies=<transport instance> in favor of proxies=httpx.Proxy(...).

See pull requests #1057, #1058.

### Added

• Added dedicated exception class httpx.HTTPStatusError for .raise_for_status() exceptions. (Pull Raise HTTPStatusError in raise_from_status #1072)
• Added httpx.create_ssl_context() helper function. (Pull Included create_ssl_context function to create the same context with SSLConfig and serve as API #996)
• Support for proxy exlcusions like proxies={"https://www.example.com": None}. (Pull Add support for no-proxy configurations #1099)
• Support QueryParams(None) and client.params = None. (Pull Support QueryParams(None) #1060)

Changed

• Use httpx.codes consistently in favour of httpx.StatusCodes which is placed into deprecation. (Pull Single consistent name for status codes #1088)
• Usage of httpx.Timeout() should now always include an explicit default. Eg. httpx.Timeout(None, pool=5.0). (Pull httpx.Timeout must include a default #1085)
• Switch to more concise httpx.Timeout() keyword arguments. Eg. read=5.0, instead of read_timeout=5.0. (Pull Switch to more concise Timeout parameters #1111)
• Use httpx.Limits() instead of httpx.PoolLimits(), and limits=... instead of pool_limits=.... (Pull Rename PoolLimits to Limits #1113)
• The httpx.Limits(max_keepalive=...) argument is now deprecated in favour of a more explicit httpx.Limits(max_keepalive_connections=...).
• Keys used with Client(proxies={...}) should now be in the style of {"http://": ...}, rather than {"http": ...}. (Pull Raise warning if proxy key is eg. "all" instead of "all://". #1127)
• The multidict methods Headers.getlist and QueryParams.getlist are deprecated in favour of more consistent .get_list() variants. (Pull Consistent multidict methods #1089)
• URL.port becomes Optional[int]. Now only returns a port if one is explicitly included in the URL string. (Pull URL.port becomes Optional[int] #1080)
• The URL(..., allow_relative=[bool]) parameter no longer exists. All URL instances may be relative. (Pull Drop URL(allow_relative=bool) #1073)
• Drop unnecessary url.full_path = ... property setter. (Pull Drop fullpath setter #1069)
• The URL.join(relative_url=...) method is now URL.join(url=...). (Pull Clean up keyword argument name, using URL.join(url=...), not URL.join(relative_url=...). #1129)
• The URL.is_ssl property is deprecated in favour of URL.scheme == "https". (Pull Deprecate URL.is_ssl #1128)

Fixed

• Add missing Response.next() method. (Pull Add missing Response.next() #1055)
• Ensure all exception classes are exposed as public API. (Pull Add exceptions missing from top-level package #1045)
• Support multiple items with an identical field name in multipart encodings. (Pull Support for multiple files per POST field #777)
• Skip HSTS preloading on single-label domains. (Pull Skip HSTS preloading on single-label domains #1074)
• Fixes for Response.iter_lines(). (Pull aiter_lines() doesn't return full lines that span multiple chunks #1033, Fixes for LineDecoding #1075)
• Ignore permission errors when accessing .netrc files. (Pull Ignore PermissionError in netrc_info() #1104)
• Allow bare hostnames in HTTP_PROXY etc... environment variables. (Pull Handle bare env proxy hostname gracefully #1120)
• Settings app=... or transport=... bypasses any environment based proxy defaults. (Pull Setting app=... or transport=... should bypass environment proxies. #1122)
• Fix handling of .base_url when a path component is included in the base URL. (Pull Base URL improvements #1130)

[tomchristie]

Other possible candidates for a 0.14.0 release...

• Add httpx.create_ssl_context() helper function. Included create_ssl_context function to create the same context with SSLConfig and serve as API #996
• Use limits=... and httpx.Limits instead of pool_limits and httpx.PoolLimits, with a gentle deprecation path. I've been meaning to mention this. Particularly applicable if eg. at some point we wanted some more general client-wide "max concurrent requests" controls, which isn't strictly to do with connection pooling.
• Drop httpx.StatusCodes being exposed externally, since we document it's usage as httpx.codes.

I'm also minded to have a proper pass at polishing up the developer interface docs alongside the 0.14 release, since this release is really all about nailing that right down.

There are still some very minor bits of public/private attribute polishing that we'll want to look at on some of the models.

Excluding exceptions, here's how the public API shapes up after all this:

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

[tomchristie]

Hoping to roll the 0.14 release early this coming week.

Here's what I think we still need to do...

• Address any remaining issues in Local address support. httpcore#100 and get that in.
• Address follow on items from Optional HTTP/2 httpcore#121 - make httpcore[http2] a thing. Address any httpcore docs there. (We can still take an independent decision on httpx 0.14 vs 1.0 for when we switch there. Eg. if we include httpcore[http2] as our base dependancy, or httpcore as out base dependancy, with httpcore[http2] as the optional extra.)
• Issue an httpcore 0.10 release.
• Update the httpx exception hierarchy to reflect 0.10. Drop InvalidURL and enforce_http_url. To close Exceptions - Documentation, Hierarchy & Naming. #949.
• Document the httpx exception hierarchy. To close Document the exception hierarchy  #1106.
• Pull in Use named keyword arguments on httpcore streams #1121. (Raise an issue to later switch to using content=... in ASGITransport/WSGITransport as a nice tidy-up refactor.)
• Take a call on Drop HSTS Preloading #1110
• Take a call on On proxies={"http": ...} vs. proxies={"http://": ...} #1105
• Take a call on if we should switch to httpx[http2] in 0.14 or are we punting on that til 1.0?
• Bring release notes up to date in this PR. (Done up to Mon 3rd Aug, just needs exception hierarchy changes noted, with link to docs)

Anything I'm missing?

[tomchristie]

• Module level deprecation warning for HTTPError, and consider making it a two tuple of (RequestError, HTTPStatusError).

[florimondmanca]

@tomchristie I won't be available most of the rest of today for reviews, neither on Monday. Is there such an urgent need to release 0.14 "ASAP"? I understand we're all excited but just an explicit heads up that I don't think this means we should bypass reviews on non-trivial changes (since I'm assuming merging w/o thorough second review would be the only way to achieve a release by tomorrow given the rest of things that need to be done). 😅

[tomchristie]

Yup, all fair. Let's keep it moderated. It's a great piece of work, no need for us to rush it tho.

[iwoloschin]

• Module level deprecation warning for HTTPError, and consider making it a two tuple of (RequestError, HTTPStatusError).

I think we really want this in some form that doesn't explicitly break existing codebases. If we can find a way to print a deprecation warning that's great, but if not just putting a big warning in the release notes is sufficient (yay for pre-1.0 code!).

[tomchristie]

@iwoloschin Indeed. I think there's probably also a decent case to make for not deprecating it at all, and instead keeping it as a base class, but only for RequestError and HTTPStatusError, so that...

try:
    response = httpx.get("https://www.example.com/")  # May raise a RequestError subclass
    response.raise_for_status()  # May raise HTTPStatusError
except httpx.HTTPError as exc:
    pass

Which means existing code all keeps working as expected, while still providing finer-grained classes where needed.

Also, both HTTPStatusError and RequestError provide .request, so we can suitably annotate that on the base class.

It's also more concise than the alternative...

try:
    response = httpx.get("https://www.example.com/")  # May raise a RequestError subclass
    response.raise_for_status()  # May raise HTTPStatusError
except (httpx.RequestError, httpx.HTTPStatusError) as exc:
    pass

This hadn't really occurred to me when looking at #1095.

[tomchristie]

Last bits here are...

• Get httpcore 0.10 released... See https://github.com/encode/httpcore/milestone/1
• Get Update to httpcore 0.10 #1126 resolved (Update setup.py to httpcore[http2]==0.10.* once the release is available, and re-run test suite.)
• Pull in exception docs in Document exceptions #1138 (Make sure to uncomment missing exception classes first.)
• Make HTTP/2 optional. (Add to release notes, add to HTTP/2 section, add import h2 check in client, update setup.py)
• Review & roll a release.