The patch for issue 23465 (PEP 486) updated the docs to explain the behavior of #!/usr/bin/env as follows:

    The /usr/bin/env form of shebang line has one further special
    property. Before looking for installed Python interpreters, 
    this form will search the executable PATH for a Python 
    executable. This corresponds to the behaviour of the Unix 
    env program, which performs a PATH search. 

This paragraph needs to be added to the 3.4 docs.

Another undocumented feature is adding custom commands in the [commands] section of py.ini. The read_commands function handles this. 

Speaking of which, a side effect of defining SEARCH_PATH in PC/launcher.c is that PATH is searched in find_command if the command isn't found in the global "commands" array. This can lead to unexpected behavior when combined with SKIP_PREFIX (i.e. the skip_prefix function skips past any of the builtin_prefixes in the shebang). For example, #!/usr/bin/perl will search the current directory and PATH for "perl.COM" "perl.EXE", "perl.BAT", etc (i.e. trying each extension listed in PATHEXT). This behavior should be documented. Preferably I think it should also be constrained to only search when the prefix is /usr/bin/env, such as by adding a "search" boolean parameter to the find_command function.