gh-102810 Add docstrings to the public facing methods of the Timeout class

[JosephSBoyle]

Adds docstrings to the public facing methods of the Timeout class.

Adapted from the docs: https://docs.python.org/3/library/asyncio-task.html#asyncio.Timeout.

• Issue: Add docstrings to asyncio.Timeout #102810

[gvanrossum]

Thanks! Here are a few suggestions for improvement.

[AlexWaygood]

A few small suggestions to make the writing slightly more succinct — though some of these cause the language to diverge slightly from the docs at https://docs.python.org/3/library/asyncio-task.html#asyncio.Timeout, and we might want to keep the docs and the docstrings more-or-less in sync. (Though we generally want the docstrings to be shorter than the docs.)

[gvanrossum]

Oops. Sorry, I changed my mind about some of this. :-(

I agree with Alex's suggestions.

[gvanrossum]

Cool! (@AlexWaygood, if you agree you can merge.)

[AlexWaygood]

Two more small things from me.

[AlexWaygood]

I'd like to sync the docs here with some of the changes made in this PR:

cpython/Doc/library/asyncio-task.rst

Lines 623 to 648 in d51a6dc

	.. class:: Timeout()
	An :ref:`asynchronous context manager <async-context-managers>`
	that limits time spent inside of it.
	.. versionadded:: 3.11
	.. method:: when() -> float | None
	Return the current deadline, or ``None`` if the current
	deadline is not set.
	The deadline is a float, consistent with the time returned by
	:meth:`loop.time`.
	.. method:: reschedule(when: float | None)
	Change the time the timeout will trigger.
	If *when* is ``None``, any current deadline will be removed, and the
	context manager will wait indefinitely.
	If *when* is a float, it is set as the new deadline.
	if *when* is in the past, the timeout will trigger on the next
	iteration of the event loop.

Some of the new wordings in this PR are much nicer than what we currently have at https://docs.python.org/3/library/asyncio-task.html#asyncio.Timeout, in my opinion; it would be a shame for the docstrings to be improved but to leave the docs as they are. But perhaps this is a large enough task that it can be done in a separate PR.

Specific changes to the docs I'd like to see are:

• The docs currently falsely imply that the constructor takes 0 arguments (it actually has a required when argument). We should probably move the discussion of the semantics of when from lines 642-648 to the main body of the docs describing the class, like we've done in this PR.
• Lines 625-626 of the docs should be updated to be the same as the first sentence of the new class docstring
• Line 640 of the docs can be changed to "Reschedule the timeout", same as the first (only) sentence of the new docstring for reschedule()

[JosephSBoyle]

Hiya, @AlexWaygood, w.r.t your last comment: I'm happy to do that in a separate PR or here, whichever you prefer.

IMO it might be nicer to get this PR in if you think it's ready, and then we can have a separate PR focussed on the changes to the Sphinx docs that you highlighed.

Your call:)

[AlexWaygood]

IMO it might be nicer to get this PR in if you think it's ready, and then we can have a separate PR focussed on the changes to the Sphinx docs that you highlighed.

Sounds good, let's do that! Thanks for working on this :D

[miss-islington]

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

[bedevere-bot]

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