PEP 514: Python registration in the Windows registry
Hi all I'd like to get this PEP approved (status changed to Active, IIUC). So far (to my knowledge), Anaconda is writing out the new metadata and Visual Studio is reading it. Any changes to the schema now will require somewhat public review anyway, so I don't see any harm in approving the PEP right now. To reiterate, this doesn't require changing anything about CPython at all and has no backwards compatibility impact on official releases (but hopefully it will stop alternative distros from overwriting our essential metadata and causing problems). I suppose I look to Guido first, unless he wants to delegate to one of the other Windows contributors? Cheers, Steve URL: https://www.python.org/dev/peps/pep-0514/ Full text ------- 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.
I was going to delegate to our resident Windows expert, but that's you. :-( Can you suggest someone else? I really don't want to swap in what I once knew about the Windows registry... On Fri, Jul 15, 2016 at 3:20 PM, Steve Dower <steve.dower@python.org> wrote:
Hi all
I'd like to get this PEP approved (status changed to Active, IIUC).
So far (to my knowledge), Anaconda is writing out the new metadata and Visual Studio is reading it. Any changes to the schema now will require somewhat public review anyway, so I don't see any harm in approving the PEP right now.
To reiterate, this doesn't require changing anything about CPython at all and has no backwards compatibility impact on official releases (but hopefully it will stop alternative distros from overwriting our essential metadata and causing problems).
I suppose I look to Guido first, unless he wants to delegate to one of the other Windows contributors?
Cheers, Steve
URL: https://www.python.org/dev/peps/pep-0514/
Full text -------
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. _______________________________________________ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/guido%40python.org
-- --Guido van Rossum (python.org/~guido)
On 15Jul2016 1526, Guido van Rossum wrote:
I was going to delegate to our resident Windows expert, but that's you. :-(
Can you suggest someone else? I really don't want to swap in what I once knew about the Windows registry...
He might not be pleased at the nomination, but Paul Moore would be my first choice. Otherwise Zach still has the obligation that comes with being labelled a Windows expert in the dev guide ;)
On Fri, Jul 15, 2016 at 3:20 PM, Steve Dower <steve.dower@python.org> wrote:
Hi all
I'd like to get this PEP approved (status changed to Active, IIUC).
So far (to my knowledge), Anaconda is writing out the new metadata and Visual Studio is reading it. Any changes to the schema now will require somewhat public review anyway, so I don't see any harm in approving the PEP right now.
To reiterate, this doesn't require changing anything about CPython at all and has no backwards compatibility impact on official releases (but hopefully it will stop alternative distros from overwriting our essential metadata and causing problems).
I suppose I look to Guido first, unless he wants to delegate to one of the other Windows contributors?
Cheers, Steve
URL: https://www.python.org/dev/peps/pep-0514/
Full text -------
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. _______________________________________________ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/guido%40python.org
On 15 July 2016 at 23:39, Steve Dower <steve.dower@python.org> wrote:
On 15Jul2016 1526, Guido van Rossum wrote:
I was going to delegate to our resident Windows expert, but that's you. :-(
Can you suggest someone else? I really don't want to swap in what I once knew about the Windows registry...
He might not be pleased at the nomination, but Paul Moore would be my first choice.
:-) Thanks for the vote of confidence, Steve - if Guido's OK with it I'd be willing to do this. Paul
Yup! Paul is now officially the BDFL-delegate for PEP 514. On Sat, Jul 16, 2016 at 2:44 AM, Paul Moore <p.f.moore@gmail.com> wrote:
On 15 July 2016 at 23:39, Steve Dower <steve.dower@python.org> wrote:
On 15Jul2016 1526, Guido van Rossum wrote:
I was going to delegate to our resident Windows expert, but that's you. :-(
Can you suggest someone else? I really don't want to swap in what I once knew about the Windows registry...
He might not be pleased at the nomination, but Paul Moore would be my first choice.
:-) Thanks for the vote of confidence, Steve - if Guido's OK with it I'd be willing to do this.
Paul
-- --Guido van Rossum (python.org/~guido)
On 16 July 2016 at 18:59, Guido van Rossum <guido@python.org> wrote:
Yup! Paul is now officially the BDFL-delegate for PEP 514.
OK. I've just been reviewing the PEP and have posted some comments. There's a lot of words(!), but I don't think there's a huge amount of substantive change, mostly it's just confirmation of intent. I'll let Steve ponder that, and if anyone else has any further comments to make, now's the time to speak up. Paul
On 16 July 2016 at 08:20, Steve Dower <steve.dower@python.org> wrote:
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.
The second sentence here seems like it should say "... it is not possible ..." (since subsequent paragraphs explain that side-by-side installs of 32-bit and 64-bit versions don't really work properly until 3.5) Cheers, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
Good catch, thanks. Top-posted from my Windows Phone -----Original Message----- From: "Nick Coghlan" <ncoghlan@gmail.com> Sent: 7/15/2016 23:53 To: "Steve Dower" <steve.dower@python.org> Cc: "Python Dev" <python-dev@python.org> Subject: Re: [Python-Dev] PEP 514: Python registration in the Windows registry On 16 July 2016 at 08:20, Steve Dower <steve.dower@python.org> wrote:
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.
The second sentence here seems like it should say "... it is not possible ..." (since subsequent paragraphs explain that side-by-side installs of 32-bit and 64-bit versions don't really work properly until 3.5) Cheers, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
On 15 July 2016 at 23:20, Steve Dower <steve.dower@python.org> wrote:
Hi all
I'd like to get this PEP approved (status changed to Active, IIUC).
Some comments below.
So far (to my knowledge), Anaconda is writing out the new metadata and Visual Studio is reading it. Any changes to the schema now will require somewhat public review anyway, so I don't see any harm in approving the PEP right now.
To reiterate, this doesn't require changing anything about CPython at all and has no backwards compatibility impact on official releases (but hopefully it will stop alternative distros from overwriting our essential metadata and causing problems).
Certainly there's nothing that impacts existing releases. I've noted an issue around sys.winver below, that as an absolute minimum needs a clarification in the 3.6 docs (the documented behaviour of sys.winver isn't explicit enough to provide the uniqueness guarantees this PEP needs) and may in fact need a code change or a PEP change if sys.winver doesn't actually distinguish between 32-bit and 64-bit builds (I've not been able to confirm that either way, unfortunately). [...]
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.
The PEP seems quite strongly focused on GUI tools, where the normal mode of operation would be to present the user with a list of "available installations" (with extra data where possible, not just a bare list of names) and ask for a selection. I'd like to see console tools considered as well. Basically, I'd like to avoid tool developers reading this section and thinking "it only applies to GUI tools or OS integration, not to me". For example, virtualenv introspects the available Python installations - see https://github.com/pypa/virtualenv/blob/master/virtualenv.py#L86 - to support the "-p <interpreter>" flag. To handle this well, it would be useful to allow distributions to register a "short tag", so that as well as "-p 3.5" or "-p 2", Virtualenv could support (say) "-p conda3.4" or "-p pypy2". (The short tag should be at the Company level, so "conda" or "pypy", and the version gets added to that). Another place where this might be useful is the py.exe launcher (it's not in scope for this PEP, but having the data needed to allow the launcher to invoke any available installation could be useful for future enhancements). Another key motivation for me would be to define clearly what information tools can rely on being able to get from the available registry entries describing what's installed. Whenever I've needed to scan the registry, the things I've needed to find out are where I find the Python interpreter, what Python version it is, and whether it's 32-bit or 64-bit. The first so that I can run Python, and the latter two so that I can tell if this is a version I support *without* needing to run the interpreter. For me, everything else in this PEP is about UI, but those 3 items plus the "short tag" idea are more about what capabilities I can provide. [...]
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.
It might be worth being more explicit here that 32-bit and 64-bit processes see the registry keys slightly differently. More on this below.
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.
(As Nick pointed out, "it is not possible to have valid...". I'd also add "under the rules described above"). Also, Python 3.5 doesn't appear to include the architecture in sys.winver either.
py Python 3.5.1 (v3.5.1:37a07cee5969, Dec 6 2015, 01:54:25) [MSC v.1900 64 bit (AMD64)] on win32 Type "help", "copyright", "credits" or "license" for more information.
import sys sys.winver '3.5'
(Unless it adds -32 for 32-bit, and reserves the bare version for 64-bit. I've skimmed the CPython source but can't confirm that). The documentation of sys.winver makes no mention of whether it distinguishes 32- and 64-bit builds. In fact, it states "The value is normally the first three characters of version". If we're relying on sys.winver being unique by version/architecture, the docs need to say so (so that future changes don't accidentally violate that).
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.
From what I can see, this latter isn't true. I presume that 64-bit uses no suffix, but 32-bit uses a "-32" suffix? This should probably be made explicit. At a minimum, if I were writing a tool to list all installed Python versions, with only what I have available to go on (the PEP and a 64-bit Python 3.5) I wouldn't be able to write correct code, as I don't have all the information I need.
Also, if we expect to be able to distinguish 32 and 64 bit implementations in this way, that's putting a new restriction on sys.winver, that it returns a different value for 32-bit and 64-bit builds. If that's the case, I'd rather see that explicitly documented, both here and in the sys.winver documentation. I'd actually prefer a more explicit mechanism going forward, but as this is a "backward compatibility" section I'll save that for later.
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.
Clarification needed here? "Environments registered under other Company names have no backward compatibility requirements, and thus each distinct environment must use a distinct Tag, to support side-by-side installations."
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
I'd suggest adding "Human-readable Company values are preferred". UUIDs seem like a horrible idea in practice.
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.
The next few sections are talking about what data gets included in the registry. Much of this is optional, which is perfectly OK, but there are some defaulting rules here as well. I think we should clearly note those data items that tools which read the data can rely on having available. For example, the "Display Name" can always be obtained, either directly or from the Company key. But the support URL may or may not exist. This is important IMO, as it provides a guide for tool writers over what details they are entitled to assume they know about a distribution. This becomes more important later, when the technical information starts appearing. It's also worth noting that "Display Name" isn't actually as useful as it sounds, in practice. A tool that relies on it would report the python.org installers as being provided by "PythonCore", which isn't particularly user friendly. Maybe we need something in the "Backward Compatibility" section going into a bit more detail as to how tools should deal with that, and maybe we need to add a "DisplayName" in 3.6+.
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
Again, I'd add a recommendation that human readable Tag values be used whenever possible.
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.
To an extent there's the same comment here as for DisplayName for Company - it needs to be defined with consideration for how it will be used. This is, of course, more of a "quality of implementation" matter than a standards one. But the PEP might benefit from an example of use, maybe showing the output from a hypothetical command line tool that lists all installations on the machine.
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.
I'm not too happy with this. What's the benefit of allowing an installation to *not* provide the Python version? Instead, I'd prefer to say: 1. All installations must provide the Python version. They are free to use x.y or x.y.z. format (i.e., the micro version is optional - although again what's the benefit? Why not mandate x.y for consistency?). The rule given in SysVersion is fine (without the final sentence). 2. If CPython *does*, as I'm assuming, use 3.5-32, then that's an issue, because CPython doesn't follow the PEP. Maybe we should allow the Tag to be version-architecture. 3. Following on from (2) we should include a string value SysArchitecture for the architecture (32 or 64) as well. Again, this should always be available from the value or the Tag. The reason I think that the interpreter version and architecture should be mandatory is because otherwise a tool that (for example) only supports Python 3.4 or greater, or only 64-bit, has no way to exclude unsupported installations. So in summary: SysVersion = x.y SysArchitecture = 32 or 64 If SysArchitecture is missing, Tag must end in -32 or -64, and the part after the "-" is the architecture. If SysVersion is missing, Tag must be x.y or x.y-NN and the version is x.y. For backward compatibility, if Company is "PythonCore", SysArchitecture is missing, and Tag doesn't end in -NN, then SysArchitecture is 32 if the registry key is under Wow6432Node. Otherwise, it's 64 if we're a 64-bit process and 32 if we're a 32-bit process. This final heuristic could be wrong, though, and code that cannot cope with getting the wrong value (for example, it's planning on loading the Python DLL into its address space) MUST take other measures to check, or ignore any ambiguous entries. (I'm open to the above being corrected - I didn't check any references when writing it down). BTW, is there any reason why the python.org installers couldn't be modified to provide *all* the information suggested in this PEP, rather than just sticking with what we've traditionally provided? It would be a good example of how to register yourself "properly", as well as avoiding the sort of ambiguity we see above.
Note that each of these values is recommended, but optional.
SysVersion and SysArchitecture (or a Tag that works as a fallback) should be mandatory. Otherwise I'm OK with this statement.
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.
These two items assume implicitly that a Python installation must provide python.exe and pythonw.exe. I'm inclined to make this explicit. Specifically, I think it's crucial that tools can read the (console or windowed) executable path as described here, and run that executable with standard Python command line arguments, and expect it to work. Otherwise there's little point in the installation registering its existence. I can see an argument for a distribution providing just python.exe and omitting pythonw.exe (or even the other way around). But I can't see how I could write generic code to work with such a distribution. So let's disallow that possibility until someone comes up with a concrete use case [...]
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.
I think we need to be clearer here. First of all, it should probably clearly state that any subkey of the <Company>\<Tag> key (and any value of that key, I guess), unless explicitly documented in this PEP, is free for any use by the vendor (Although this may make later expansion of this PEP hard - do we want to worry about that?). We should also note that PythonCore has a number of such "private" keys, and tools should not assume any particular meaning for them. Secondly, I think we should be more explicit about the search path issue. Maybe something like the following (this is based on my memory of the issue, so apologies for any inaccuracy): """ The Python core has traditionally used certain other keys under the PythonCore\<Tag> key to set interpreter paths and similar. This usage is considered historical, and is retained mainly for backward compatibility[1]. Third party installations are permitted to use a similar approach under their own <Company>\<Tag> namespace, but 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 (not even the PythonCore ones) for determining search paths. Making such changes is a decision for the third party; this PEP makes no recommendation either way. It should be noted, however, that without modification, the Python interpreter's behaviour will be based on the values under the PythonCore namespace, not under the vendor's namespace. """ [1] Is this sentence true? IIRC, nothing new is using that feature, and older stuff that did, such as pywin32, is removing it. But I know of no actual plans to rip it out at any point. Paul
On 16Jul2016 1254, Paul Moore wrote:
On 15 July 2016 at 23:20, Steve Dower <steve.dower@python.org> wrote:
Hi all
I'd like to get this PEP approved (status changed to Active, IIUC).
Some comments below.
Awesome, thanks! Posted a pull request at https://github.com/python/peps/pull/59 for ease of diff reading, and some commentary below (with aggressive snipping).
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.
The PEP seems quite strongly focused on GUI tools ... I'd like to avoid tool developers reading this section and thinking "it only applies to GUI tools or OS integration, not to me".
Agreed. I tried to avoid any console/GUI-specific terms, but I can probably be more explicit about it being useful to both.
For example, virtualenv introspects the available Python installations - see https://github.com/pypa/virtualenv/blob/master/virtualenv.py#L86 - to support the "-p <interpreter>" flag. To handle this well, it would be useful to allow distributions to register a "short tag", so that as well as "-p 3.5" or "-p 2", Virtualenv could support (say) "-p conda3.4" or "-p pypy2". (The short tag should be at the Company level, so "conda" or "pypy", and the version gets added to that).
Another place where this might be useful is the py.exe launcher (it's not in scope for this PEP, but having the data needed to allow the launcher to invoke any available installation could be useful for future enhancements).
virtualenv would be a great example to use. My thinking was that the Tag should be appropriate here (perhaps with the Company to disambiguate when necessary), and that is now explicit. Anaconda currently has "Anaconda_4.1.1_64-bit" as their tag, which would not be convenient, so an explicit suggestion here would help ensure this is useful.
Another key motivation for me would be to define clearly what information tools can rely on being able to get from the available registry entries describing what's installed. Whenever I've needed to scan the registry, the things I've needed to find out are where I find the Python interpreter, what Python version it is, and whether it's 32-bit or 64-bit. The first so that I can run Python, and the latter two so that I can tell if this is a version I support *without* needing to run the interpreter. For me, everything else in this PEP is about UI, but those 3 items plus the "short tag" idea are more about what capabilities I can provide.
Good points. I discussed architecture with a colleague at one point and I'm not entirely sure it's universally useful (what architecture is IronPython when built for Any CPU? what architecture is Jython?), but maybe something like the contents of importlib.machinery.IMPORT_SUFFIXES would be?
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.
It might be worth being more explicit here that 32-bit and 64-bit processes see the registry keys slightly differently. More on this below.
I considered this and thought I had a link to the official docs about it. I don't want this PEP to be mistaken for documentation on how registry redirection works :)
Backwards Compatibility -----------------------
Also, Python 3.5 doesn't appear to include the architecture in sys.winver either.
... (Unless it adds -32 for 32-bit, and reserves the bare version for 64-bit. I've skimmed the CPython source but can't confirm that). The documentation of sys.winver makes no mention of whether it distinguishes 32- and 64-bit builds. In fact, it states "The value is normally the first three characters of version". If we're relying on sys.winver being unique by version/architecture, the docs need to say so (so that future changes don't accidentally violate that).
I'll update the docs, but your guess is correct. I changed sys.winver on 32-bit to be "3.5-32" since that matches what py.exe was already using to refer to it. I didn't want to invent yet-another-way-to-tag-architectures. (I also updated py.exe to match tags directly under PythonCore, so 3.5-32 is matched without scanning the binary type.) Also, sys.winver is defined in PCBuild/python.props, which is how we accidentally backported the suffix to 2.7.11 :(
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.
From what I can see, this latter isn't true. I presume that 64-bit uses no suffix, but 32-bit uses a "-32" suffix? This should probably be made explicit. At a minimum, if I were writing a tool to list all installed Python versions, with only what I have available to go on (the PEP and a 64-bit Python 3.5) I wouldn't be able to write correct code, as I don't have all the information I need.
Also, if we expect to be able to distinguish 32 and 64 bit implementations in this way, that's putting a new restriction on sys.winver, that it returns a different value for 32-bit and 64-bit builds. If that's the case, I'd rather see that explicitly documented, both here and in the sys.winver documentation.
I'd actually prefer a more explicit mechanism going forward, but as this is a "backward compatibility" section I'll save that for later.
I don't want to lock in the actual scheme of the tags used by CPython. Granted, without SysArchitecture in the key you can't identify the architecture from the information you have, but Tags are supposed to be treated as opaque with the exception of those that were released prior to 3.5 (also not explicit, so I'll fix that).
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
I'd suggest adding "Human-readable Company values are preferred". UUIDs seem like a horrible idea in practice.
Maybe, but name-squatting seems equally bad (and I've seen enough collaborative registration systems like this to see the value in guaranteed uniqueness). I'll recommend trademarked names though.
It's also worth noting that "Display Name" isn't actually as useful as it sounds, in practice. A tool that relies on it would report the python.org installers as being provided by "PythonCore", which isn't particularly user friendly. Maybe we need something in the "Backward Compatibility" section going into a bit more detail as to how tools should deal with that, and maybe we need to add a "DisplayName" in 3.6+.
I'll specify defaults for PythonCore on each of them and add them to 3.6 (once the PEP is approved and we agree on the values). It certainly doesn't harm the usefulness, but we do want to make sure that tools are handling old PythonCore entries in a consistent way.
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.
To an extent there's the same comment here as for DisplayName for Company - it needs to be defined with consideration for how it will be used. This is, of course, more of a "quality of implementation" matter than a standards one. But the PEP might benefit from an example of use, maybe showing the output from a hypothetical command line tool that lists all installations on the machine.
It's defined as being used to "identify ... to users". Equally, the SupportUrl "may be displayed or otherwise used to direct users to [support]". I feel that these are strong enough definitions, and that showing an hypothetical command line tool output might be seen as too prescriptive (or alternatively, swinging the pendulum too far away from GUI tools).
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.
I'm not too happy with this. [...]
Note that each of these values is recommended, but optional.
SysVersion and SysArchitecture (or a Tag that works as a fallback) should be mandatory. Otherwise I'm OK with this statement.
Snipped most of the details because I agree it's unsatisfying right now, but I disagree with enough of the counterproposal that it was getting to be messy commenting on each bit. Basically, I added SysArchitecture (to match platform.architecture()[0], typically '32bit' or '64bit' but extensible without having to define all potential values in the PEP) with a note that for PythonCore it should be inferred from the registry path. SysVersion no longer allows inferring it from the Tag, except for PythonCore and only when SysVersion is missing. I'm very keen to not force any of this information to be required as it is very difficult to know how to deal with interpreters that don't include it. Does virtualenv refuse to list/use it, even if the install path is valid, just because SysArchitecture was omitted? What if the registry becomes corrupt - should Visual Studio refuse to show what information it can obtain? I already stated that all information is recommended. The change I've made now is that tools shouldn't work too hard to guess - if SysVersion is missing, they can simply say they don't know what version the interpreter is. If knowing the version is critically important, they can refuse to use it, but for many applications this is not going to be the case. And Python 3.6 will specify all of the keys. Adding it to Python 3.5 is only likely to cause issues now with people who test against 3.5.3 and not 3.5.2, which didn't have the keys.
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.
These two items assume implicitly that a Python installation must provide python.exe and pythonw.exe. I'm inclined to make this explicit. Specifically, I think it's crucial that tools can read the (console or windowed) executable path as described here, and run that executable with standard Python command line arguments, and expect it to work. Otherwise there's little point in the installation registering its existence.
Again, there's a backwards compatibility argument here in that Python 3.4 and earlier did not create full paths to the executables. But that can be called out separately. When you say "assume implicitly ... python.exe and pythonw.exe", do you mean executables by those names (counterexample - IronPython includes ipy.exe and ipyw.exe, which you either know specially or would discover from these keys)? Or BOTH executables (e.g. python.exe AND pythonw.exe)? Or executables with equivalent behaviour? I'd argue that the whole PEP only applies to Python interpreters, and if you don't support standard command line arguments you aren't really a Python interpreter and shouldn't be registering as one. But I hesitate to try and define a hard rule that captures all the possible nuances here - I'd rather deal with it by having users file bugs against offending interpreters for not working correctly.
I can see an argument for a distribution providing just python.exe and omitting pythonw.exe (or even the other way around). But I can't see how I could write generic code to work with such a distribution. So let's disallow that possibility until someone comes up with a concrete use case
I think in this case, you'd either specify both keys with the same path (so tools that want the windowed executable are going to get a console window) or omit the key and make sure you don't have a "pythonw.exe" in your install directory (which seems unlikely :) ). These keys are mainly about the possibility of renaming the executables, as shown in the example. But I've added a note reminding tools developers that the executable may not exist, and attempting to launch it may fail (i.e. business as usual).
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.
I think we need to be clearer here. ...
Great suggestion. I've revised this section. (I have vague plans to make the PythonPath subkey redundant in more cases for 3.6, and I *think* we can probably drop the Modules key completely, but I'm not entirely sure it's a good idea. Still thinking about it :) ) Cheers, Steve
On 18 July 2016 at 17:33, Steve Dower <steve.dower@python.org> wrote:
Some comments below.
Awesome, thanks! Posted a pull request at https://github.com/python/peps/pull/59 for ease of diff reading, and some commentary below (with aggressive snipping).
Thanks - I'll do a proper review of that, but just wanted to make a few comments here.
virtualenv would be a great example to use. My thinking was that the Tag should be appropriate here (perhaps with the Company to disambiguate when necessary), and that is now explicit.
Anaconda currently has "Anaconda_4.1.1_64-bit" as their tag, which would not be convenient, so an explicit suggestion here would help ensure this is useful.
Yeah, that's not a useful value for this use case. What I'm thinking of is that currently a number of projects (for example, virtualenv, tox, and a personal Powershell wrapper I have round virtualenv) do this registry introspection exercise, purely to provide a "more convenient" way of specifying a Python version than giving the full path to the interpreter. Unix users have versioned executables, so -p python3.5 works fine, but Windows users don't have that. So my idea is "something as easy to remember as python3.5". But having said this, we're talking about a theoretical extension to existing functionality, that probably has marginal utility at best, so I don't want to get hung up on details here.
Snipped most of the details because I agree it's unsatisfying right now, but I disagree with enough of the counterproposal that it was getting to be messy commenting on each bit.
I take your points here. What I was trying to avoid (because I've encountered it myself) is having to actually *run* the Python interpreter to extract this information. Unix code does this freely, because running subprocesses is so cheap there, but starting up a load of processes on Windows is a non-trivial cost. But again, this is in the area of "potential use cases" rather than "we need it now", so I'm OK with deferring the question if you're uncertain. OK, that's enough off-the-cuff responses. I'll find some time to review your PR (probably tomorrow) and comment there. Paul
On 18 July 2016 at 18:01, Paul Moore <p.f.moore@gmail.com> wrote:
On 18 July 2016 at 17:33, Steve Dower <steve.dower@python.org> wrote:
Some comments below.
Awesome, thanks! Posted a pull request at https://github.com/python/peps/pull/59 for ease of diff reading, and some commentary below (with aggressive snipping).
Thanks - I'll do a proper review of that, but just wanted to make a few comments here.
Added some comments to the PR. Basically: 1. We could do with a better descrition of use cases. 2. We either require registry keys to be user-friendly (no UUIDs!) or we find an alternative approach for the virtualenv-style use case. 3. Registering "how to start the interpreter" (python.exe or whatever) should be mandatory. I don't think we're far off, though. Paul
On 19 July 2016 at 10:49, Paul Moore <p.f.moore@gmail.com> wrote:
On 18 July 2016 at 18:01, Paul Moore <p.f.moore@gmail.com> wrote:
On 18 July 2016 at 17:33, Steve Dower <steve.dower@python.org> wrote:
Some comments below.
Awesome, thanks! Posted a pull request at https://github.com/python/peps/pull/59 for ease of diff reading, and some commentary below (with aggressive snipping).
Thanks - I'll do a proper review of that, but just wanted to make a few comments here.
Added some comments to the PR. Basically:
1. We could do with a better descrition of use cases. 2. We either require registry keys to be user-friendly (no UUIDs!) or we find an alternative approach for the virtualenv-style use case. 3. Registering "how to start the interpreter" (python.exe or whatever) should be mandatory.
I don't think we're far off, though.
For what it's worth, the following code seems to do a reasonable job of scanning the registry according to the rules in the PEP. If anyone has access to any 3rd party installations of Python that follow the proposed PEP's rules, it would be interesting to try this script against them. import winreg def list_subkeys(key): i = 0 while True: try: yield winreg.EnumKey(key, i) except WindowsError: return i += 1 locations = [ ("64-bit", winreg.HKEY_LOCAL_MACHINE, winreg.KEY_WOW64_64KEY), ("32-bit", winreg.HKEY_LOCAL_MACHINE, winreg.KEY_WOW64_32KEY), ("user", winreg.HKEY_CURRENT_USER, 0), ] if __name__ == "__main__": seen = {} for loc, hive, bits in locations: k = winreg.CreateKeyEx(hive, "Software\\Python", 0, winreg.KEY_READ | bits) for company in list_subkeys(k): sk = winreg.CreateKey(k, company) for tag in list_subkeys(sk): try: prefix = winreg.QueryValue(sk, "{}\InstallPath".format(tag)) except WindowsError: # If there's no InstallPath, it's not a valid registration continue clash = "" if seen.get((company, tag)): clash = "Overrides" if hive == winreg.HKEY_CURRENT_USER else "Ambiguous" print("{}\{} ({}) {} {}".format(company, tag, loc, prefix, clash)) seen[(company, tag)] = True This code works (and gives the same results) on at least 2.7 and 3.4+ (32 and 64 bit). I didn't test on older versions. It was tricky enough to get right that I'll probably package it up and publish it at some point. Steve - if you want to add it to the PEP as a sample implementation, that's fine with me, too. Some notes: 1. Python 2.7 allows "Ambiguous" system installs. In other words, the <Tag> is the same for 32 and 64 bit, but the installer doesn't stop you installing both. Python 3.4 has the same <Tag> but the installer prevents installing both 32 and 64 bit versions. 2. Prior to 3.5, it's impossible without running the interpreter or inspecting the exe to determine if a user install is 32 or 64 bit. You can tell for a system install based on which registry key you found the data on. As these are both legacy / "backward compatibility" issues, they aren't a problem with the PEP as such. Paul
Why do you need SysArchitecture? Surely the 32bit pythons are registered in the 32bit registry and the 64 bit pythons in the 64 bit registry. you can side by side install python 3.4 but only if you install 64 bit first then 32 bit second. Barry
On 15 Jul 2016, at 23:20, Steve Dower <steve.dower@python.org> wrote:
Hi all
I'd like to get this PEP approved (status changed to Active, IIUC).
So far (to my knowledge), Anaconda is writing out the new metadata and Visual Studio is reading it. Any changes to the schema now will require somewhat public review anyway, so I don't see any harm in approving the PEP right now.
To reiterate, this doesn't require changing anything about CPython at all and has no backwards compatibility impact on official releases (but hopefully it will stop alternative distros from overwriting our essential metadata and causing problems).
I suppose I look to Guido first, unless he wants to delegate to one of the other Windows contributors?
Cheers, Steve
URL: https://www.python.org/dev/peps/pep-0514/
Full text -------
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. _______________________________________________ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/barry%40barrys-emacs.org
On 28 July 2016 at 17:51, Barry Scott <barry@barrys-emacs.org> wrote:
Why do you need SysArchitecture? Surely the 32bit pythons are registered in the 32bit registry and the 64 bit pythons in the 64 bit registry.
Per-user installs go in HKEY_CURRENT_USER, which is not architecture-specific. So you either need SysArchitecture, or you have to leave it as "unknown". Paul
The 3.4 issue where ordering matters is a bug in the MSI, incidentally (there's an extra upgrade code in one of them). Python 3.5 does not have the issue and side by side works correctly for both per-user and all-user installs. Top-posted from my Windows Phone -----Original Message----- From: "Barry Scott" <barry@barrys-emacs.org> Sent: 7/28/2016 10:19 To: "Steve Dower" <steve.dower@python.org> Cc: "Python Dev" <python-dev@python.org> Subject: Re: [Python-Dev] PEP 514: Python registration in the Windows registry Why do you need SysArchitecture? Surely the 32bit pythons are registered in the 32bit registry and the 64 bit pythons in the 64 bit registry. you can side by side install python 3.4 but only if you install 64 bit first then 32 bit second. Barry
On 15 Jul 2016, at 23:20, Steve Dower <steve.dower@python.org> wrote:
Hi all
I'd like to get this PEP approved (status changed to Active, IIUC).
So far (to my knowledge), Anaconda is writing out the new metadata and Visual Studio is reading it. Any changes to the schema now will require somewhat public review anyway, so I don't see any harm in approving the PEP right now.
To reiterate, this doesn't require changing anything about CPython at all and has no backwards compatibility impact on official releases (but hopefully it will stop alternative distros from overwriting our essential metadata and causing problems).
I suppose I look to Guido first, unless he wants to delegate to one of the other Windows contributors?
Cheers, Steve
URL: https://www.python.org/dev/peps/pep-0514/
Full text -------
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. _______________________________________________ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/barry%40barrys-emacs.org
participants (5)
-
Barry Scott -
Guido van Rossum -
Nick Coghlan -
Paul Moore -
Steve Dower