> I realize one could interpret the python3 in the shebang as an 
> "explicit version specification", but a) that's not on the 
> command line, which seems the more natural reading and b) it's 
> only a partial specification, since it doesn't say which python3
> to use.

The wanted version is specified by the command line, else by the script shebang. The default version to use for `py -3` or a "python3" virtual command in a shebang (e.g. "#!/usr/bin/python3") is determined by the PY_PYTHON3 environment variable or the "python3" setting in "py.ini". If a default 3.x version isn't configured, the launcher uses the latest-version installation of 3.x, of which the 64-bit version is preferred (e.g. 3.10 is preferred over 3.10-32, which is preferred over 3.9).

For just `py` or a "python" virtual command in a shebang -- i.e. when no version is specified -- an active virtual environment is preferred. Else it uses the default that's set in PY_PYTHON environment variable or the "python" setting in py.ini. If no default is set, and there's no shebang, the launcher prefers the latest-version 3.x that's installed. If there's a shebang, the launcher prefers the latest-version 2.x that's installed.

Originally, the non-versioned "/usr/bin/env python" virtual command was handled the same as all other non-versioned "python" virtual commands. But later on the "env" form was changed to first try a path search for "python.exe" via WinAPI SearchPathW() before falling back on the common behavior. In most cases this search will find an active virtual environment. But it could be that another directory with "python.exe" is added to the front of PATH after a virtual environment is activated.

---

How about generalizing "/usr/bin/env python*" to support virtual environments by getting the "version" (venv) or "version_info" (virtualenv) value from "%VIRTUAL_ENV%\pyvenv.cfg"? I'd prefer to get that value in locate_venv_python(). It can still set the `version` string to "venv", but extend the INSTALLED_PYTHON record with a `venv_version` string that can be checked in the result of find_python_by_version(L"venv").

Extend locate_python() with a `search` parameter. If `search` is true, then do a path search [1] for `wanted_ver`, with the searched "python*.exe" executable name set depending on the launcher build (i.e. py[w][_d].exe). If searching is skipped or doesn't find a match, then run an active virtual environment if either `wanted_ver` is empty or `search` is true and `wanted_ver` is compatible with the virtual environment. Otherwise locate a registered Python installation based on `wanted_ver` and `from_shebang`.

---

For GUI and debug builds, the PYTHON_EXECUTABLE macro could be split into a base "python[w]" name and an extension "[_d].exe" name, which makes it easy to construct the name to search for given a valid version string. For example, with a pyw_d.exe debug build, "python3" would be searched for as "pythonw3_d.exe".

---

[1] I'd prefer to expand the path search to also check the user and machine "App Paths", which are like "$HOME/.local/bin" and "/usr/bin" for the Windows shell.