iSharkFly-Open
/
python-peps
mirror of https://github.com/python/peps.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

update to reflect new C impl, refer some impl details to launcher docs

This commit is contained in:
Mark Hammond 2011-07-21 16:19:40 +10:00
parent d65528918f
commit 87b5e7eaff
1 changed files with 66 additions and 119 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

185
pep-0397.txt
View File

@ -7,7 +7,7 @@ Status: Draft
Type: Standards Track Type: Standards Track
Content-Type: text/plain Content-Type: text/plain
Created: 15-Mar-2011 Created: 15-Mar-2011
Post-History: 17-May-2011, 15-Mar-2011 Post-History: 21-July-2011, 17-May-2011, 15-Mar-2011
Abstract Abstract
@ -41,7 +41,7 @@ Rationale
page describes a valid shebang line. page describes a valid shebang line.
Additionally, these operating systems provide symbolic-links to Additionally, these operating systems provide symbolic-links to
Python executables in well-known directories. For example, many Python executables in well-known directories. For example, many
systems will have a link /usr/bin/python which references a systems will have a link /usr/bin/python which references a
particular version of Python installed under the operating-system. particular version of Python installed under the operating-system.
These symbolic links allow Python to be executed without regard for These symbolic links allow Python to be executed without regard for
@ -67,8 +67,8 @@ Rationale
An overview of the launcher. An overview of the launcher.
This PEP outlines the general functionality and key guidelines of a This PEP outlines the general functionality and key guidelines of a
launcher for Windows. It is accompanied by a reference implementation launcher for Windows. It is accompanied by an implementation [3],
[3], written in Python, which defines the detailed implementation. Over written in C, which defines the detailed implementation. Over
time, changes to the implementation may be desired - if the changes time, changes to the implementation may be desired - if the changes
adhere to the guidelines in this PEP and have been made following adhere to the guidelines in this PEP and have been made following
the standard Python development model this PEP need not change. 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 feature offered by the launcher but instead to offer guidelines the
launcher should adhere to. launcher should adhere to.
The actual implementation of the launcher will be written in C and The launcher will come in 2 versions - one which is a console program and
will not link directly or indirectly with Python, but the Python one which is a "windows" (ie., GUI) program. These 2 launchers correspond
based reference implementation should always remain the canonical to the 'python.exe' and 'pythonw.exe' executables which currently ship
description of the functionality. Any changes proposed to the with Python. The console launcher will be named 'py.exe' and the Windows
launcher functionality should first be made and agreed to in the one named 'pyw.exe'. The "windows" (ie., GUI) version of the launcher
Python implementation, after which time the C implementation can be will attempt to locate and launch pythonw.exe even if a virtual shebang
changed to reflect the new reference. Any deviations between the line nominates simply "python" - infact, the trailing 'w' notation will
functionality of the reference implementation versus the C not be supported in the virtual shebang line at all.
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 be distributed with all future versions of Python The launcher will be distributed with all future versions of Python
and if possible, should be installed somewhere likely to already be and if possible, should be installed directly into the Windows directory
on the system PATH (eg., the Windows System32) directory. If installed, (note that the System32 directory is not a good option as this directory
the "console" version of the launcher should be associated with .py files is not on the default PATH for 32bit processes on a 64bit Windows.) If
and the "windows" version associated with .pyw files. 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 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 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 versions of Python can install an updated version of the launcher without
impacting how the previously installed version of the launcher is used. 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 interactively - for example, starting the launcher with no command-line
arguments will launch the default Python with no command-line arguments. arguments will launch the default Python with no command-line arguments.
Further, command-line arguments will be supported to allow a specific Further, command-line arguments will be supported to allow a specific
Python version to be launched interactively - however, these conveniences 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. be easy to avoid if desired.
Guidelines for a Python launcher. Guidelines for a Python launcher.
@ -130,7 +123,7 @@ Guidelines for a Python launcher.
in [1], including all restrictions listed. in [1], including all restrictions listed.
The launcher should support shebang lines commonly found on Unix. 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 though there is unlikely to be an executable in the relative Windows
directory "\usr\bin". This means that many scripts can use a single 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 shebang line and be likely to work on both Unix and Windows without
@ -146,20 +139,21 @@ Guidelines for a Python launcher.
common links on Unix (such as "/usr/bin/jython") and the inability for the common links on Unix (such as "/usr/bin/jython") and the inability for the
launcher to automatically locate the installation location of these launcher to automatically locate the installation location of these
implementations on Windows, the launcher will support this via implementations on Windows, the launcher will support this via
customization options. Scripts taking advantage of this will not be customization options. Scripts taking advantage of this will not be
portable (as these customization options must be set to reflect the portable (as these customization options must be set to reflect the
configuration of the machine on which the launcher is running) but this configuration of the machine on which the launcher is running) but this
ability is nonetheless considered worthwhile. ability is nonetheless considered worthwhile.
On Unix, the user can control which specific version of Python is used 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 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 the launcher on Windows will not use Windows links, cutomization options
will be used to override the semantics for determining exactly what (exposed via both environment variables and INI files) will be used to
version of Python will be used. For example, while a shebang line of override the semantics for determining what version of Python will be
"/usr/bin/python2" will automatically locate a Python 2.x implementation, used. For example, while a shebang line of "/usr/bin/python2" will
an environment variable can override exactly which Python 2.x automatically locate a Python 2.x implementation, an environment variable
implementation will be chosen. Similarly for "/usr/bin/python" and can override exactly which Python 2.x implementation will be chosen.
"/usr/bin/python3". This is specified in detail later in this PEP. Similarly for "/usr/bin/python" and "/usr/bin/python3". This is
specified in detail later in this PEP.
Shebang line parsing Shebang line parsing
@ -172,17 +166,19 @@ Shebang line parsing
followed by a space character, the customized command will be used. followed by a space character, the customized command will be used.
See below for a description of customized commands. See below for a description of customized commands.
* If the command starts with the strings '/usr/bin/python', * The launcher will define a set of strings which are considered Unix
'/usr/bin/env python' or 'python' the command will be treated as a 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 'virtual command' and the rules described in Python Version Qualifiers
(below) will be used to locate the executable to use. (below) will be used to locate the executable to use.
* Otherwise the command is assumed to be directly ready to execute - ie. * Otherwise the command is assumed to be directly ready to execute - ie.
a fully-qualified path optionally followed by arguments. The contents a fully-qualified path (or a reference to an executable on the PATH)
of the string will not be parsed - it will be passed directly to the optionally followed by arguments. The contents of the string will not
Windows CreateProcess function after appending the name of the script be parsed - it will be passed directly to the Windows CreateProcess
and the launcher command-line arguments. This means that the rules used function after appending the name of the script and the launcher
by CreateProcess will be used, including how relative path names and 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 executable references without extensions are treated. Notably, the
Windows command processor will not be used, so special rules used by the Windows command processor will not be used, so special rules used by the
command processor (such as automatic appending of extensions other than 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 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 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 located and the arguments passed to that. However, if a valid
shebang line is found but the process specified by that line can not shebang line is found but the process specified by that line can not
be started, the default interpreter will not be started - the error 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 in shebang lines:
Virtual Commands are shebang lines which start with the strings Virtual Commands are shebang lines which start with strings which would
'/usr/bin/python', '/usr/bin/env python' or 'python'. Optionally, the 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), virtual command may be suffixed with a version qualifier (see below),
such as '/usr/bin/python2' or '/usr/bin/python3.2'. The command executed such as '/usr/bin/python2' or '/usr/bin/python3.2'. The command executed
is based on the rules described in Python Version Qualifiers below. 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 result in the launcher using the command-line 'c:\bin\vpython.exe -foo
doit.py' doit.py'
Two .ini files will be searched by the launcher - 'py.ini' in the The precise details about the names, locations and search order of the
current user's "application data" directory (ie, the directory returned .ini files is in the launcher documentation [4]
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.
Python Version Qualifiers Python Version Qualifiers
@ -246,19 +238,6 @@ Python Version Qualifiers
the 32bit implementation of that version be used. Note that no "-64" the 32bit implementation of that version be used. Note that no "-64"
qualifier is necessary as this is the default implementation (see below). 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 On 64bit Windows with both 32bit and 64bit implementations of the
same (major.minor) Python version installed, the 64bit version will same (major.minor) Python version installed, the 64bit version will
always be preferred. This will be true for both 32bit and 64bit 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 execute a 64bit Python installation of the specified version if
available. This is so the behavior of the launcher can be predicted available. This is so the behavior of the launcher can be predicted
knowing only what versions are installed on the PC and without knowing only what versions are installed on the PC and without
regard to the order in which they were installed. As noted above, an regard to the order in which they were installed (ie, without knowing
optional "-32" suffix can be used on a version specifier to change this whether a 32 or 64bit version of Python and corresponding launcher was
behaviour. installed last). As noted above, an optional "-32" suffix can be used
on a version specifier to change this behaviour.
Examples: The launcher will support various customization options to allow
fine-grained control over which specific Python version is chosen given
* If no relevant options are set, the commands 'python' and a partial or empty version qualifier - see the launcher documentation [4]
'python2' will use the latest Python 2.x version installed and for details.
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
Command-line handling Command-line handling
@ -316,10 +262,10 @@ Command-line handling
If the only command-line argument is "-h" or "--help", the launcher will If the only command-line argument is "-h" or "--help", the launcher will
print a small banner and command-line usage, then pass the argument to 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 the default Python. This will cause help for the launcher being printed
followed by help for Python itself. The output from the launcher will followed by help for Python itself. The output from the launcher will
attempt to clearly indicate the extended help information is coming from clearly indicate the extended help information is coming from the
the launcher and not Python. launcher and not Python.
As a concession to interactively launching Python, the launcher will As a concession to interactively launching Python, the launcher will
support the first command-line argument optionally being a dash ("-") 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. child is launched using the exact same version running the parent script.
If sys.executable referred to the launcher the child would be likely 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 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 SyntaxError.
be considered.
Another hurdle is the support for alternative Python implementations Another hurdle is the support for alternative Python implementations
using the "customized commands" feature described above, where loading 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 Given these considerations, the launcher will execute it's command in a
child process, remaining alive while the child process is executing, then 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, 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 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 automatically killed when the parent is terminated (although children of
@ -386,7 +331,9 @@ References
[2] http://www.python.org/dev/peps/pep-0394/ [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 Copyright