[Python-checkins] peps: Add PEP 514: Python registration in the Windows registry
steve.dower
python-checkins at python.org
Sat Feb 6 15:37:56 EST 2016
https://hg.python.org/peps/rev/1b9459d7021e
changeset: 6220:1b9459d7021e
user: Steve Dower <steve.dower at microsoft.com>
date: Sat Feb 06 12:37:37 2016 -0800
summary:
Add PEP 514: Python registration in the Windows registry
files:
pep-0514.txt | 250 +++++++++++++++++++++++++++++++++++++++
1 files changed, 250 insertions(+), 0 deletions(-)
diff --git a/pep-0514.txt b/pep-0514.txt
new file mode 100644
--- /dev/null
+++ b/pep-0514.txt
@@ -0,0 +1,250 @@
+PEP: 514
+Title: Python registration in the Windows registry
+Version: $Revision$
+Last-Modified: $Date$
+Author: Steve Dower <steve.dower at python.org>
+Status: Draft
+Type: Informational
+Content-Type: text/x-rst
+Created: 02-Feb-2016
+Post-History: 02-Feb-2016
+
+Abstract
+========
+
+This PEP defines a schema for the Python registry key to allow third-party
+installers to register their installation, and to allow applications to detect
+and correctly display all Python environments on a user's machine. No
+implementation changes to Python are proposed with this PEP.
+
+Python environments are not required to be registered unless they want to be
+automatically discoverable by external tools.
+
+The schema matches the registry values that have been used by the official
+installer since at least Python 2.5, and the resolution behaviour matches the
+behaviour of the official Python releases.
+
+Motivation
+==========
+
+When installed on Windows, the official Python installer creates a registry key
+for discovery and detection by other applications. This allows tools such as
+installers or IDEs to automatically detect and display a user's Python
+installations.
+
+Third-party installers, such as those used by distributions, typically create
+identical keys for the same purpose. Most tools that use the registry to detect
+Python installations only inspect the keys used by the official installer. As a
+result, third-party installations that wish to be discoverable will overwrite
+these values, resulting in users "losing" their Python installation.
+
+By describing a layout for registry keys that allows third-party installations
+to register themselves uniquely, as well as providing tool developers guidance
+for discovering all available Python installations, these collisions should be
+prevented.
+
+Definitions
+===========
+
+A "registry key" is the equivalent of a file-system path into the registry. Each
+key may contain "subkeys" (keys nested within keys) and "values" (named and
+typed attributes attached to a key).
+
+``HKEY_CURRENT_USER`` is the root of settings for the currently logged-in user,
+and this user can generally read and write all settings under this root.
+
+``HKEY_LOCAL_MACHINE`` is the root of settings for all users. Generally, any
+user can read these settings but only administrators can modify them. It is
+typical for values under ``HKEY_CURRENT_USER`` to take precedence over those in
+``HKEY_LOCAL_MACHINE``.
+
+On 64-bit Windows, ``HKEY_LOCAL_MACHINE\Software\Wow6432Node`` is a special key
+that 32-bit processes transparently read and write to rather than accessing the
+``Software`` key directly.
+
+Structure
+=========
+
+We consider there to be a single collection of Python environments on a machine,
+where the collection may be different for each user of the machine. There are
+three potential registry locations where the collection may be stored based on
+the installation options of each environment::
+
+ HKEY_CURRENT_USER\Software\Python\<Company>\<Tag>
+ HKEY_LOCAL_MACHINE\Software\Python\<Company>\<Tag>
+ HKEY_LOCAL_MACHINE\Software\Wow6432Node\Python\<Company>\<Tag>
+
+Environments are uniquely identified by their Company-Tag pair, with two options
+for conflict resolution: include everything, or give priority to user
+preferences.
+
+Tools that include every installed environment, even where the Company-Tag pairs
+match, should ensure users can easily identify whether the registration was
+per-user or per-machine.
+
+Tools that give priority to user preferences must ignore values from
+``HKEY_LOCAL_MACHINE`` when a matching Company-Tag pair exists is in
+``HKEY_CURRENT_USER``.
+
+Official Python releases use ``PythonCore`` for Company, and the value of
+``sys.winver`` for Tag. Other registered environments may use any values for
+Company and Tag. Recommendations are made in the following sections.
+
+Python environments are not required to register themselves unless they want to
+be automatically discoverable by external tools.
+
+Backwards Compatibility
+-----------------------
+
+Python 3.4 and earlier did not distinguish between 32-bit and 64-bit builds in
+``sys.winver``. As a result, it is possible to have valid side-by-side
+installations of both 32-bit and 64-bit interpreters.
+
+To ensure backwards compatibility, applications should treat environments listed
+under the following two registry keys as distinct, even when the Tag matches::
+
+ HKEY_LOCAL_MACHINE\Software\Python\PythonCore\<Tag>
+ HKEY_LOCAL_MACHINE\Software\Wow6432Node\Python\PythonCore\<Tag>
+
+Environments listed under ``HKEY_CURRENT_USER`` may be treated as distinct from
+both of the above keys, potentially resulting in three environments discovered
+using the same Tag. Alternatively, a tool may determine whether the per-user
+environment is 64-bit or 32-bit and give it priority over the per-machine
+environment, resulting in a maximum of two discovered environments.
+
+It is not possible to detect side-by-side installations of both 64-bit and
+32-bit versions of Python prior to 3.5 when they have been installed for the
+current user. Python 3.5 and later always uses different Tags for 64-bit and
+32-bit versions.
+
+Environments registered under other Company names must use distinct Tags to
+support side-by-side installations. There is no backwards compatibility
+allowance.
+
+Company
+-------
+
+The Company part of the key is intended to group related environments and to
+ensure that Tags are namespaced appropriately. The key name should be
+alphanumeric without spaces and likely to be unique. For example, a trademarked
+name, a UUID, or a hostname would be appropriate::
+
+ HKEY_CURRENT_USER\Software\Python\ExampleCorp
+ HKEY_CURRENT_USER\Software\Python\6C465E66-5A8C-4942-9E6A-D29159480C60
+ HKEY_CURRENT_USER\Software\Python\www.example.com
+
+The company name ``PyLauncher`` is reserved for the PEP 397 launcher
+(``py.exe``). It does not follow this convention and should be ignored by tools.
+
+If a string value named ``DisplayName`` exists, it should be used to identify
+the environment category to users. Otherwise, the name of the key should be
+used.
+
+If a string value named ``SupportUrl`` exists, it may be displayed or otherwise
+used to direct users to a web site related to the environment.
+
+A complete example may look like::
+
+ HKEY_CURRENT_USER\Software\Python\ExampleCorp
+ (Default) = (value not set)
+ DisplayName = "Example Corp"
+ SupportUrl = "http://www.example.com"
+
+Tag
+---
+
+The Tag part of the key is intended to uniquely identify an environment within
+those provided by a single company. The key name should be alphanumeric without
+spaces and stable across installations. For example, the Python language
+version, a UUID or a partial/complete hash would be appropriate; an integer
+counter that increases for each new environment may not::
+
+ HKEY_CURRENT_USER\Software\Python\ExampleCorp\3.6
+ HKEY_CURRENT_USER\Software\Python\ExampleCorp\6C465E66
+
+If a string value named ``DisplayName`` exists, it should be used to identify
+the environment to users. Otherwise, the name of the key should be used.
+
+If a string value named ``SupportUrl`` exists, it may be displayed or otherwise
+used to direct users to a web site related to the environment.
+
+If a string value named ``Version`` exists, it should be used to identify the
+version of the environment. This is independent from the version of Python
+implemented by the environment.
+
+If a string value named ``SysVersion`` exists, it must be in ``x.y`` or
+``x.y.z`` format matching the version returned by ``sys.version_info`` in the
+interpreter. Otherwise, if the Tag matches this format it is used. If not, the
+Python version is unknown.
+
+Note that each of these values is recommended, but optional. A complete example
+may look like this::
+
+ HKEY_CURRENT_USER\Software\Python\ExampleCorp\6C465E66
+ (Default) = (value not set)
+ DisplayName = "Distro 3"
+ SupportUrl = "http://www.example.com/distro-3"
+ Version = "3.0.12345.0"
+ SysVersion = "3.6.0"
+
+InstallPath
+-----------
+
+Beneath the environment key, an ``InstallPath`` key must be created. This key is
+always named ``InstallPath``, and the default value must match ``sys.prefix``::
+
+ HKEY_CURRENT_USER\Software\Python\ExampleCorp\3.6\InstallPath
+ (Default) = "C:\ExampleCorpPy36"
+
+If a string value named ``ExecutablePath`` exists, it must be a path to the
+``python.exe`` (or equivalent) executable. Otherwise, the interpreter executable
+is assumed to be called ``python.exe`` and exist in the directory referenced by
+the default value.
+
+If a string value named ``WindowedExecutablePath`` exists, it must be a path to
+the ``pythonw.exe`` (or equivalent) executable. Otherwise, the windowed
+interpreter executable is assumed to be called ``pythonw.exe`` and exist in the
+directory referenced by the default value.
+
+A complete example may look like::
+
+ HKEY_CURRENT_USER\Software\Python\ExampleCorp\6C465E66\InstallPath
+ (Default) = "C:\ExampleDistro30"
+ ExecutablePath = "C:\ExampleDistro30\ex_python.exe"
+ WindowedExecutablePath = "C:\ExampleDistro30\ex_pythonw.exe"
+
+Help
+----
+
+Beneath the environment key, a ``Help`` key may be created. This key is always
+named ``Help`` if present and has no default value.
+
+Each subkey of ``Help`` specifies a documentation file, tool, or URL associated
+with the environment. The subkey may have any name, and the default value is a
+string appropriate for passing to ``os.startfile`` or equivalent.
+
+If a string value named ``DisplayName`` exists, it should be used to identify
+the help file to users. Otherwise, the key name should be used.
+
+A complete example may look like::
+
+ HKEY_CURRENT_USER\Software\Python\ExampleCorp\6C465E66\Help
+ Python\
+ (Default) = "C:\ExampleDistro30\python36.chm"
+ DisplayName = "Python Documentation"
+ Extras\
+ (Default) = "http://www.example.com/tutorial"
+ DisplayName = "Example Distro Online Tutorial"
+
+Other Keys
+----------
+
+Some other registry keys are used for defining or inferring search paths under
+certain conditions. A third-party installation is permitted to define these keys
+under their Company-Tag key, however, the interpreter must be modified and
+rebuilt in order to read these values.
+
+Copyright
+=========
+
+This document has been placed in the public domain.
\ No newline at end of file
--
Repository URL: https://hg.python.org/peps
More information about the Python-checkins
mailing list