classification
Title: asyncio documentation links to wrong CancelledError
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.6, Python 3.5
process
Status: closed Resolution: out of date
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Jelle Zijlstra, SilentGhost, asvetlov, awilfox, berker.peksag, docs@python, iritkatriel, r.david.murray, vstinner, yselivanov
Priority: normal Keywords: patch

Created on 2016-03-17 14:45 by awilfox, last changed 2020-12-04 08:18 by asvetlov. This issue is now closed.

Files
File name Uploaded Description Edit
issue26582.patch Jelle Zijlstra, 2016-06-05 19:14 review
Messages (8)
msg261911 - (view) Author: A. Wilcox (awilfox) Date: 2016-03-17 14:45
In the 3.5 and 3.6a0 documentation for asyncio, "CancelledError" is linked to the concurrent.futures.CancelledError.  This led me to try catching that exception and finding that it did not work correctly at all.  Only after searching for asyncio example code and seeing how other people caught asyncio.CancelledError did I realise the issue.

The fact asyncio.CancelledError even exists isn't actually documented, and I believe that is why the :exc: reference is linking to the wrong module.
msg262140 - (view) Author: SilentGhost (SilentGhost) * (Python triager) Date: 2016-03-21 16:51
In fact most of the :exc: reference are pointing explicitly to concurrent.futures.CancelledError (and those that don't probably should). It is interesting that you weren't able to make use of that exception, because in Lib/asyncio/futures.py#L23 it's clearly defined as an alias of the concurrent.futures.CancelledError.

I guess, ultimately, asyncio.CancelleError needs to be documented seeing how widely used it is.
msg266843 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2016-06-01 22:55
ping: Victor or Yuri, do agree that asyncio.CancelledError should be documented?  I know that this duality has confused me in the past as well.  I don't know if having it documented would have helped me ahead of time, but at least it could have cleared up my puzzlement as to why I was seeing a concurrent.futures exception when I didn't think I was using concurrent.futures :)

I do wonder what the OPs actual problem was with catching the exception.
msg266880 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2016-06-02 09:14
> do agree that asyncio.CancelledError should be documented?

Yes, I would prefer to get the exception from asyncio, even if it is
officially an alias to an exception of a different module.

It would be surprising to have to import concurrent.futures in a
module written for asyncio, just to catch this exception.
msg267464 - (view) Author: Jelle Zijlstra (Jelle Zijlstra) * (Python triager) Date: 2016-06-05 19:14
This patch documents CancelledError in the asyncio documentation.
msg268610 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2016-06-15 08:34
CancelledError documentation needs to be updated to mention that it is an alias for 'concurrent.futures.CancelledError'. We also need to update all ``:exc:`~concurrent.futures.CancelledError``` usages in Doc/library/asyncio*.rst. I'd prefer to reuse the description of https://docs.python.org/3.5/library/concurrent.futures.html#concurrent.futures.CancelledError
msg382438 - (view) Author: Irit Katriel (iritkatriel) * (Python committer) Date: 2020-12-03 18:35
I think this has been fixed in the docs by now. See for instance:

https://docs.python.org/3/library/asyncio-task.html#asyncio.gather
https://docs.python.org/3/library/asyncio-future.html#asyncio.Future.result
msg382471 - (view) Author: Andrew Svetlov (asvetlov) * (Python committer) Date: 2020-12-04 08:17
Moreover, the issue is outdated.

asyncio.CancelledError is not an alias of concurrent.futures.CancelledError starting from Python 3.8

Unfortunately, we should make this not 100% backward compatible change.
History
Date User Action Args
2020-12-04 08:18:12asvetlovsetstatus: open -> closed
resolution: out of date
stage: patch review -> resolved
2020-12-04 08:17:57asvetlovsetnosy: + asvetlov
messages: + msg382471
2020-12-03 18:35:56iritkatrielsetnosy: + iritkatriel
messages: + msg382438
2016-06-15 08:34:18berker.peksagsetnosy: + berker.peksag
messages: + msg268610

type: enhancement
stage: patch review
2016-06-05 19:14:44Jelle Zijlstrasetfiles: + issue26582.patch

nosy: + Jelle Zijlstra
messages: + msg267464

keywords: + patch
2016-06-02 09:14:36vstinnersetmessages: + msg266880
2016-06-01 22:55:27r.david.murraysetnosy: + r.david.murray, yselivanov
messages: + msg266843
2016-03-21 16:51:51SilentGhostsetnosy: + SilentGhost
messages: + msg262140
2016-03-17 14:49:41vstinnersetnosy: + vstinner
2016-03-17 14:45:53awilfoxcreate