gh-102810 Improve the sphinx docs for asyncio.Timeout

[JosephSBoyle]

I've drafted a PR of some updates to the sphinx docs, as requested on a prev. PR for this issue by @AlexWaygood[0].

• Add a note recommending the use of the async context factories timeout() and timeout_at()
• Add the missing argument to the class definition
• Add a description of what the when param does, and it's possible values.

[0]. #102811 (comment)

• Issue: Add docstrings to asyncio.Timeout #102810

[AlexWaygood]

Thank you! FYI we get docs previews on PRs (you can access it via the "details" button on the "netlify" check down at the bottom), so there's no need to post screenshots on a docs PR :)

[JosephSBoyle]

@AlexWaygood, thanks for the review - I somehow missed that repetition in my self-review.. I suppose my brain was just de-duplicating it subconsciously! (Or more likely I'm sleepy 💤)

[JosephSBoyle]

On a somewhat unrelated note: it occurred to me that it's potentially confusing to have timeout and Timeout behave radically differently when used in the exact same context. timeout takes a duration and Timeout takes an expiry time, which causes
them to behave very differently.

For instance I'm sure one or more people will accidentally use one instead of the other, like so:

async with asyncio.Timeout(1):  # Most likely this `when` has already expired, since `when < loop.time()`
     await asyncio.sleep(0)     # raises a `TimeoutError`
     
async with asyncio.timeout(1):  # This is most likely what the user wants
     await asyncio.sleep(0)     # Behaves as intended

I wonder if perhaps something can be done to ameliorate this. If people agree this is problematic I can open a separate issue.

[AlexWaygood]

On a somewhat unrelated note: it occurred to me that it's potentially confusing to have timeout and Timeout behave radically differently when used in the exact same context. timeout takes a duration and Timeout takes an expiry time, which causes them to behave very differently.

For instance I'm sure one or more people will accidentally use one instead of the other, like so:

async with asyncio.Timeout(1):  # Most likely this `when` has already expired, since `when < loop.time()`
     await asyncio.sleep(0)     # raises a `TimeoutError`
     
async with asyncio.timeout(1):  # This is most likely what the user wants
     await asyncio.sleep(0)     # Behaves as intended

I wonder if perhaps something can be done to ameliorate this. If people agree this is problematic I can open a separate issue.

As you say, the behaviour of timeout is likely what the user wants, and I think that's why we have examples in the docs of how to use timeout, but not Timeout, and why the docs for Timeout are only a subsection of the docs for timeout. I'm not sure what else can be done to ameliorate that :/

[gvanrossum]

The Timeout class is not the recommended API. But it is just public enough that we can’t change it.

[AlexWaygood]

Looks great to me, thanks @JosephSBoyle! Will wait to see if Guido has any final thoughts before merging

[miss-islington]

Thanks @JosephSBoyle for the PR, and @AlexWaygood for merging it 🌮🎉.. I'm working now to backport this PR to: 3.11.
🐍🍒⛏🤖 I'm not a witch! I'm not a witch!

[bedevere-bot]

GH-102958 is a backport of this pull request to the 3.11 branch.