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

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.

Victor, since you wrote much of the asyncio doc, any comment on this request?

> Victor, since you wrote much of the asyncio doc, any comment on this request?

Please write a patch. The change is ok.

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.