gh-100247: Fix py.exe launcher not using entire shebang command for finding custom commands (GH-100944)

1 files changed, 27 insertions, 12 deletions

diff --git a/Doc/using/windows.rst b/Doc/using/windows.rst
index fdbe4c1..69bca4d 100644
--- a/Doc/using/windows.rst
+++ b/Doc/using/windows.rst
@@ -831,7 +831,7 @@ To allow shebang lines in Python scripts to be portable between Unix and
 Windows, this launcher supports a number of 'virtual' commands to specify
 which interpreter to use.  The supported virtual commands are:
 
-* ``/usr/bin/env python``
+* ``/usr/bin/env``
 * ``/usr/bin/python``
 * ``/usr/local/bin/python``
 * ``python``
@@ -868,14 +868,28 @@ minor version. I.e. ``/usr/bin/python3.7-32`` will request usage of the
 
 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 :envvar:`PATH` for a Python executable. This corresponds to the
-behaviour of the Unix ``env`` program, which performs a :envvar:`PATH` search.
+executable :envvar:`PATH` for a Python executable matching the name provided
+as the first argument. This corresponds to the behaviour of the Unix ``env``
+program, which performs a :envvar:`PATH` search.
 If an executable matching the first argument after the ``env`` command cannot
-be found, it will be handled as described below. Additionally, the environment
-variable :envvar:`PYLAUNCHER_NO_SEARCH_PATH` may be set (to any value) to skip
-this additional search.
+be found, but the argument starts with ``python``, it will be handled as
+described for the other virtual commands.
+The environment variable :envvar:`PYLAUNCHER_NO_SEARCH_PATH` may be set
+(to any value) to skip this search of :envvar:`PATH`.
+
+Shebang lines that do not match any of these patterns are looked up in the
+``[commands]`` section of the launcher's :ref:`.INI file <launcher-ini>`.
+This may be used to handle certain commands in a way that makes sense for your
+system. The name of the command must be a single argument (no spaces),
+and the value substituted is the full path to the executable (no arguments
+may be added).
 
-Shebang lines that do not match any of these patterns are treated as **Windows**
+.. code-block:: ini
+
+   [commands]
+   /bin/sh=C:\Program Files\Bash\bash.exe
+
+Any commands not found in the .INI file are treated as **Windows** executable
 paths that are absolute or relative to the directory containing the script file.
 This is a convenience for Windows-only scripts, such as those generated by an
 installer, since the behavior is not compatible with Unix-style shells.
@@ -898,15 +912,16 @@ Then Python will be started with the ``-v`` option
 Customization
 -------------
 
+.. _launcher-ini:
+
 Customization via INI files
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Two .ini files will be searched by the launcher - ``py.ini`` in the current
-user's "application data" directory (i.e. the directory returned by calling the
-Windows function ``SHGetFolderPath`` with ``CSIDL_LOCAL_APPDATA``) and ``py.ini`` in the
-same directory as the launcher. The same .ini files are used for both the
-'console' version of the launcher (i.e. py.exe) and for the 'windows' version
-(i.e. pyw.exe).
+user's application data directory (``%LOCALAPPDATA%`` or ``$env:LocalAppData``)
+and ``py.ini`` in the same directory as the launcher. The same .ini files are
+used for both the 'console' version of the launcher (i.e. py.exe) and for the
+'windows' version (i.e. pyw.exe).
 
 Customization specified in the "application directory" will have precedence over
 the one next to the executable, so a user, who may not have write access to the