[Python-Dev] Python environment registration in the Windows Registry

[Steve Dower]

I was throwing around some ideas with colleagues about how we detect 
Python installations on Windows from within Visual Studio, and it came 
up that there are many Python distros that install into different 
locations but write the same registry entries. (I knew about this, of 
course, but this time I decided to do something.)

Apart from not being detected properly by all IDEs/tools/installers, 
non-standard distros that register themselves in the official keys may 
also mess with the default sys.path values. For example, at one point 
(possibly still true) if you installed both Canopy and Anaconda, you 
would break the first one because they tried to load the other's stdlib.

Other implementations have different structures or do not register 
themselves at all, which also makes it more complicated for tools to 
discover them.

So here is a rough proposal to standardise the registry keys that can be 
set on Windows in a way that (a) lets other installers besides the 
official ones have equal footing, (b) provides consistent search and 
resolution semantics for tools, and (c) includes slightly more rich 
metadata (such as display names and URLs). Presented in PEP-like form 
here, but if feedback suggests just putting it in the docs I'm okay with 
that too. It is fully backwards compatible with official releases of 
Python (at least back to 2.5, possibly further) and does not require 
modifications to Python or the official installer - it is purely 
codifying a superset of what we already do.

Any and all feedback welcomed, especially from the owners of other 
distros, Python implementations or tools on the list.

Cheers,
Steve

-----

PEP: ???
Title: Python environment registration in the Windows Registry
Version: $Revision$
Last-Modified: $Date$
Author: Steve Dower <steve.dower at python.org>
Status: Draft
Type: ???
Content-Type: text/x-rst
Created: 02-Feb-2016


Abstract
========

When installed on Windows, the official Python installer creates a 
registry key for discovery and detection by other applications. 
Unofficial installers, such as those used by distributions, typically 
create identical keys for the same purpose. However, these may conflict 
with the official installer or other distributions.

This PEP defines a schema for the Python registry key to allow 
unofficial installers to separately 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.

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.

Specification
=============

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. These are::

     HKEY_CURRENT_USER\Software\Python\<Company>\<Tag>
     HKEY_LOCAL_MACHINE\Software\Python\<Company>\<Tag>
     HKEY_LOCAL_MACHINE\Software\Wow6432Node\Python\<Company>\<Tag>

On a given machine, an environment is uniquely identified by its 
Company-Tag pair. Keys should be searched in the order shown, and if the 
same Company-Tag pair appears in more than one of the above locations, 
only the first occurrence is offerred.

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.



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 if Tag matches::

     HKEY_LOCAL_MACHINE\Software\Python\PythonCore\<Tag>
     HKEY_LOCAL_MACHINE\Software\Wow6432Node\Python\PythonCore\<Tag>

Note that this does not apply to Python 3.5 and later, which uses 
different Tags. Environments registered under other Company names must 
use distinct Tags for side-by-side installations.

1. Environments in ``HKEY_CURRENT_USER`` are always preferred
2. Environments in ``HKEY_LOCAL_MACHINE\Software\Wow6432Node`` are 
preferred if the interpreter is known to be 32-bit


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

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"