From 87b5e7eaff841d5eee26206059fd32f1078d1993 Mon Sep 17 00:00:00 2001 From: Mark Hammond Date: Thu, 21 Jul 2011 16:19:40 +1000 Subject: [PATCH] update to reflect new C impl, refer some impl details to launcher docs --- pep-0397.txt | 185 ++++++++++++++++++--------------------------------- 1 file changed, 66 insertions(+), 119 deletions(-) diff --git a/pep-0397.txt b/pep-0397.txt index b0e62fc98..effb3b59a 100644 --- a/pep-0397.txt +++ b/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 @@ -41,7 +41,7 @@ Rationale page describes a valid shebang line. 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 particular version of Python installed under the operating-system. These symbolic links allow Python to be executed without regard for @@ -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 @@ -146,20 +139,21 @@ Guidelines for a Python launcher. common links on Unix (such as "/usr/bin/jython") and the inability for the launcher to automatically locate the installation location of these 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 configuration of the machine on which the launcher is running) but this ability is nonetheless considered worthwhile. 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 @@ -316,10 +262,10 @@ Command-line handling 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 - 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. + the default Python. This will cause help for the launcher being printed + followed by help for Python itself. The output from the launcher will + 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