Unified http version parameter

[T-256]

Current:

client = httpx.Client(http1=True, http2=True)

If HTTP3 be added:

client = httpx.Client(http1=True, http2=True, http3=True)

Suggested:

version = httpx.Version.HTTP1_1 | httpx.Version.HTTP2 | httpx.Version.HTTP3

client = httpx.Client(version=version)

[zanieb]

Isn't the boolean about allowing the connection to be upgraded to the given HTTP version? I don't see how this has the same meaning as a union type.

[T-256]

Instead of having 3 parameters for Client, it would be one parameter with type of enum.IntFlag.

import enum


class Version(enum.IntFlag):
    HTTP1_1 = auto()
    HTTP2 = auto()
    HTTP3 = auto()


class Client:
    def __init__(
        ...,
        version: Version = Version.HTTP1_1,
    ): ...

then we can deprecate http1= and http2= in favor of version=.

[zanieb]

I still don't see this as an improved user experience. It's less intuitive and since people usually want to allow connections to upgrade to a newer HTTP version but not fail on an older version also it's less easy to use i.e. you'd need to union multiple types and understand flag enums.

[tomchristie]

An alternative here is...

http_version = httpx.HTTPVersion("HTTP/1.1", "HTTP/2")
client = httpx.Client(http_version=http_version)

I like this a bit because it's more obvious which of the 3 allowable states you're choosing...

http_version = httpx.HTTPVersion("HTTP/1.1")  # Default
client = httpx.Client(http_version=http_version)

HTTP/2 only (prior knowledge)

http_version = httpx.HTTPVersion("HTTP/2")  # Default
client = httpx.Client(http_version=http_version)

It can be nicely inspectable...

>>> httpx.HTTPVersion()
<httpx.HTTPVersion ["HTTP/1.1"]>

It's also feels consistent with the proposed SSL API change...

ssl_context = httpx.SSLContent(...)
http_version = httpx.HTTPVersion(...)
client = httpx.Client(http_version=http_version, ssl_context=ssl_context)

Or when declaring the transport explicitly...

ssl_context = httpx.SSLContent(...)
http_version = httpx.HTTPVersion(...)
transport = httpx.HTTPTransport(http_version=http_version, ssl_context=ssl_context)

client = httpx.Client(transport=transport)

We can work towards these both also being visible in a consistent way...

>>> client = httpx.Client()
>>> client.transport
<httpx.HTTPTransport [Connections: 0 active, 0 keep-alive. Requests: 0 active, 0 queued.]>
>>> client.transport.ssl_context
<httpx.SSLContext [verify=True]>
>>> client.transport.http_version
<httpx.HTTPVersion ["HTTP/1.1"]>

Worth considering?

[T-256]

Now that I'm thinking more, we could enhance the current using protocol. When we send TLS-Client-Hello we include multiple alpns, is there any easy way to determine server selected which http version? what about non-TLS requests? what about upgraded connections?

[tomchristie]

The answers to those questions are documented against httpcore. Needs improving in httpx also.

is there any easy way to determine server selected which http version?

response.http_version

what about non-TLS requests?

Prior-knowledge is supported and allows non-TLS HTTP/2 requests. Use http1=False, http2=True.

what about upgraded connections?

Upgrade: h2c is not currently supported.

[T-256]

The answers to those questions are documented against httpcore. Needs improving in httpx also

Well documented, sorry for missed them.

response.http_version

As http_version used for already negotiated protocol, I'd recommend use different parameter name for client/transport instances for avoid complicating their difference for users.

We don't use any http_* parameter when instantiate httpx.Client (e.g. we won't use http_transport=/http_cookies= instead of transport=/cookies=).

As suggestion it could be protocols=, versions=, use_versions=.

by pointing to your proposed api, should httpx.HTTPVersion use another enum-based class for supported versions?

class SupportedVersions(StrEnum):
    HTTP1_1 = "HTTP/1.1"
    HTTP2 = "HTTP/2"
    # HTTP3 = "HTTP/3"


class HTTPVersions:
    def __init__(self, *versions: SupportedVersions): ...


versions = HTTPVersions("HTTP/1.1", "HTTP/2")
client = Client(versions=versions)