Skip to content

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

@jonathandung

Description

@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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    Status

    Todo

    Status

    Todo

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions