Confusion about passing tuple-type values to the timeout parameter of the Timeout class

[marigoold]

In this code section, it appears that the timeout parameter can accept a tuple of length 2 to 4. However, when I do this, the type system reports an error.
Reproduction steps:

1. Create a file test_httpx_timeout.py

import httpx
timeout = httpx.Timeout((10.0, 30.0))

2. Check it with mypy mypy test_httpx_timeout.py and I get the following error:

test_httpx_timeout.py:2: error: Argument 1 to "Timeout" has incompatible type "tuple[float, float]"; expected "float | tuple[float | None, float | None, float | None, float | None] | Timeout | None | UnsetType"  [arg-type]
Found 1 error in 1 file (checked 1 source file)

[SirHegel]

You are not misreading the implementation: the runtime behavior and the public type alias disagree.

On current master, Timeout.__init__() reads positions 0 and 1, then makes positions 2 and 3 optional (implementation). However, TimeoutTypes declares only an exact four-item tuple (type alias), so mypy is correctly enforcing the annotation it sees.

I reproduced the mismatch on that commit:

Timeout((10.0, 30.0))       runtime: OK; mypy: error
Timeout((10.0, 30.0, 40.0)) runtime: OK; mypy: error
Timeout((10.0, 30.0, 40.0, 50.0)) runtime: OK; mypy: OK

Until the annotation is aligned, the typed equivalent is:

timeout = httpx.Timeout(
    connect=10.0,
    read=30.0,
    write=None,
    pool=None,
)

or:

timeout = httpx.Timeout((10.0, 30.0, None, None))

If 2- and 3-item tuples are intended to remain supported, TimeoutTypes should explicitly union the three fixed tuple shapes. A variadic tuple would be too broad: currently 0/1-item tuples raise IndexError, while values after the fourth are silently ignored. Tests should therefore cover the exact 2-, 3-, and 4-item forms.

---

Update: I prepared the minimal type-alias change and runtime coverage in a signed commit: encode:b5addb6...SirHegel:2fb3342

It passes scripts/check (Ruff format, mypy across 60 files, and Ruff lint), 27 applicable configuration tests, and a standalone mypy check that accepts exactly the 2/3/4-item forms while rejecting 1/5. This repository currently restricts PR creation to collaborators, so GitHub rejects a pull request from this account; the immutable comparison is available for maintainer review or cherry-pick.

[gyanu2507]

On top of the stub mismatch already called out: don't pass a bare tuple into Timeout(...) if you care about mypy. Use kwargs (or a single float):

import httpx

timeout = httpx.Timeout(10.0, connect=5.0)
timeout = httpx.Timeout(None, connect=5.0, read=30.0)
client = httpx.Client(timeout=httpx.Timeout(10.0, connect=5.0))

One float still means "same value for every phase":

httpx.Timeout(10.0)

Runtime historically accepted a 2 to 4 length tuple and mapped positions to connect/read/write/pool. The published types didn't keep up, so mypy rejects Timeout((10.0, 30.0)) even when CPython is fine with it.

Keywords are clearer anyway and type-check today.