Created by: gwideman, Oct 1, 2013 4:02 pm
Revised by: gwideman, Oct 2, 2013 10:35 pm (3 revisions)


A page on which to gather some notes about Python Windows Launcher behavior.


Launcher fails to respect PATH

Launcher (C:\Windows\py.exe) is invoked (via Windows file associations) when
  • Command line: user invokes an file by typing just its name
  • In Windows Explorer, user double-clicks file
Launcher (via functionality in source launcher.c) finds a version of Python to launch as follows (decreasing priority, I think):
  • py.exe -3 argument
  • Shebang line in
  • PY_PYTHON environment variable
  • py.ini in same dir as py.exe, or in user's AppData\Local
  • Launcher hunts through the registry for all versions of Python that have been installed, and by default picks the latest 2.x version of Python.
As installed by Python 3.3.x, the last behavior is the default.
The major problem with this default is that it fails to respect the system PATH. So, if the PATH contains only the path to Python 3.3.x, and Python 2.x has been "disabled" by exclusion from PATH, nonetheless Launcher will find and execute it.
This seems a highly unexpected behavior.

Issue submitted

Windows Launcher fails to respect PATH:

Documentation Issues

In all the docs for launcher:
  • The order of precedence for all the factors the influence py.exe's choice of python installation need to be spelled out.
  • Interaction with virtual environments needs to be spelled out.
  • The mechanism by which py.exe actually finds isntalled pythons needs to be spelled out. (Ie: it uses the registry, keys such and such)
  • There is rampant confusion between command-line command, and shebang-line command, with the word "command" often used in an ambiguous context.
  • The directory for user-specific py.ini file (which is %LOCALAPPDATA%) is almost always mistakenly described as some other directory.
  • The several docs about Launcher each cover part of the picture, but none seem complete.

Notes on PEP 397

"The stand-alone installer asks for an alternative location of the installer,"
Should that be "The stand-alone installer asks for an alternative location for the launcher,"?
Python Script Launching:
Incomplete sentence " well as binaries specified without "
"executable in the relative Windows directory "\usr\bin"."
\usr\bin is an absolute path, albeit relative to the current drive.

Configuration file
"current user's "application data" directory"
"Customization specified in the "application directory"
Each of these name directories, but not the one intended, which is the "Local application data" directory.
"(i.e. the directory returned by calling the Windows function SHGetFolderPath with CSIDL_LOCAL_APPDATA,"
Presumably true, but not very useful for the user wanting to find the directory. Better would be to mention:
"This is the directory which can be found in the console with 'dir %LOCALAPPDATA%', or in Windows Explorer by entering %LOCALAPPDATA% into the path slot.
"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 .ini file next to the launcher, can override commands in that global .ini file)"
This is very confusing regarding what the "customization in the application directory" might be, and whether the ini file "next to the launcher" is perhaps distinct from "the global .ini file". Instead, perhaps:
The py.ini in the user's "Local application data" directory has precedence over the global py.ini in py.exe's directory, so that the user will be able to override the global py.ini settings without needing write permissions to the global py.ini.
Python Version Qualifiers
If no version qualifiers are found in a command, the environment variable PY_PYTHON can be set to specify the default version qualifier - the default value is "2". Note this value could specify just a major version (e.g. "2") or a major.minor qualifier (e.g. "2.6"), or even major.minor-32.
So the logic here may be that
  • internally py.exe has a 'default version' variable
  • If there is no PY_PYTHON environment variable defined, the internal 'default version' defaults to '2'
  • Leading to the "hunt down and installed 2, regardless of whether in the PATH" behavior.
In short, py.exe treats the absence of PY_PYTHON as a request by the user to use 2.latest in preference over any python in the PATH.
Shebang line parsing
This entire section is undermined by a consistent muddling of command-line command versus shebang-line command.
If the first command-line argument [to py.exe?] does not start with a dash ('-') character, an attempt will be made to open that argument as a file and parsed for a shebang line according to the rules in [1]::
#! interpreter [optional-arg]
Once parsed, the command will be categorized according to the following rules:
In this passage, the "command" in the last line seems to be about the shebang line, and not the "command-line" in the first sentence.
If the first argument [of what] can not be opened as a file or if no valid shebang line can be found, the launcher will act as if a shebang line of '#!python' was found
This paragraph appears to be the "else" part of the first sentence in the section Shebang line parsing: "an attempt will be made to open that argument as a file".
This would suggest that "first argument" refers to arguments of the command-line, ie: py.exe firstarg. Not to the [optional-arg] shown for the shebang line. But then we'd have py [arg-not-a-flag-nor-file] --> python [arg-not-a-flag-nor-file] ... which does what?

Python Launcher for Windows bitbucket docs
Customizing default Python versions
If no relevant options are set, the commands python and python2 will use the latest Python 2.x version installed and the command python3 will use the latest Python 3.x installed.
Here, 'command' does not refer to a command-line command, but to shebang line.