httpx: the README's httpx2 examples fail type checking when httpx is also installed #5281

Describe your environment

OS: Arch Linux (x86_64)
Python version: 3.14.2
Package version: opentelemetry-instrumentation-httpx 0.66b2 (same on main), with httpx 0.28.1 and httpx2 2.16.0 installed; mypy 2.4.1, pyright 1.1.414

What happened?

With httpx and httpx2 both installed, which the README covers ("If both libraries are installed, use HTTPXClientInstrumentor for httpx clients and HTTPX2ClientInstrumentor for httpx2 clients."), the README's httpx2 examples fail type checking. HTTPX2ClientInstrumentor.instrument_client inherits client: httpx.Client | httpx.AsyncClient, and the Httpx2 transport wrappers take httpx.BaseTransport / httpx.AsyncBaseTransport, where httpx is the TYPE_CHECKING import (init.py). The calls work at runtime. A follow-up to #4818, which #4833 closed without changing these annotations. Should they accept the httpx2 classes?

Steps to Reproduce

repro.py (the README examples, condensed, plus their async variants), checked with mypy repro.py:

import httpx2
from opentelemetry.instrumentation.httpx import (
    AsyncOpenTelemetryTransportHttpx2,
    HTTPX2ClientInstrumentor,
    SyncOpenTelemetryTransportHttpx2,
)

# README: "For ``httpx2`` clients, use ``HTTPX2ClientInstrumentor.instrument_client``"
HTTPX2ClientInstrumentor.instrument_client(httpx2.Client())
HTTPX2ClientInstrumentor.instrument_client(httpx2.AsyncClient())

# README: "For ``httpx2`` transports, use ``SyncOpenTelemetryTransportHttpx2`` and ``AsyncOpenTelemetryTransportHttpx2``"
httpx2.Client(transport=SyncOpenTelemetryTransportHttpx2(httpx2.HTTPTransport()))
httpx2.AsyncClient(transport=AsyncOpenTelemetryTransportHttpx2(httpx2.AsyncHTTPTransport()))

Expected Result

No errors, as for the same four calls written with httpx and HTTPXClientInstrumentor.

Actual Result

repro.py:9: error: Argument 1 to "instrument_client" of "_BaseHTTPXClientInstrumentor" has incompatible type "httpx2._client.Client"; expected "httpx._client.Client | AsyncClient"  [arg-type]
repro.py:10: error: Argument 1 to "instrument_client" of "_BaseHTTPXClientInstrumentor" has incompatible type "httpx2._client.AsyncClient"; expected "Client | httpx._client.AsyncClient"  [arg-type]
repro.py:13: error: Argument 1 to "SyncOpenTelemetryTransportHttpx2" has incompatible type "HTTPTransport"; expected "BaseTransport"  [arg-type]
repro.py:14: error: Argument 1 to "AsyncOpenTelemetryTransportHttpx2" has incompatible type "AsyncHTTPTransport"; expected "AsyncBaseTransport"  [arg-type]
Found 4 errors in 1 file (checked 1 source file)

pyright reports the same calls, and also the wrapper passed as transport= to httpx2.Client.

Additional context

I used an AI assistant to draft this report and reviewed it before posting.

Would you like to implement a fix?

None

Tip

_{React with 👍 to help prioritize this issue. Please use comments to provide useful context, avoiding +1 or me too, to help us triage it. Learn more here.}