Skip to content

bpo-46566: Add new py.exe launcher implementation #32062

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 15 commits into from
Mar 28, 2022
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 61 additions & 2 deletions Doc/using/windows.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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:
Expand Down
Loading