Proposal: Rename ensure_future to create_task

[asvetlov]

During my training sessions I constantly forced to say:

 `ensure_future()` is used for creating new task by 99% of use cases.
 
 The name is not obvious but please remember this quirk. 

Maybe function renaming (with keeping backward compatible alias) could smooth asyncio learning curve a bit?

[gjcarneiro]

To be honest, the most untuitive one was asyncio.async, but got deprecated for some reason. I like asyncio.async() much more than either asyncio.ensure_future() or asyncio.create_task().

I know that it is now a proper keyword, but maybe we could do something sensible with the keyword?

async def foo():
 something

def main():
 task = async foo()

[1st1]

To be honest, the most untuitive one was asyncio.async, but got deprecated for some reason. I like asyncio.async() much more than either asyncio.ensure_future() or asyncio.create_task().

The reason is “async” becoming a keyword.

I know that it is now a proper keyword, but maybe we could do something sensible with the keyword?

async def foo():
 something

def main():
 task = async foo()

I don’t think this is a good idea. Making async an actual operator will require some sort of protocol to make it possible for frameworks other than asyncio to use it. Adding functions is so much easier.

And async() wasn't an obvious name in the first place. It doesn’t say anything about what it does. Why should I call the async() function on a coroutine, if coroutines are already "async"?

[gjcarneiro]

If it's a lot of work, I can understand. But IMHO async is quite clear in intent. It means that something executes asynchronous. As oposed to await, which runs a coroutine or task synchronously. (the fact that async creates a task would be considered a side-effect, however, it just does whatever it takes to ensure the coroutine executes in the background).

If I'm allowed just a bit more of bike-shedding, how about a function asyncio.start()? Seems intuitive and shorter to type than asyncio.create_task().

[1st1]

ensure_future can accept Futures and Tasks, in addition to coroutines. If it's the latter, it will wrap it in a Task. If it's the former, it will just return the passed object doing nothing. The current name clearly reflects what the function is actually doing.

If we want to add a function that only accepts coroutines and turns them into tasks, I'd propose to call it spawn.

start isn't bad, but we're considering to add asyncio.run in the near future, so I think we need more task-specific name.

[mayfield]

+1 to the name spawn. I pretty much never use ensure_future because the name makes my code look ambiguous and it has a small amount of overhead compared to loop.create_task. I also don't like the soft edges and interpolation done by ensure_future but that's another topic. My ideal world would be an asyncio.spawn which is just asyncio.create_task. It would assert that the argument was a coroutine in debug mode and that's it.

…

On Mon, Dec 19, 2016 at 10:54 AM Yury Selivanov ***@***.***> wrote: ensure_future can accept Futures and Tasks, in addition to coroutines. If it's the latter, it will wrap it in a Task. If it's the former, it will just return the passed object doing nothing. The current name clearly reflects what the function is actually doing. If we want to add a function that only accepts coroutines and turns them into tasks, I'd propose to call it spawn. start isn't bad, but we're considering <#465> to add asyncio.run in the near future, so I think we need more task-specific name. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#477 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAIgNK8fnVtFI-M0zQfpSe6DzuehoSUUks5rJsTJgaJpZM4LQ5lV> .

[gjcarneiro]

Yes, spawn is better than start(), I agree.

If we add spawn(), which is supposed to be used with coroutine as argument, turning it into a Task, then I think we can keep ensure_future() alone, as it will mostly be used only internally by asyncio itself, and you can skip it from your training sessions.

[asvetlov]

+1 for spawn. Perfect name.

[gvanrossum]

-1 on spawn(), we already have a family of os.spawn*() functions that create subprocesses.

…

-1 on start(), it's too generic (and doesn't do the same kind of thing as Thread.start() at all).

-1 on create_task(), since if may not return a Task instance. Andrew, was there a reason why you couldn't recommend your students to use loop.create_task()?

[achimnol]

Thanks for having this discussion. :)
I have also felt confusing with the naming of async and ensure_future.

My question is: what's the key rationale to have both asyncio.ensure_future and loop.create_task?
According to documentation, I see the only difference is that ensure_future returns a Future if the input is a Future, where cancellation works differently from a Task.
I still don't understand clearly "why" we have both Task and Future (especially for a single API ensure_future), though the documentation well describes "how" they work differently. My guess is that Future is for a single awaited blocking call whereas Task is for chained multiple blocking calls including yielding the control to the event loop. Am I correct? If so, I reach to the same question as Andrew pointed out: ensure_future is used to create tasks instead of scheduling futures in most use cases, then why should it be named ensure_future?

Another concern is that loop.create_task requires an explicit reference to the event loop while asyncio.ensure_future doesn't. Since now asyncio.get_event_loop() always returns the current scheduling loop inside coroutines, loop.create_task would make people to write boilerplate codes to pass loop arguments.

[achimnol]

