This line in the docs is incorrect:

    If PY_PYTHON=3 and PY_PYTHON3=3.1, the commands python and python3 
    will both use specifically 3.1

It implies that setting the `python` virtual command to "3" or "2" will use the configured version of the `python3` or `python2` virtual command. As implemented, these three virtual commands are separately configured.

The `python` command is different in one way, since it's also the overall default. If the version set for `python2` or `python3` doesn't match an installed version, that's the end of the search. OTOH, the `python` command will continue to search for any version. For a shebang it prefers "2" over "3", and vice versa for the REPL or a script without a shebang.