asyncio.wait_for() doesn't raise builtin TimeoutError

[paskozdilar]

Documentation

The documentation page about asyncio.wait_for() function says that:

If a timeout occurs, it cancels the task and raises TimeoutError.

The TimeoutError hyperlink leads to the built-in exception "TimeoutError", which would lead any sane user to think that asyncio.wait_for() raises builtin TimeoutError.

However, it doesn't:

#!/usr/bin/env python3

import asyncio


async def main():
    try:
        await asyncio.wait_for(asyncio.sleep(100), timeout=1)
    except TimeoutError:
        print('timeout error')
    except Exception as exc:
        print('not a timeout error:', type(exc))


asyncio.run(main())

The above program prints:

not a timeout error: <class 'asyncio.exceptions.TimeoutError'>

Documentation should be changed to reflect what really happens in Python.

Linked PRs

• gh-110703: Add asyncio.wait_for() change notes for 3.11 #110818
• [3.12] gh-110703: Add asyncio.wait_for() change notes for 3.11 (GH-110818) #110826
• [3.11] gh-110703: Add asyncio.wait_for() change notes for 3.11 (GH-110818) #110827

[Eclips4]

Hello!
In 3.11+ it's already fixed: #86579
For 3.10 and other versions the documentation is correct:

If a timeout occurs, it cancels the task and raises asyncio.TimeoutError.

(from https://docs.python.org/3.10/library/asyncio-task.html#asyncio.wait_for)

So, seems that you reading docs for new versions, but in fact using a old one :)

[paskozdilar]

Ah, you're right.

I assumed nothing has changed because I expected a note, something like:

Changed in version 3.11: Raises builtin TimeoutError instead of asyncio.TimeoutError

Usually that kind of note follow any backwards-incompatible change.

Maybe it would be good idea to add that, it could save future readers from the same confusion I had.

Anyways, thanks for the quick reply :)

[terryjreedy]

Pending a clear decision otherwise, I think the suggested line immediately above should be added.

[kumaraditya303]

Feel free to send a PR!

[paskozdilar]

I've created the PR.

Thank you for the opportunity to contribute to CPython :)