253 lines
10 KiB
Plaintext
253 lines
10 KiB
Plaintext
PEP: 514
|
|
Title: Python registration in the Windows registry
|
|
Version: $Revision$
|
|
Last-Modified: $Date$
|
|
Author: Steve Dower <steve.dower@python.org>
|
|
Status: Draft
|
|
Type: Informational
|
|
Content-Type: text/x-rst
|
|
Created: 02-Feb-2016
|
|
Post-History: 02-Feb-2016, 01-Mar-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.
|
|
|
|
When tools are selecting a single installed environment from all registered
|
|
environments, the intent is that user preferences from ``HKEY_CURRENT_USER``
|
|
will override matching Company-Tag pairs in ``HKEY_LOCAL_MACHINE``.
|
|
|
|
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. Tools consuming these registrations are
|
|
not required to disambiguate tags other than by preferring the user's setting.
|
|
|
|
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. Alternatively, the interpreter may be
|
|
modified to not use any registry keys for determining search paths. Making such
|
|
changes is a decision for the third party; this PEP makes no recommendation
|
|
either way.
|
|
|
|
Copyright
|
|
=========
|
|
|
|
This document has been placed in the public domain. |