Reject ClientTimeout(total=0) in v4, use None to disable timeouts by veeceey · Pull Request #12044 · aio-libs/aiohttp

veeceey · 2026-02-08T23:03:25Z

Instead of normalizing total=0 to None, this PR removes support for ClientTimeout(total=0) entirely in v4.

asyncio.loop.start_tls() only accepts None or a positive number for ssl_handshake_timeout, so passing total=0 caused a ValueError. Rather than working around it, we now reject total=0 upfront with a clear error message directing users to use None instead.

The backport to 3.14 (#12067) keeps the normalization approach for backwards compatibility.

Changes:

Add __post_init__ validation to ClientTimeout that rejects total=0
Revert the timeout.total or None workaround in connector.py
Replace functional TLS test with validation tests
Update changelog

codspeed-hq · 2026-02-08T23:10:52Z

Merging this PR will not alter performance

✅ 59 untouched benchmarks

_{Comparing veeceey:fix/issue-11859 (8c58af6) with master (32924e8)}

codecov · 2026-02-09T02:05:27Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.76%. Comparing base (100e5ed) to head (8c58af6).
⚠️ Report is 11 commits behind head on master.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##           master   #12044      +/-   ##
==========================================
+ Coverage   98.69%   98.76%   +0.06%     
==========================================
  Files         127      127              
  Lines       44667    44684      +17     
  Branches     2372     2372              
==========================================
+ Hits        44086    44130      +44     
+ Misses        412      393      -19     
+ Partials      169      161       -8

Flag	Coverage Δ
CI-GHA	`98.61% <100.00%> (+0.04%)`	⬆️
OS-Linux	`98.35% <100.00%> (+<0.01%)`	⬆️
OS-Windows	`96.69% <100.00%> (+0.40%)`	⬆️
OS-macOS	`97.58% <100.00%> (?)`
Py-3.10.11	`97.13% <100.00%> (?)`
Py-3.10.19	`97.62% <100.00%> (+0.66%)`	⬆️
Py-3.11.14	`97.82% <100.00%> (-0.01%)`	⬇️
Py-3.11.9	`97.35% <100.00%> (?)`
Py-3.12.10	`97.44% <100.00%> (?)`
Py-3.12.12	`97.92% <100.00%> (-0.01%)`	⬇️
Py-3.13.12	`98.16% <100.00%> (+0.68%)`	⬆️
Py-3.14.3	`98.13% <100.00%> (+0.22%)`	⬆️
Py-3.14.3t	`97.21% <100.00%> (-0.03%)`	⬇️
Py-pypy3.11.13-7.3.20	`97.36% <100.00%> (?)`
VM-macos	`97.58% <100.00%> (?)`
VM-ubuntu	`98.35% <100.00%> (+<0.01%)`	⬆️
VM-windows	`96.69% <100.00%> (+0.40%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

webknjaz · 2026-02-10T13:36:14Z

According to the issue, Sam suggested not supporting this in v4.

CHANGES/11859.bugfix.rst

tests/test_connector.py

veeceey · 2026-02-12T02:53:23Z

Right -- Sam mentioned considering removing 0 support in v4. This fix is for the current behavior where the docs say "None or 0 disables the timeout" (client_quickstart.html#aiohttp-client-timeouts). Since 0 is currently documented as valid, passing it through shouldn't crash with a ValueError.

Happy to add a deprecation warning for total=0 as well if that helps with the v4 transition, or I can leave that for a separate discussion.

Dreamsorcerer · 2026-02-13T20:50:47Z

Happy to add a deprecation warning for total=0 as well if that helps with the v4 transition, or I can leave that for a separate discussion.

If we're good with dropping support for 0, then I'd like this PR to be moved to the 3.14 branch, and a new PR to master (v4) that removes it.

veeceey · 2026-02-14T03:34:21Z

Makes sense, I'll retarget this to the 3.14 branch with the fix + deprecation warning for total=0, and open a separate PR against master that removes 0 support entirely. Will update shortly.

veeceey · 2026-02-14T03:36:26Z

Created #12067 against the 3.14 branch with the normalization fix.

I'll rework this PR to remove total=0 support for v4 -- will update the ClientTimeout validation to reject 0 with a clear error message, update the docs, and adjust the tests accordingly.

When `ClientTimeout(total=0)` is used (meaning no timeout), the value `0` was passed directly to `asyncio.loop.start_tls()` as `ssl_handshake_timeout`, which requires either `None` or a positive number. This caused a `ValueError`. The fix converts `0` to `None` using `timeout.total or None` before passing it to `start_tls()`, aligning with aiohttp's documented behavior where both `None` and `0` mean "no timeout". Fixes aio-libs#11859 Co-Authored-By: Claude Opus 4.6 <[email protected]>

for more information, see https://pre-commit.ci

…loop.start_tls The Python intersphinx inventory lists asyncio.loop.start_tls as a py:method, not py:func. Using :py:func: causes an unresolved reference warning, which fails the build due to Sphinx's -W flag. Co-Authored-By: Claude Opus 4.6 <[email protected]>

Rewrite test_start_tls_with_zero_total_timeout to use a real TLS server/client instead of mocking internals. This tests actual framework behavior — making an HTTPS request with ClientTimeout(total=0) should succeed without raising ValueError. Also fix changelog to use :exc: Sphinx reference for ValueError.

Instead of normalizing 0 to None for ssl_handshake_timeout, validate upfront that total=0 is not passed. The docs previously said 0 or None disables the timeout, but asyncio.loop.start_tls only accepts None or positive values. For v4, we drop the 0 support entirely with a clear error message directing users to use None instead. Fixes aio-libs#11859

veeceey · 2026-02-14T07:00:54Z

Reworked this for v4 as discussed. Instead of normalizing 0 to None, the PR now:

Adds __post_init__ validation to ClientTimeout that rejects total=0 with a clear error message pointing to None
Reverts the timeout.total or None workaround in connector.py (no longer needed since 0 can't reach it)
Replaces the functional TLS test with simple validation tests

The 3.14 backport (#12067) keeps the normalization approach for backwards compatibility.

Dreamsorcerer · 2026-02-14T15:20:16Z

Appears to be a test to update.

The test_tcp_connector_cancel_dns_error_captured test was still using ClientTimeout(0) which now raises ValueError since total=0 is no longer supported. Use default ClientTimeout() (total=None) instead.

veeceey · 2026-02-15T04:18:00Z

Updated the test, thanks for pointing that out.

veeceey · 2026-02-16T02:53:30Z

Hi @Dreamsorcerer @webknjaz, this has been reworked for v4 as discussed — ClientTimeout now rejects total=0 in post_init with a clear error pointing to None, and I've updated the test that was flagged. The 3.14 backport is in #12067. Ready for another look when you get a chance!

veeceey requested review from asvetlov and webknjaz as code owners February 8, 2026 23:03

psf-chronographer bot added the bot:chronographer:provided There is a change note present in this PR label Feb 8, 2026

webknjaz requested changes Feb 10, 2026

View reviewed changes

CHANGES/11859.bugfix.rst Outdated Show resolved Hide resolved

tests/test_connector.py Outdated Show resolved Hide resolved

tests/test_connector.py Outdated Show resolved Hide resolved

webknjaz requested review from Dreamsorcerer and bdraco February 10, 2026 13:36

veeceey mentioned this pull request Feb 14, 2026

Fix ValueError with ClientTimeout(total=0) in TLS connections #12067

Merged

veeceey and others added 5 commits February 13, 2026 22:58

[pre-commit.ci] auto fixes from pre-commit.com hooks

740dc47

for more information, see https://pre-commit.ci

veeceey force-pushed the fix/issue-11859 branch from cbdf743 to 8972966 Compare February 14, 2026 07:00

veeceey changed the title ~~Fix ValueError with ClientTimeout(total=0) in TLS connections~~ Reject ClientTimeout(total=0) in v4, use None to disable timeouts Feb 14, 2026

Update test to use ClientTimeout() instead of ClientTimeout(0)

8c58af6

The test_tcp_connector_cancel_dns_error_captured test was still using ClientTimeout(0) which now raises ValueError since total=0 is no longer supported. Use default ClientTimeout() (total=None) instead.

patchback bot mentioned this pull request Feb 16, 2026

[PR #12067/830b9421 backport][3.13] Fix ValueError with ClientTimeout(total=0) in TLS connections #12081

Merged

Dreamsorcerer added the backport:skip Skip backport bot label Feb 16, 2026

Dreamsorcerer merged commit 1c472b5 into aio-libs:master Feb 16, 2026
42 of 43 checks passed

Uh oh!

Conversation

veeceey commented Feb 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codspeed-hq bot commented Feb 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merging this PR will not alter performance

Uh oh!

codecov bot commented Feb 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

webknjaz commented Feb 10, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

veeceey commented Feb 12, 2026

Uh oh!

Dreamsorcerer commented Feb 13, 2026

Uh oh!

veeceey commented Feb 14, 2026

Uh oh!

veeceey commented Feb 14, 2026

Uh oh!

veeceey commented Feb 14, 2026

Uh oh!

Dreamsorcerer commented Feb 14, 2026

Uh oh!

veeceey commented Feb 15, 2026

Uh oh!

veeceey commented Feb 16, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

veeceey commented Feb 8, 2026 •

edited

Loading

codspeed-hq bot commented Feb 8, 2026 •

edited

Loading

codecov bot commented Feb 9, 2026 •

edited

Loading