Update asyncio.ensure_future() documentation

[akindofyoga]

Added back mention that ensure_future actually scheduled obj. This documentation just mentions what ensure_future returns, so I did not realize that ensure_future also schedules obj.

[the-knights-who-say-ni]

Hello, and thanks for your contribution!

I'm a bot set up to make sure that the project can legally accept your contribution by verifying you have signed the PSF contributor agreement (CLA).

Unfortunately we couldn't find an account corresponding to your GitHub username on bugs.python.org (b.p.o) to verify you have signed the CLA (this might be simply due to a missing "GitHub Name" entry in your b.p.o account settings). This is necessary for legal reasons before we can look at your contribution. Please follow the steps outlined in the CPython devguide to rectify this issue.

You can check yourself to see if the CLA has been received.

Thanks again for your contribution, we look forward to reviewing it!

[aeros]

Thanks for the PR @rogerthat94 and welcome!

I have a few recommendations for you:

1. Create an account on https://bugs.python.org/ and sign the CLA. Usually this takes around 24 hours and sometimes the status must be updated manually by checking the status for GitHub.

2. Adjust the PR title to Update asyncio.ensure_future() documentation. The title you are using is definitely along the right lines, but it will make it easier for core developers knowledgeable with that specific function to find this PR.

Let me know if you have any questions and I'll do my best to answer them. (:

[aeros]

The use of the :term: Sphinx role links to Python's glossary directly. :ref: would not be incorrect in this case, but :term: is more specific. The glossary would be probably be the best place to direct users to if they are unfamiliar with coroutines.

Additionally, the extra : character after the Sphinx role isn't needed.

Suggested change

	Schedule the execution of a :ref:`coroutine object <coroutine>`: wrap it in
	Schedule the execution of a :term:`coroutine object <coroutine>` and wrap it in

After adding this change, it may be necessary to split this into an additional line. reST specifies that the maximum line width should be 80 characters, this change would place the total for this line at 82.

[akindofyoga]

Thanks! I have signed the CLA, updated the title, and made the changes that you requested.

[1st1]

I don't understand why this change is needed. The description you added isn't correct -- the function is quite complex and can do multiple things based on the type of its argument. The documentation already describes this all in full in a succinct form.

[bedevere-bot]

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

[1st1]

@rogerthat94 If you want we can do this the other way:

   * a :class:`Task` object wrapping *obj*, if *obj* is a
     coroutine (:func:`iscoroutine` is used for the test);
     in this case the coroutine will be scheduled by
    ``ensure_future()``.
     

[akindofyoga]

The suggestion in your second comment looks fine to me.

The current documentation does not mention that asyncio.ensure_future() will schedule a coroutine. It just says what asyncio.ensure_future() returns. I think highlighting the fact that asyncio.ensure_future() can schedule a coroutine in addition to returning something is important.

[akindofyoga]

I have made the requested changes; please review again

[bedevere-bot]

Thanks for making the requested changes!

@1st1: please review the changes made to this pull request.

[asvetlov]

Is there a thing like scheduled coroutine at all?
There is scheduled callback.
A task starts running just after creation, so there is no created-but-not-started task.

That's how asyncio works, nothing special for ensure_future(): is you have a task the object is either running or finished (successfully or by exception).

The scheduled async function looks incorrect.

[akindofyoga]

The old documentation for ensure_future says "Schedule the execution of a coroutine object: wrap it in a future. Return a Task object."

[1st1]

I mean I say "schedule coroutine" all the time :) Maybe we do need a better terminology, but as it currently stands I guess this one is fine. :)

[miss-islington]

Thanks @rogerthat94 for the PR, and @1st1 for merging it 🌮🎉.. I'm working now to backport this PR to: 3.7, 3.8.
🐍🍒⛏🤖

[miss-islington]

I'm having trouble backporting to 3.8. Reason: 'Error 110 while writing to socket. Connection timed out.'. Please retry by removing and re-adding the needs backport to 3.8 label.

[bedevere-bot]

GH-15361 is a backport of this pull request to the 3.7 branch.

[1st1]

Thank you, @rogerthat94!

[aeros]

Thanks for the PR @rogerthat94 and thanks for the review @1st1 and @asvetlov!

[aeros]

@1st1

Maybe we do need a better terminology, but as it currently stands I guess this one is fine. :)

If we do come up with a better word for it, be sure to add it to the glossary! This will help to ensure that readers have a clear understanding of what is being referred to. There's several async terms on there already.

[miss-islington]

Thanks @rogerthat94 for the PR, and @1st1 for merging it 🌮🎉.. I'm working now to backport this PR to: 3.8.
🐍🍒⛏🤖

[bedevere-bot]

GH-15364 is a backport of this pull request to the 3.8 branch.