So, how about asyncio.schedule()?
I think this would embrace both Task and Future if we want to keep the backward compatibility but also clarify the naming.
The current name asyncio.ensure_future feels like that it "ensures" the full execution of the given Task or Future even when they have exceptions, but this is not true.

[gvanrossum]

The current name asyncio.ensure_future feels like that it "ensures" the full execution of the given Task or Future even when they have exceptions, but this is not true.

Oh, this is an interesting (to me) misunderstanding. The thing that is "ensured" is the type of the return value, not its eventual execution.

The point of ensure_future() is if you have something that could either be a coroutine or a Future (the latter includes a Task because that's a subclass of Future), and you want to be able to call a method on it that is only defined on Future (probably about the only useful example being cancel()). When it is already a Future (or Task) this does nothing; when it is a coroutine it wraps it in a Task.

If you know that you have a coroutine and you want it to be scheduled, the correct API to use is create_task(). The only time when you should be calling ensure_future() is when you are providing an API (like most of asyncio's own APIs) that accepts either a coroutine or a Future and you need to do something to it that requires you to have a Future.

Hopefully this helps. I am beginning to feel that the main thing that's wrong here is that the treatment in the docs is not very good...

[achimnol]

Thanks for clarification. So ensure_future() ensures that the returned object is compatible with Future (either a Task or Future).

Still, I have doubt if it's a good name. The current naming is focusing on the input/output types rather than what it does with the input. And what it does seems to overlap with loop.create_task(). Again, create_task() naming has its own problem; it lacks the sense of side-effect to the event loop (scheduling & execution of the created task). I think these are why people in this thread are suggesting spawn()-like namings.
Now I have realized where my misunderstanding came from: asyncio.async() is action-oriented naming while asyncio.ensure_future() is type-oriented naming, but I thought it was still action-oriented when first introduced in the standard library.

The docs need improvements as well, because several key example codes related to tasks are using ensure_future() to create tasks from coroutines. Notable cases are:

• https://docs.python.org/3.6/library/asyncio-task.html#example-parallel-execution-of-tasks
• https://docs.python.org/3.6/library/asyncio-dev.html#chain-coroutines-correctly

I'd like to know if there are technical reasons to use asyncio.ensure_future() instead of loop.create_task() in above docs (except historical reasons such as that create_task() is introduced later in 3.4.2 and the docs are not just updated yet).

[gjcarneiro]

Guido, I understand you don't like spawn() or start(), but can we still try to come up with a short and intuitive name? I hate writing asyncio.ensure_future() or loop.create_task() (especially since my code usually doesn't have an explicit loop variable around).

It's a pity we cannot use async() anymore. I like @achimnol's schedule suggestion, anything is better than ensure_future(), really... launch(), go()? ... :-)

[gvanrossum]

Here's a counter-question. Why are you using these functions? My guess is that you've got a coroutine that you want to run "in the background", i.e. without waiting for it. What does that coroutine do? Is it a long-running server task? But why not have a "main" task that waits for all your server tasks (using gather() if there could be more than one)? As an added benefit it should be possible to arrange for a cancellation of the main task to cancel all the server tasks automatically, and you could do this in response to a signal (details left as an exercise for the reader :-).

Regarding the docs:

https://docs.python.org/3.6/library/asyncio-task.html#example-parallel-execution-of-tasks -- This should not need the ensure_future() calls at all -- gather() will call it for you when one of its arguments is a coroutine. Also it makes more sense to rewrite the gather() call without a list, like this:

loop.run_complete(gather(
 factorial("A", 2),
 factorial("B", 3),
 factorial("C", 4)))

(But before you propose a patch please test this suggestion!)

https://docs.python.org/3.6/library/asyncio-dev.html#chain-coroutines-correctly --
This seems to be explaining that you should serialize your calls rather than trying to run them as background calls (I agree) and the final example shows that you don't need ensure_future() at all (and again I agree). Maybe we shouldn't have examples that show bad practices?

In the end I still believe that ensure_future() is an appropriately obscure name for a rarely-needed piece of functionality. When creating a task from a coroutine you should use the appropriately-named loop.create_task(). Maybe there should be an alias for that asyncio.create_task()? (You could use asyncio.Task() but the docs explicitly say not to do that -- IIRC that's because uvloop has its own Task class that must be created using loop.create_task(). @1st1?)

[1st1]

Maybe there should be an alias for that asyncio.create_task()?

Yes, that's the idea. It would be nice to have a way to create tasks without explicit loop handling. So asyncio.create_task(coroutine) would work. I still like spawn more (even though os.spawn does something different).

(You could use asyncio.Task() but the docs explicitly say not to do that -- IIRC that's because uvloop has its own Task class that must be created using loop.create_task(). @1st1?)

The initial motivation for adding loop.create_task() was to make it possible for frameworks to inject their own Task implementation, to implement threadlocal-like objects in asyncio. And AFAIK some people use this feature (including me). Later I used create_task to implement a faster Task in uvloop.