update to reflect new C impl, refer some impl details to launcher docs
This commit is contained in:
parent
d65528918f
commit
87b5e7eaff
177
pep-0397.txt
177
pep-0397.txt
|
@ -7,7 +7,7 @@ Status: Draft
|
|||
Type: Standards Track
|
||||
Content-Type: text/plain
|
||||
Created: 15-Mar-2011
|
||||
Post-History: 17-May-2011, 15-Mar-2011
|
||||
Post-History: 21-July-2011, 17-May-2011, 15-Mar-2011
|
||||
|
||||
Abstract
|
||||
|
||||
|
@ -67,8 +67,8 @@ Rationale
|
|||
An overview of the launcher.
|
||||
|
||||
This PEP outlines the general functionality and key guidelines of a
|
||||
launcher for Windows. It is accompanied by a reference implementation
|
||||
[3], written in Python, which defines the detailed implementation. Over
|
||||
launcher for Windows. It is accompanied by an implementation [3],
|
||||
written in C, which defines the detailed implementation. Over
|
||||
time, changes to the implementation may be desired - if the changes
|
||||
adhere to the guidelines in this PEP and have been made following
|
||||
the standard Python development model this PEP need not change.
|
||||
|
@ -76,33 +76,26 @@ An overview of the launcher.
|
|||
feature offered by the launcher but instead to offer guidelines the
|
||||
launcher should adhere to.
|
||||
|
||||
The actual implementation of the launcher will be written in C and
|
||||
will not link directly or indirectly with Python, but the Python
|
||||
based reference implementation should always remain the canonical
|
||||
description of the functionality. Any changes proposed to the
|
||||
launcher functionality should first be made and agreed to in the
|
||||
Python implementation, after which time the C implementation can be
|
||||
changed to reflect the new reference. Any deviations between the
|
||||
functionality of the reference implementation versus the C
|
||||
implementation due should imply the C implementation is in error
|
||||
(although some exceptions will need to be made due to the nature of the
|
||||
reference implementation being in Python)
|
||||
|
||||
It is expected that 2 versions of the launcher will be needed - one
|
||||
which is a console program and one which is a "windows" (ie., GUI)
|
||||
program. These 2 launchers correspond to the 'python.exe' and
|
||||
'pythonw.exe' executables which currently ship with Python. The
|
||||
console launcher will be named 'py.exe' and the Windows one named
|
||||
'pyw.exe'. The "windows" (ie., GUI) version of the launcher will attempt
|
||||
to locate and launch pythonw.exe even if a virtual shebang line nominates
|
||||
simply "python" - infact, the trailing 'w' notation will not be supported
|
||||
in the virtual shebang line at all.
|
||||
The launcher will come in 2 versions - one which is a console program and
|
||||
one which is a "windows" (ie., GUI) program. These 2 launchers correspond
|
||||
to the 'python.exe' and 'pythonw.exe' executables which currently ship
|
||||
with Python. The console launcher will be named 'py.exe' and the Windows
|
||||
one named 'pyw.exe'. The "windows" (ie., GUI) version of the launcher
|
||||
will attempt to locate and launch pythonw.exe even if a virtual shebang
|
||||
line nominates simply "python" - infact, the trailing 'w' notation will
|
||||
not be supported in the virtual shebang line at all.
|
||||
|
||||
The launcher will be distributed with all future versions of Python
|
||||
and if possible, should be installed somewhere likely to already be
|
||||
on the system PATH (eg., the Windows System32) directory. If installed,
|
||||
the "console" version of the launcher should be associated with .py files
|
||||
and the "windows" version associated with .pyw files.
|
||||
and if possible, should be installed directly into the Windows directory
|
||||
(note that the System32 directory is not a good option as this directory
|
||||
is not on the default PATH for 32bit processes on a 64bit Windows.) If
|
||||
the launcher can't be installed in the Windows directory, the installer
|
||||
can suggest or choose an alternative, but it will be the responsibility
|
||||
of the user to ensure this directory is on the PATH.
|
||||
|
||||
Once installed, the "console" version of the launcher should be
|
||||
associated with .py files and the "windows" version associated with .pyw
|
||||
files.
|
||||
|
||||
The launcher will not be tied to a specific version of Python - eg., a
|
||||
launcher distributed with Python 3.3 should be capable of locating and
|
||||
|
@ -111,12 +104,12 @@ An overview of the launcher.
|
|||
versions of Python can install an updated version of the launcher without
|
||||
impacting how the previously installed version of the launcher is used.
|
||||
|
||||
The launcher will offer some conveniences for Python developers working
|
||||
The launcher may offer some conveniences for Python developers working
|
||||
interactively - for example, starting the launcher with no command-line
|
||||
arguments will launch the default Python with no command-line arguments.
|
||||
Further, command-line arguments will be supported to allow a specific
|
||||
Python version to be launched interactively - however, these conveniences
|
||||
will not detract from the primary purpose of launching scripts and will
|
||||
must not detract from the primary purpose of launching scripts and must
|
||||
be easy to avoid if desired.
|
||||
|
||||
Guidelines for a Python launcher.
|
||||
|
@ -130,7 +123,7 @@ Guidelines for a Python launcher.
|
|||
in [1], including all restrictions listed.
|
||||
|
||||
The launcher should support shebang lines commonly found on Unix.
|
||||
For example, a shebang line of '!# /usr/bin/python' should work even
|
||||
For example, a shebang line of '#! /usr/bin/python' should work even
|
||||
though there is unlikely to be an executable in the relative Windows
|
||||
directory "\usr\bin". This means that many scripts can use a single
|
||||
shebang line and be likely to work on both Unix and Windows without
|
||||
|
@ -153,13 +146,14 @@ Guidelines for a Python launcher.
|
|||
|
||||
On Unix, the user can control which specific version of Python is used
|
||||
by adjusting the links in /usr/bin to point to the desired version. As
|
||||
the launcher on Windows will not use Windows links, environment variables
|
||||
will be used to override the semantics for determining exactly what
|
||||
version of Python will be used. For example, while a shebang line of
|
||||
"/usr/bin/python2" will automatically locate a Python 2.x implementation,
|
||||
an environment variable can override exactly which Python 2.x
|
||||
implementation will be chosen. Similarly for "/usr/bin/python" and
|
||||
"/usr/bin/python3". This is specified in detail later in this PEP.
|
||||
the launcher on Windows will not use Windows links, cutomization options
|
||||
(exposed via both environment variables and INI files) will be used to
|
||||
override the semantics for determining what version of Python will be
|
||||
used. For example, while a shebang line of "/usr/bin/python2" will
|
||||
automatically locate a Python 2.x implementation, an environment variable
|
||||
can override exactly which Python 2.x implementation will be chosen.
|
||||
Similarly for "/usr/bin/python" and "/usr/bin/python3". This is
|
||||
specified in detail later in this PEP.
|
||||
|
||||
Shebang line parsing
|
||||
|
||||
|
@ -172,17 +166,19 @@ Shebang line parsing
|
|||
followed by a space character, the customized command will be used.
|
||||
See below for a description of customized commands.
|
||||
|
||||
* If the command starts with the strings '/usr/bin/python',
|
||||
'/usr/bin/env python' or 'python' the command will be treated as a
|
||||
* The launcher will define a set of strings which are considered Unix
|
||||
compatible commands to launch Python, such as '/usr/bin/python' etc.
|
||||
If a command matching one of these strings will be treated as a
|
||||
'virtual command' and the rules described in Python Version Qualifiers
|
||||
(below) will be used to locate the executable to use.
|
||||
|
||||
* Otherwise the command is assumed to be directly ready to execute - ie.
|
||||
a fully-qualified path optionally followed by arguments. The contents
|
||||
of the string will not be parsed - it will be passed directly to the
|
||||
Windows CreateProcess function after appending the name of the script
|
||||
and the launcher command-line arguments. This means that the rules used
|
||||
by CreateProcess will be used, including how relative path names and
|
||||
a fully-qualified path (or a reference to an executable on the PATH)
|
||||
optionally followed by arguments. The contents of the string will not
|
||||
be parsed - it will be passed directly to the Windows CreateProcess
|
||||
function after appending the name of the script and the launcher
|
||||
command-line arguments. This means that the rules used by
|
||||
CreateProcess will be used, including how relative path names and
|
||||
executable references without extensions are treated. Notably, the
|
||||
Windows command processor will not be used, so special rules used by the
|
||||
command processor (such as automatic appending of extensions other than
|
||||
|
@ -195,7 +191,7 @@ Shebang line parsing
|
|||
|
||||
If the first argument 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 - ie., a default Python interpreter will be
|
||||
'#!python' was found - ie., a default Python interpreter will be
|
||||
located and the arguments passed to that. However, if a valid
|
||||
shebang line is found but the process specified by that line can not
|
||||
be started, the default interpreter will not be started - the error
|
||||
|
@ -204,8 +200,9 @@ Shebang line parsing
|
|||
|
||||
Virtual commands in shebang lines:
|
||||
|
||||
Virtual Commands are shebang lines which start with the strings
|
||||
'/usr/bin/python', '/usr/bin/env python' or 'python'. Optionally, the
|
||||
Virtual Commands are shebang lines which start with strings which would
|
||||
be expected to work on Unix platforms - examples include
|
||||
'/usr/bin/python', '/usr/bin/env python' and 'python'. Optionally, the
|
||||
virtual command may be suffixed with a version qualifier (see below),
|
||||
such as '/usr/bin/python2' or '/usr/bin/python3.2'. The command executed
|
||||
is based on the rules described in Python Version Qualifiers below.
|
||||
|
@ -227,13 +224,8 @@ Customized Commands:
|
|||
result in the launcher using the command-line 'c:\bin\vpython.exe -foo
|
||||
doit.py'
|
||||
|
||||
Two .ini files will be searched by the launcher - 'py.ini' in the
|
||||
current user's "application data" directory (ie, the directory returned
|
||||
by calling the Windows function SHGetFolderPath with CSIDL_APPDATA) and
|
||||
'py.ini' in the same directory as the launcher. Commands specified
|
||||
in the "application directory" will have precendence over the one next to
|
||||
the executable, and the same .ini files will be used by both the Windows
|
||||
and Console versions of the launcher.
|
||||
The precise details about the names, locations and search order of the
|
||||
.ini files is in the launcher documentation [4]
|
||||
|
||||
Python Version Qualifiers
|
||||
|
||||
|
@ -246,19 +238,6 @@ Python Version Qualifiers
|
|||
the 32bit implementation of that version be used. Note that no "-64"
|
||||
qualifier is necessary as this is the default implementation (see below).
|
||||
|
||||
If no version qualifiers are found, 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 (eg., "2") or a
|
||||
major.minor qualifier (eg., "2.6"), or even major.minor-32.
|
||||
|
||||
If no minor version qualfiers are found, the environment variable
|
||||
PY_PYTHON{major} (where {major} is the current major version qualifier
|
||||
as determined above) can be set to specify the full version. If no such
|
||||
option is found, the launcher will enumerate the installed Python
|
||||
versions and use the latest minor release found for the major version,
|
||||
which is likely, although not guaranteed, to be the most recently
|
||||
installed version in that family.
|
||||
|
||||
On 64bit Windows with both 32bit and 64bit implementations of the
|
||||
same (major.minor) Python version installed, the 64bit version will
|
||||
always be preferred. This will be true for both 32bit and 64bit
|
||||
|
@ -266,48 +245,15 @@ Python Version Qualifiers
|
|||
execute a 64bit Python installation of the specified version if
|
||||
available. This is so the behavior of the launcher can be predicted
|
||||
knowing only what versions are installed on the PC and without
|
||||
regard to the order in which they were installed. As noted above, an
|
||||
optional "-32" suffix can be used on a version specifier to change this
|
||||
behaviour.
|
||||
regard to the order in which they were installed (ie, without knowing
|
||||
whether a 32 or 64bit version of Python and corresponding launcher was
|
||||
installed last). As noted above, an optional "-32" suffix can be used
|
||||
on a version specifier to change this behaviour.
|
||||
|
||||
Examples:
|
||||
|
||||
* 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 lastest Python 3.x installed.
|
||||
|
||||
* The commands 'python3.1' and 'python2.7' will not consult any
|
||||
options at all as the versions are fully specified.
|
||||
|
||||
* if 'PY_PYTHON=3', the commands 'python' and 'python3' will both use
|
||||
the latest installed Python 3 version.
|
||||
|
||||
* if 'PY_PYTHON=3.1-32', the command 'python' will use the 32bit
|
||||
implementation of 3.1 whereas the command 'python3' will use the latest
|
||||
installed Python (PY_PYTHON was not considered at all as a major
|
||||
version was specified.)
|
||||
|
||||
* if 'PY_PYTHON=3' and 'PY_PYTHON3=3.1', the commands
|
||||
'python' and 'python3' will both use specifically 3.1
|
||||
|
||||
In addition to environment variables, the same settings can be configured
|
||||
in the .INI file used by the launcher. The section in the INI file will
|
||||
be called '[defaults]' and the key name will be the same as the
|
||||
environment variables without the leading 'PY_' prefix (and note that
|
||||
the key names in the INI file are case insensitive. The contents of
|
||||
an environment variable will override things specified in the INI file.
|
||||
|
||||
For example:
|
||||
* Setting 'PY_PYTHON=3.1' is equivilent to the INI file
|
||||
containing:
|
||||
[defaults]
|
||||
python=3.1
|
||||
|
||||
* Setting 'PY_PYTHON=3' and 'PY_PYTHON3=3.1' is equivilent to the INI file
|
||||
containing:
|
||||
[defaults]
|
||||
python=3
|
||||
python3=3.1
|
||||
The launcher will support various customization options to allow
|
||||
fine-grained control over which specific Python version is chosen given
|
||||
a partial or empty version qualifier - see the launcher documentation [4]
|
||||
for details.
|
||||
|
||||
Command-line handling
|
||||
|
||||
|
@ -318,8 +264,8 @@ Command-line handling
|
|||
print a small banner and command-line usage, then pass the argument to
|
||||
the default Python. This will cause help for the launcher being printed
|
||||
followed by help for Python itself. The output from the launcher will
|
||||
attempt to clearly indicate the extended help information is coming from
|
||||
the launcher and not Python.
|
||||
clearly indicate the extended help information is coming from the
|
||||
launcher and not Python.
|
||||
|
||||
As a concession to interactively launching Python, the launcher will
|
||||
support the first command-line argument optionally being a dash ("-")
|
||||
|
@ -359,8 +305,7 @@ Process Launching
|
|||
child is launched using the exact same version running the parent script.
|
||||
If sys.executable referred to the launcher the child would be likely
|
||||
executed using a Python 2.x version and would be likely to fail with a
|
||||
SyntaxError. A solution for this would need to be found before this could
|
||||
be considered.
|
||||
SyntaxError.
|
||||
|
||||
Another hurdle is the support for alternative Python implementations
|
||||
using the "customized commands" feature described above, where loading
|
||||
|
@ -372,7 +317,7 @@ Process Launching
|
|||
|
||||
Given these considerations, the launcher will execute it's command in a
|
||||
child process, remaining alive while the child process is executing, then
|
||||
terminate with the same exit code as returned by the child. To address the
|
||||
terminate with the same exit code as returned by the child. To address
|
||||
concerns regarding the termination of the launcher not killing the child,
|
||||
the Win32 Job API will be used to arrange so that the child process is
|
||||
automatically killed when the parent is terminated (although children of
|
||||
|
@ -386,7 +331,9 @@ References
|
|||
|
||||
[2] http://www.python.org/dev/peps/pep-0394/
|
||||
|
||||
[3] http://bugs.python.org/issue11629
|
||||
[3] https://bitbucket.org/vinay.sajip/pylauncher
|
||||
|
||||
[4] https://bitbucket.org/vinay.sajip/pylauncher/src/tip/Docs/launcher.rst
|
||||
|
||||
Copyright
|
||||
|
||||
|
|
Loading…
Reference in New Issue