New submission from awilfox:
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.
---------- assignee: docs@python components: Documentation messages: 261911 nosy: awilfox, docs@python priority: normal severity: normal status: open title: asyncio documentation links to wrong CancelledError versions: Python 3.5, Python 3.6
SilentGhost added the comment:
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.
---------- nosy: +SilentGhost
R. David Murray added the comment:
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.
---------- nosy: +r.david.murray, yselivanov
STINNER Victor added the comment:
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.
Jelle Zijlstra added the comment:
This patch documents CancelledError in the asyncio documentation.
---------- keywords: +patch nosy: +Jelle Zijlstra Added file: http://bugs.python.org/file43246/issue26582.patch
Berker Peksag added the comment:
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.futur...
---------- nosy: +berker.peksag stage: -> patch review type: -> enhancement
Irit Katriel firstname.lastname@example.org added the comment:
I think this has been fixed in the docs by now. See for instance:
---------- nosy: +iritkatriel
Andrew Svetlov email@example.com added the comment:
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.
---------- nosy: +asvetlov
Change by Andrew Svetlov firstname.lastname@example.org:
---------- resolution: -> out of date stage: patch review -> resolved status: open -> closed