[issue26582] asyncio documentation links to wrong CancelledError
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 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26582> _______________________________________
Changes by STINNER Victor <victor.stinner@gmail.com>: ---------- nosy: +haypo _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26582> _______________________________________
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 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26582> _______________________________________
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 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26582> _______________________________________
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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26582> _______________________________________
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 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26582> _______________________________________
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 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26582> _______________________________________
Irit Katriel <iritkatriel@yahoo.com> added the comment: 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 ---------- nosy: +iritkatriel _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue26582> _______________________________________
Andrew Svetlov <andrew.svetlov@gmail.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 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue26582> _______________________________________
Change by Andrew Svetlov <andrew.svetlov@gmail.com>: ---------- resolution: -> out of date stage: patch review -> resolved status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue26582> _______________________________________
Changes by STINNER Victor <victor.stinner@gmail.com>: ---------- nosy: +haypo _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26582> _______________________________________
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 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26582> _______________________________________
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 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26582> _______________________________________
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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26582> _______________________________________
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 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26582> _______________________________________
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 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26582> _______________________________________
Irit Katriel <iritkatriel@yahoo.com> added the comment: 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 ---------- nosy: +iritkatriel _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue26582> _______________________________________
Andrew Svetlov <andrew.svetlov@gmail.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 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue26582> _______________________________________
Change by Andrew Svetlov <andrew.svetlov@gmail.com>: ---------- resolution: -> out of date stage: patch review -> resolved status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue26582> _______________________________________
participants (8)
-
Andrew Svetlov -
awilfox
-
Berker Peksag
-
Irit Katriel
-
Jelle Zijlstra
-
R. David Murray
-
SilentGhost
-
STINNER Victor