Despite the shy mention in the docs, it was not clear to me that the future returned from asyncio.run_coroutine_threadsafe is not compatible with asyncio.ensure_future (and other asyncio functions), and it took me a fair amount of frustration and source-code-digging to figure out what was going on.

To avoid this confusion for other users, I think that a verbose TypeError warning when a concurrent.futures.Future object is passed into asyncio.ensure_future would be very helpful.

`asyncio.run_coroutine_threadsafe` was't designed to be compatible with `asyncio.ensure_future`. It should be used to run a coroutine in an event loop from another thread. You shouldn't need to await on the future it returns.

Totally. But this wasn't immediately clear to me when using the API. A verbose error like this one would have made this behavior more clear to me.

> A verbose error like this one would have made this behavior more clear to me.

Well, it already raises a TypeError with a clear message -- this is how we tell the user that the argument type is not supported in Python.  I don't think we need to specialize this code any further.

Instead I'd suggest to try to improve asyncio documentation for `ensure_future` and `run_coroutine_threadsafe`.

> it already raises a TypeError with a clear message

This is more to my point: I found the TypeError message not clear at all. 

From my prospective, I was using a future object returned from an asyncio function to call another asyncio function, yet that function was telling me it could only use a future with it. 

Though I eventually figured out what was going on, I think that a more clear message at that moment would have been very helpful to me. And I think other users who benefit from this was well.

A better warning/wording for the API would be helpful as well, but I don't think it fully suffices the problem.

> This is more to my point: I found the TypeError message not clear at all. 

> From my prospective, I was using a future object returned from an asyncio function to call another asyncio function, yet that function was telling me it could only use a future with it. 

I understand, but this is the first time I see somebody tries to use `ensure_future` on `run_coroutine_threadsafe` result, which suggests that it's not a common problem.

Specializing error messages makes code more complex and adds to maintenance overhead, so we can't afford to make changes on first request.  In cases like this we usually put the issue on hold to see if more people complain.

Totally understandable. Some final thoughts:

> this is the first time I see somebody tries to use `ensure_future` on `run_coroutine_threadsafe` result, which suggests that it's not a common problem.

 - I wonder how much self-reporting will be done here.

 - I also considered making the existing error message more verbose (I think that still could be effective). However, I decided to open this PR as a separate TypeError to not muddle the language of the probably more common TypeError.

Thanks for your time and insight, Yury!

> - I wonder how much self-reporting will be done here.

Yeah, I don't think we see enough reporting on bugs.python.org.  I hope people will become more vocal :)  I try to monitor what people say about asyncio on SO, Twitter and /r/python to get a better picture.

> - I also considered making the existing error message more verbose (I think that still could be effective).

Feel free to suggest a better wording.

I don't think your specialized error message adds anything.  The the most common mistake, IMO, is going to be not realizing that run_coroutine_threadsafe don't return one of the acceptable types.  So being told that concurrent.future.Future is not acceptable will add zero additional information.  I think the only change that needs to be made is to make the existing message say 'asyncio.Future' instead of just 'Future'.

> Feel free to suggest a better wording.

> I think the only change that needs to be made is to make the existing message say 'asyncio.Future' instead of just 'Future'.

I hear ya. New commit in the PR reverts the TypeError I added, and changes the original TypeError language to simply read "An asyncio.Future ..." instead of just "A Future ...".

New changeset ae5b3260dd459845aad8a30491b76d471577785d by Mariatta (Charles Renwick) in branch 'master':
bpo-30098: Clarify that run_coroutine_threadsafe expects asyncio.Future   (GH-1170)
https://github.com/python/cpython/commit/ae5b3260dd459845aad8a30491b76d471577785d

New changeset 503d74a60aa9290cf8d174eab95fdfdea1f2b284 by Mariatta in branch '3.5':
bpo-30098: Clarify that run_coroutine_threadsafe expects asyncio.Future   (GH-1170) (#1246)
https://github.com/python/cpython/commit/503d74a60aa9290cf8d174eab95fdfdea1f2b284

New changeset a3d8dda7d899bf41ab7eb2c6148459ad276fe295 by Mariatta in branch '3.6':
bpo-30098: Clarify that run_coroutine_threadsafe expects asyncio.Future   (GH-1170) (#1247)
https://github.com/python/cpython/commit/a3d8dda7d899bf41ab7eb2c6148459ad276fe295

PR has been merged and backported to 3.5 and 3.6. 
Thanks everyone :)