bpo-46566: Add new py.exe launcher implementation (GH-32062)

Doc/using/windows.rst

@@ -817,6 +817,13 @@ minor version. I.e. ``/usr/bin/python2.7-32`` will request usage of the
    by the "-64" suffix. Furthermore it is possible to specify a major and
    architecture without minor (i.e. ``/usr/bin/python3-64``).
 
+.. versionchanged:: 3.11
+
+   The "-64" suffix is deprecated, and now implies "any architecture that is
+   not provably i386/32-bit". To request a specific environment, use the new
+   ``-V:<TAG>`` argument with the complete tag.
+
+
 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
@@ -937,13 +944,65 @@ For example:
 Diagnostics
 -----------
 
-If an environment variable ``PYLAUNCH_DEBUG`` is set (to any value), the
+If an environment variable :envvar:`PYLAUNCHER_DEBUG` is set (to any value), the
 launcher will print diagnostic information to stderr (i.e. to the console).
 While this information manages to be simultaneously verbose *and* terse, it
 should allow you to see what versions of Python were located, why a
 particular version was chosen and the exact command-line used to execute the
-target Python.
+target Python. It is primarily intended for testing and debugging.
+
+Dry Run
+-------
+
+If an environment variable :envvar:`PYLAUNCHER_DRYRUN` is set (to any value),
+the launcher will output the command it would have run, but will not actually
+launch Python. This may be useful for tools that want to use the launcher to
+detect and then launch Python directly. Note that the command written to
+standard output is always encoded using UTF-8, and may not render correctly in
+the console.
+
+Install on demand
+-----------------
+
+If an environment variable :envvar:`PYLAUNCHER_ALLOW_INSTALL` is set (to any
+value), and the requested Python version is not installed but is available on
+the Microsoft Store, the launcher will attempt to install it. This may require
+user interaction to complete, and you may need to run the command again.
+
+An additional :envvar:`PYLAUNCHER_ALWAYS_INSTALL` variable causes the launcher
+to always try to install Python, even if it is detected. This is mainly intended
+for testing (and should be used with :envvar:`PYLAUNCHER_DRYRUN`).
+
+Return codes
+------------
 
+The following exit codes may be returned by the Python launcher. Unfortunately,
+there is no way to distinguish these from the exit code of Python itself.
+
+The names of codes are as used in the sources, and are only for reference. There
+is no way to access or resolve them apart from reading this page. Entries are
+listed in alphabetical order of names.
+
++-------------------+-------+-----------------------------------------------+
+| Name              | Value | Description                                   |
++===================+=======+===============================================+
+| RC_BAD_VENV_CFG   | 107   | A :file:`pyvenv.cfg` was found but is corrupt.|
++-------------------+-------+-----------------------------------------------+
+| RC_CREATE_PROCESS | 101   | Failed to launch Python.                      |
++-------------------+-------+-----------------------------------------------+
+| RC_INSTALLING     | 111   | An install was started, but the command will  |
+|                   |       | need to be re-run after it completes.         |
++-------------------+-------+-----------------------------------------------+
+| RC_INTERNAL_ERROR | 109   | Unexpected error. Please report a bug.        |
++-------------------+-------+-----------------------------------------------+
+| RC_NO_COMMANDLINE | 108   | Unable to obtain command line from the        |
+|                   |       | operating system.                             |
++-------------------+-------+-----------------------------------------------+
+| RC_NO_PYTHON      | 103   | Unable to locate the requested version.       |
++-------------------+-------+-----------------------------------------------+
+| RC_NO_VENV_CFG    | 106   | A :file:`pyvenv.cfg` was required but not     |
+|                   |       | found.                                        |
++-------------------+-------+-----------------------------------------------+
 
 
 .. _windows_finding_modules: