[issue21365] asyncio.Task reference misses the most important fact about it, related info spread around intros and example commentary instead
STINNER Victor added the comment: Hi, I pushed my change to add a new BaseEventLoop.create_task() method. For that, I also updated the documentation: http://hg.python.org/cpython/rev/66f06fbf8a2f I rewrote the documentation of the Task method, and more generally all places describing how to create a Task object. I changed the first sentence to Schedule the execution of a coroutine object to be the most explicit. The documentation will be readable online in a few hours: https://docs.python.org/dev/library/asyncio-task.html#task Thanks for your report. -- resolution: - fixed status: open - closed ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue21365 ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue21365] asyncio.Task reference misses the most important fact about it, related info spread around intros and example commentary instead
STINNER Victor added the comment: Victor, since you wrote much of the asyncio doc, any comment on this request? Please write a patch. The change is ok. -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue21365 ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue21365] asyncio.Task reference misses the most important fact about it, related info spread around intros and example commentary instead
Changes by Giampaolo Rodola' g.rod...@gmail.com: -- components: +Asyncio ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue21365 ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue21365] asyncio.Task reference misses the most important fact about it, related info spread around intros and example commentary instead
Terry J. Reedy added the comment: Victor, since you wrote much of the asyncio doc, any comment on this request? -- nosy: +terry.reedy ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue21365 ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue21365] asyncio.Task reference misses the most important fact about it, related info spread around intros and example commentary instead
New submission from Paul Sokolovsky: It caused me a big surprise that asyncio.Task object automatically schedules itself in the main loop for execution upon creation (i.e. in constructor). Nowhere in the main reference part of section 18.5.2.4. Task (https://docs.python.org/3.5/library/asyncio-task.html#task) does it mention that fact. Vice versa, it explicitly says that Task is merely A coroutine object wrapped in a Future., which surely sets grounds for surprise when finding that Task is not just coroutine wrapped in Future, but exhibits extra behavior unexpected of plain Future. Docs cursorily mention this property of Task outside main reference section for it. Specifically: 1) 18.5.2.1. Coroutines, end of intro section: In the case of a coroutine object, there are two basic ways to start it running: call yield from coroutine from another coroutine (assuming the other coroutine is already running!), or convert it to a Task. I would argue that this is way too cursorily and doesn't put strong enough emphasis on the property of self-scheduling, to catch attention of novice or casual reader. For example, my entailments after reading the passage above are: ... or convert it to a Task, to schedule it in a loop [explicitly], because a coroutine can't be scheduled in a loop directly, but Task can be. 2) Very end of subsection 18.5.2.4.1. Example: Parallel execution of tasks, a short line squeezed between colored example block and new section heading - a place where some user will miss it outright: A task is automatically scheduled for execution when it is created. Based on case study above, I would like to propose: 1). In section 18.5.2.4. Task, in class description, make unmissable fact that instantiating an object makes it scheduled. For example, append after: A coroutine object wrapped in a Future. Subclass of Future. following: Instantiating object of this class automatically schedules it to be run in an event loop specified by 'loop' parameter (or default event loop). 2) Ideally, update 2 excerpts above to convey more explicit information, and be more visible (for case 2, for example, move it before the example, not after). -- assignee: docs@python components: Documentation messages: 217272 nosy: docs@python, pfalcon priority: normal severity: normal status: open title: asyncio.Task reference misses the most important fact about it, related info spread around intros and example commentary instead type: enhancement versions: Python 3.5 ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue21365 ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue21365] asyncio.Task reference misses the most important fact about it, related info spread around intros and example commentary instead
Paul Sokolovsky added the comment: Based on discussion https://groups.google.com/forum/#!topic/python-tulip/zfMQIUcIR-0 . That discussion actually questions the grounds of such Task behavior, and points it as a violation of Explicit is better than implicit principle, and as inconsistent behavior wrt to similar objects in Python stdlib (threads, processes, etc.) This ticket however assumes that there're very good reasons for such behavior, and/or it just should be accepted as API idiosyncrasy which is late to fix, and just tries to make sure that docs are not culprit for mismatching user expectations. -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue21365 ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue21365] asyncio.Task reference misses the most important fact about it, related info spread around intros and example commentary instead
Changes by Berker Peksag berker.pek...@gmail.com: -- nosy: +giampaolo.rodola, gvanrossum, haypo, pitrou, yselivanov ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue21365 ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
