Document how the `msg` parameter for `asyncio.futures.Future.cancel` is used

[jonathandung]

Documentation

Currently, in the user-facing asyncio docs for Futures, it is mentioned that the signature of cancel changed to cancel(msg=None) in python 3.9.

However, the msg parameter has never been explained:

   .. method:: cancel(msg=None)

      Cancel the Future and schedule callbacks.

      If the Future is already *done* or *cancelled*, return ``False``.
      Otherwise, change the Future's state to *cancelled*,
      schedule the callbacks, and return ``True``.

      .. versionchanged:: 3.9
         Added the *msg* parameter.

From its name, users may incorrectly assume it stands for 'message' and thus must be a string, whereas to my understanding, it is but the argument passed to the instance of asyncio.exceptions.CancelledError thrown to waiters of the future, and can be of any type.

See the .rst source of the relevant documentation segment and the asyncio source.

Linked PRs

• gh-148091: asyncio : clarify Future.cancel(msg) behaviour #148248
• [3.14] gh-148091: clarify asyncio.Future.cancel(msg) behaviour (GH-148248) #148299
• [3.13] gh-148091: clarify asyncio.Future.cancel(msg) behaviour (GH-148248) #148300

[manoj-k-m]

Hi , I'd like to work on this issue if it's not already handled. Please let me know if that's okay.

[jonathandung]

Sure.