Document the extensions API.

[tomchristie]

We have some documentation on the extensions API in the httpcore docs, but I don't see anywhere that we're referencing it in httpx.

Maybe we need an extra section in the "Advanced Usage" docs?

---

Prompted by #2552

^{Originally posted by al3x4kov January 22, 2023}
Hi!

i have this code:
async with httpx.AsyncClient(verify=False if not ca_bundle else ca_bundle, timeout=timeout) as client:
rsp = await client.request( method="GET", url=url, headers=headers )

ca_bundle is a path like /tmp/ca_bundle
timeout = 30.0

Everything is ok, i get response but the main question is what i should add in my code to have in log strings like:
console.print(f"* SSL established using {version!r} / {cipher[0]!r}")
This line from def trace from httpx/_main.py

I found that in client.request i can add parameter extensions, but i can't really understand what to pass in

I tried to use TRACE logging type - doesn't work for me. I see only this lines.

[al3x4kov]

I cannot assert that using extensions will help solve my problem. I assumed that the transport would contain information about the version of TLS used and the encryption method, but I only found information on how to output the minimum and maximum versions of TLS, as well as the available encryption methods.

Example how i found min/max available TLS versions (Please don't throw stones at me):

transport = client._transport_for_url(response.url)
tls_version = transport.__dict__['_pool']._ssl_context.maximum_version.name

I found info here:

transport = client._transport_for_url(response.url)
dir(transport.__dict__['_pool']._ssl_context)

['__class__', '__delattr__', '__dict__', '__dir__', '__doc__', '__eq__', '__format__', '__ge__', '__getattribute__', '__gt__', '__hash__', '__init__', '__init_subclass__', '__le__', '__lt__', '__module__', '__ne__', '__new__', '__reduce__', '__reduce_ex__', '__repr__', '__setattr__', '__sizeof__', '__str__', '__subclasshook__', '__weakref__', '_encode_hostname', '_host_flags', '_load_windows_store_certs', '_msg_callback', '_set_alpn_protocols', '_set_npn_protocols', '_windows_cert_stores', '_wrap_bio', '_wrap_socket', 'cert_store_stats', 'check_hostname', 'get_ca_certs', 'get_ciphers', 'hostname_checks_common_name', 'load_cert_chain', 'load_default_certs', 'load_dh_params', 'load_verify_locations', 'maximum_version', 'minimum_version', 'options', 'post_handshake_auth', 'protocol', 'session_stats', 'set_alpn_protocols', 'set_ciphers', 'set_default_verify_paths', 'set_ecdh_curve', 'set_npn_protocols', 'set_servername_callback', 'sni_callback', 'sslobject_class', 'sslsocket_class', 'verify_flags', 'verify_mode', 'wrap_bio', 'wrap_socket']

[tomchristie]

Take a look at the 'network_stream' extension. This exposes the underlying network stream, which allows you to read or write directly to it, or to get additional information, such as the SSL object.

The socket SSL information is also available through this interface, although you need to ensure that the underlying connection is still open, in order to access it...

# You'll probably want to use `httpx` (or an httpx client instance) here instead of `httpcore`.
# The extension works the same way...
with httpcore.stream("GET", "https://www.example.com") as response:
    network_stream = response.extensions["network_stream"]

    ssl_object = network_stream.get_extra_info("ssl_object")
    print("TLS version", ssl_object.version())

[tomchristie]

Another user asking the same question, but looking for the server_addr info... #2633