I agree that the docs are a little confusing on this. Having said that, though, I'm not entirely sure the behaviour needs fixing. The scenario where there's a problem is:

1. User has written a script that needs Python 3 and won't run with Python 2.
2. User does not want to force a specific interpreter, or use the system Python.
3. User wants to use virtualenvs (or otherwise manipulate PATH to switch Python versions) and will sometimes have Python 2 and sometimes Python 3 active.
4. User expects to be able to run the script with Python 2 active and in that case use the system Python 3.

That's a pretty rare situation, IMO. Add to that the fact that it's really hard to detect when the python on PATH is Python 2 (you basically need to run python -V).

The discussion seems to be veering a little too much towards "do what I mean" to me, and I'd prefer we keep the behaviour simple.

I'm happy with the idea that "/usr/bin/env python3" should search, and then fall back to the system defined Python 3. The question is what should we search *for*. There seem to me to be only 2 options:

1. python - but this could select a Python 2 interpreter, so that seems wrong.
2. python3 - that's logical but has a number of quirks
   2a. There isn't a python3 executable supplied as standard, so this behaviour is useless without user customisation.
   2b. Do we want to force searching for additional extensions like .bat? What about .ps1 for Powershell users? What do we do for the GUI version?

Overall, I think option 2 has too many grey areas to be really acceptable, and I'm inclined to say YAGNI, and we simply leave "/usr/bin/env python3" undefined.

For the OP's use case, I'm not clear precisely why "/usr/bin/env python" wouldn't be a sufficiently good approach. If there's a specific scenario in his setup that means we really do *have* to have "/usr/bin/env python3" I'd be grateful if he could clarify. Or to put it another way, is this issue simply "I was surprised it didn't work as I expected" or is it "I cannot do what I want because this doesn't work"?