Hello,
I'm interested to find out if debugging Python scripts with GDB is supported on OSX at all?
I'm referring to the functionality described on https://wiki.python.org/moin/DebuggingWithGdb and on http://fedoraproject.org/wiki/Features/EasierPythonDebugging.
I've tried so far various combinations of pre-compiled GDB from the homebrew package manager, locally-compiled GDB from homebrew, as well as locally compiled GDB from MacPorts, together with a pre-compiled Python 2.7, homebrew-compiled 2.7, and custom compiled Python 2.7 from the official source tarball.
My results so far were not successful. The legacy GDB commands to show a python stack trace or the local variables - do not work. And the new GDB commands (referenced on the Fedora project page) are not present at all in any of the GDB versions.
I've checked the python CI build bot tests, and it seems the new GDB commands are only successfully tested on Linux machines, and are skipped on FreeBSD, OS X, and Solaris machines.
Are the new python <-> GDB commands specific to Linux?
Are there any considerations to take in regards to debug symbols for Python / GDB on OSX?
Has anyone attempted what I'm trying to do?
I would be grateful for any advice.
And I apologize if my choice of the mailing lists is not the best.
Regards, Alex.
PEP 7 requires CPython to use C code conforming to the venerable C89
standard. Traditionally, we've been stuck with C89 due to poor C support
in MSVC. However, MSVC 2013 and 2015 implement the key features of C99.
C99 does not offer anything earth-shattering; here are the features I
think we'd find most interesting:
- Variable declarations can be on any line: removes possibly the most
annoying limitation of C89.
- Inline functions: We can make Py_DECREF and Py_INCREF inline functions
rather than unpleasant macros.
- C++-style line comments: Not an killer feature but commonly used.
- Booleans
In summary, some niceties that would make CPython hacking a little more
fun.
So, what say you to updating PEP 7 to allow C99 features for Python 3.6
(in so much as GCC and MSVC support them)?
Regards,
Benjamin
Hello,
Back in March, I've posted a patch at http://bugs.python.org/issue26526 -- "In parsermodule.c, replace over 2KLOC of hand-crafted validation code, with a DFA".
The motivation for this patch was to enable a memory footprint optimization, discussed at http://bugs.python.org/issue26415
My proposed optimization reduces the memory footprint by up to 30% on the standard benchmarks, and by 200% on a degenerate case which sparked the discussion.
The run time stays unaffected by this optimization.
Python Developer's Guide says: "If you don't get a response within a few days after pinging the issue, then you can try emailing python-dev(a)python.org<mailto:python-dev@python.org> asking for someone to review your patch."
So, here I am.
IMPORTANT NOTICE: The contents of this email and any attachments are confidential and may also be privileged. If you are not the intended recipient, please notify the sender immediately and do not disclose the contents to any other person, use it for any purpose, or store or copy the information in any medium. Thank you.
Hi,
I updated my PEP 509 to make the dictionary version globally unique.
With *two* use cases of this PEP (Yury's method call patch and my FAT
Python project), I think that the PEP is now ready to be accepted.
Globally unique identifier is a requirement for Yury's patch
optimizing method calls ( https://bugs.python.org/issue26110 ). It
allows to check for free if the dictionary was replaced.
I also renamed the ma_version field to ma_version_tag.
HTML version:
https://www.python.org/dev/peps/pep-0509/
Victor
PEP: 509
Title: Add a private version to dict
Version: $Revision$
Last-Modified: $Date$
Author: Victor Stinner <victor.stinner(a)gmail.com>
Status: Draft
Type: Standards Track
Content-Type: text/x-rst
Created: 4-January-2016
Python-Version: 3.6
Abstract
========
Add a new private version to the builtin ``dict`` type, incremented at
each dictionary creation and at each dictionary change, to implement
fast guards on namespaces.
Rationale
=========
In Python, the builtin ``dict`` type is used by many instructions. For
example, the ``LOAD_GLOBAL`` instruction searchs for a variable in the
global namespace, or in the builtins namespace (two dict lookups).
Python uses ``dict`` for the builtins namespace, globals namespace, type
namespaces, instance namespaces, etc. The local namespace (namespace of
a function) is usually optimized to an array, but it can be a dict too.
Python is hard to optimize because almost everything is mutable: builtin
functions, function code, global variables, local variables, ... can be
modified at runtime. Implementing optimizations respecting the Python
semantics requires to detect when "something changes": we will call
these checks "guards".
The speedup of optimizations depends on the speed of guard checks. This
PEP proposes to add a version to dictionaries to implement fast guards
on namespaces.
Dictionary lookups can be skipped if the version does not change which
is the common case for most namespaces. Since the version is globally
unique, the version is also enough to check if the namespace dictionary
was not replaced with a new dictionary. The performance of a guard does
not depend on the number of watched dictionary entries, complexity of
O(1), if the dictionary version does not change.
Example of optimization: copy the value of a global variable to function
constants. This optimization requires a guard on the global variable to
check if it was modified. If the variable is modified, the variable must
be loaded at runtime when the function is called, instead of using the
constant.
See the `PEP 510 -- Specialized functions with guards
<https://www.python.org/dev/peps/pep-0510/>`_ for the concrete usage of
guards to specialize functions and for the rationale on Python static
optimizers.
Guard example
=============
Pseudo-code of an fast guard to check if a dictionary entry was modified
(created, updated or deleted) using an hypothetical
``dict_get_version(dict)`` function::
UNSET = object()
class GuardDictKey:
def __init__(self, dict, key):
self.dict = dict
self.key = key
self.value = dict.get(key, UNSET)
self.version = dict_get_version(dict)
def check(self):
"""Return True if the dictionary entry did not changed
and the dictionary was not replaced."""
# read the version of the dict structure
version = dict_get_version(self.dict)
if version == self.version:
# Fast-path: dictionary lookup avoided
return True
# lookup in the dictionary
value = self.dict.get(self.key, UNSET)
if value is self.value:
# another key was modified:
# cache the new dictionary version
self.version = version
return True
# the key was modified
return False
Usage of the dict version
=========================
Speedup method calls 1.2x
-------------------------
Yury Selivanov wrote a `patch to optimize method calls
<https://bugs.python.org/issue26110>`_. The patch depends on the
`implement per-opcode cache in ceval
<https://bugs.python.org/issue26219>`_ patch which requires dictionary
versions to invalidate the cache if the globals dictionary or the
builtins dictionary has been modified.
The cache also requires that the dictionary version is globally unique.
It is possible to define a function in a namespace and call it
in a different namespace: using ``exec()`` with the *globals* parameter
for example. In this case, the globals dictionary was changed and the
cache must be invalidated.
Specialized functions using guards
----------------------------------
The `PEP 510 -- Specialized functions with guards
<https://www.python.org/dev/peps/pep-0510/>`_ proposes an API to support
specialized functions with guards. It allows to implement static
optimizers for Python without breaking the Python semantics.
Example of a static Python optimizer: the `fatoptimizer
<http://fatoptimizer.readthedocs.org/>`_ of the `FAT Python
<http://faster-cpython.readthedocs.org/fat_python.html>`_ project
implements many optimizations which require guards on namespaces.
Examples:
* Call pure builtins: to replace ``len("abc")`` with ``3``, guards on
``builtins.__dict__['len']`` and ``globals()['len']`` are required
* Loop unrolling: to unroll the loop ``for i in range(...): ...``,
guards on ``builtins.__dict__['range']`` and ``globals()['range']``
are required
Pyjion
------
According of Brett Cannon, one of the two main developers of Pyjion,
Pyjion can also benefit from dictionary version to implement
optimizations.
Pyjion is a JIT compiler for Python based upon CoreCLR (Microsoft .NET
Core runtime).
Unladen Swallow
---------------
Even if dictionary version was not explicitly mentioned, optimizing
globals and builtins lookup was part of the Unladen Swallow plan:
"Implement one of the several proposed schemes for speeding lookups of
globals and builtins." Source: `Unladen Swallow ProjectPlan
<https://code.google.com/p/unladen-swallow/wiki/ProjectPlan>`_.
Unladen Swallow is a fork of CPython 2.6.1 adding a JIT compiler
implemented with LLVM. The project stopped in 2011: `Unladen Swallow
Retrospective
<http://qinsb.blogspot.com.au/2011/03/unladen-swallow-retrospective.html>`_.
Changes
=======
Add a ``ma_version_tag`` field to the ``PyDictObject`` structure with
the C type ``PY_INT64_T``, 64-bit unsigned integer. Add also a global
dictionary version. Each time a dictionary is created, the global
version is incremented and the dictionary version is initialized to the
global version. The global version is also incremented and copied to the
dictionary version at each dictionary change:
* ``clear()`` if the dict was non-empty
* ``pop(key)`` if the key exists
* ``popitem()`` if the dict is non-empty
* ``setdefault(key, value)`` if the `key` does not exist
* ``__detitem__(key)`` if the key exists
* ``__setitem__(key, value)`` if the `key` doesn't exist or if the value
is not ``dict[key]``
* ``update(...)`` if new values are different than existing values:
values are compared by identity, not by their content; the version can
be incremented multiple times
The ``PyDictObject`` structure is not part of the stable ABI.
The field is called ``ma_version_tag`` rather than ``ma_version`` to
suggest to compare it using ``version_tag == old_version_tag`` rather
than ``version <= old_version`` which makes the integer overflow much
likely.
Example using an hypothetical ``dict_get_version(dict)`` function::
>>> d = {}
>>> dict_get_version(d)
100
>>> d['key'] = 'value'
>>> dict_get_version(d)
101
>>> d['key'] = 'new value'
>>> dict_get_version(d)
102
>>> del d['key']
>>> dict_get_version(d)
103
The version is not incremented if an existing key is set to the same
value. For efficiency, values are compared by their identity:
``new_value is old_value``, not by their content:
``new_value == old_value``. Example::
>>> d = {}
>>> value = object()
>>> d['key'] = value
>>> dict_get_version(d)
40
>>> d['key'] = value
>>> dict_get_version(d)
40
.. note::
CPython uses some singleton like integers in the range [-5; 257],
empty tuple, empty strings, Unicode strings of a single character in
the range [U+0000; U+00FF], etc. When a key is set twice to the same
singleton, the version is not modified.
Implementation and Performance
==============================
The `issue #26058: PEP 509: Add ma_version_tag to PyDictObject
<https://bugs.python.org/issue26058>`_ contains a patch implementing
this PEP.
On pybench and timeit microbenchmarks, the patch does not seem to add
any overhead on dictionary operations.
When the version does not change, ``PyDict_GetItem()`` takes 14.8 ns for
a dictionary lookup, whereas a guard check only takes 3.8 ns. Moreover,
a guard can watch for multiple keys. For example, for an optimization
using 10 global variables in a function, 10 dictionary lookups costs 148
ns, whereas the guard still only costs 3.8 ns when the version does not
change (39x as fast).
The `fat module
<http://fatoptimizer.readthedocs.org/en/latest/fat.html>`_ implements
such guards: ``fat.GuardDict`` is based on the dictionary version.
Integer overflow
================
The implementation uses the C type ``PY_UINT64_T`` to store the version:
a 64 bits unsigned integer. The C code uses ``version++``. On integer
overflow, the version is wrapped to ``0`` (and then continue to be
incremented) according to the C standard.
After an integer overflow, a guard can succeed whereas the watched
dictionary key was modified. The bug only occurs at a guard check if
there are exaclty ``2 ** 64`` dictionary creations or modifications
since the previous guard check.
If a dictionary is modified every nanosecond, ``2 ** 64`` modifications
takes longer than 584 years. Using a 32-bit version, it only takes 4
seconds. That's why a 64-bit unsigned type is also used on 32-bit
systems. A dictionary lookup at the C level takes 14.8 ns.
A risk of a bug every 584 years is acceptable.
Alternatives
============
Expose the version at Python level as a read-only __version__ property
----------------------------------------------------------------------
The first version of the PEP proposed to expose the dictionary version
as a read-only ``__version__`` property at Python level, and also to add
the property to ``collections.UserDict`` (since this type must mimick
the ``dict`` API).
There are multiple issues:
* To be consistent and avoid bad surprises, the version must be added to
all mapping types. Implementing a new mapping type would require extra
work for no benefit, since the version is only required on the
``dict`` type in practice.
* All Python implementations must implement this new property, it gives
more work to other implementations, whereas they may not use the
dictionary version at all.
* Exposing the dictionary version at Python level can lead the
false assumption on performances. Checking ``dict.__version__`` at
the Python level is not faster than a dictionary lookup. A dictionary
lookup has a cost of 48.7 ns and checking a guard has a cost of 47.5
ns, the difference is only 1.2 ns (3%)::
$ ./python -m timeit -s 'd = {str(i):i for i in range(100)}' 'd["33"] == 33'
10000000 loops, best of 3: 0.0487 usec per loop
$ ./python -m timeit -s 'd = {str(i):i for i in range(100)}'
'd.__version__ == 100'
10000000 loops, best of 3: 0.0475 usec per loop
* The ``__version__`` can be wrapped on integer overflow. It is error
prone: using ``dict.__version__ <= guard_version`` is wrong,
``dict.__version__ == guard_version`` must be used instead to reduce
the risk of bug on integer overflow (even if the integer overflow is
unlikely in practice).
Mandatory bikeshedding on the property name:
* ``__cache_token__``: name proposed by Nick Coghlan, name coming from
`abc.get_cache_token()
<https://docs.python.org/3/library/abc.html#abc.get_cache_token>`_.
* ``__version__``
* ``__timestamp__``
Add a version to each dict entry
--------------------------------
A single version per dictionary requires to keep a strong reference to
the value which can keep the value alive longer than expected. If we add
also a version per dictionary entry, the guard can only store the entry
version to avoid the strong reference to the value (only strong
references to the dictionary and to the key are needed).
Changes: add a ``me_version`` field to the ``PyDictKeyEntry`` structure,
the field has the C type ``PY_INT64_T``. When a key is created or
modified, the entry version is set to the dictionary version which is
incremented at any change (create, modify, delete).
Pseudo-code of an fast guard to check if a dictionary key was modified
using hypothetical ``dict_get_version(dict)``
``dict_get_entry_version(dict)`` functions::
UNSET = object()
class GuardDictKey:
def __init__(self, dict, key):
self.dict = dict
self.key = key
self.dict_version = dict_get_version(dict)
self.entry_version = dict_get_entry_version(dict, key)
def check(self):
"""Return True if the dictionary entry did not changed
and the dictionary was not replaced."""
# read the version of the dict structure
dict_version = dict_get_version(self.dict)
if dict_version == self.version:
# Fast-path: dictionary lookup avoided
return True
# lookup in the dictionary
entry_version = get_dict_key_version(dict, key)
if entry_version == self.entry_version:
# another key was modified:
# cache the new dictionary version
self.dict_version = dict_version
return True
# the key was modified
return False
The main drawback of this option is the impact on the memory footprint.
It increases the size of each dictionary entry, so the overhead depends
on the number of buckets (dictionary entries, used or unused yet). For
example, it increases the size of each dictionary entry by 8 bytes on
64-bit system.
In Python, the memory footprint matters and the trend is to reduce it.
Examples:
* `PEP 393 -- Flexible String Representation
<https://www.python.org/dev/peps/pep-0393/>`_
* `PEP 412 -- Key-Sharing Dictionary
<https://www.python.org/dev/peps/pep-0412/>`_
Add a new dict subtype
----------------------
Add a new ``verdict`` type, subtype of ``dict``. When guards are needed,
use the ``verdict`` for namespaces (module namespace, type namespace,
instance namespace, etc.) instead of ``dict``.
Leave the ``dict`` type unchanged to not add any overhead (memory
footprint) when guards are not needed.
Technical issue: a lot of C code in the wild, including CPython core,
expecting the exact ``dict`` type. Issues:
* ``exec()`` requires a ``dict`` for globals and locals. A lot of code
use ``globals={}``. It is not possible to cast the ``dict`` to a
``dict`` subtype because the caller expects the ``globals`` parameter
to be modified (``dict`` is mutable).
* Functions call directly ``PyDict_xxx()`` functions, instead of calling
``PyObject_xxx()`` if the object is a ``dict`` subtype
* ``PyDict_CheckExact()`` check fails on ``dict`` subtype, whereas some
functions require the exact ``dict`` type.
* ``Python/ceval.c`` does not completely supports dict subtypes for
namespaces
The ``exec()`` issue is a blocker issue.
Other issues:
* The garbage collector has a special code to "untrack" ``dict``
instances. If a ``dict`` subtype is used for namespaces, the garbage
collector can be unable to break some reference cycles.
* Some functions have a fast-path for ``dict`` which would not be taken
for ``dict`` subtypes, and so it would make Python a little bit
slower.
Prior Art
=========
Method cache and type version tag
---------------------------------
In 2007, Armin Rigo wrote a patch to to implement a cache of methods. It
was merged into Python 2.6. The patch adds a "type attribute cache
version tag" (``tp_version_tag``) and a "valid version tag" flag to
types (the ``PyTypeObject`` structure).
The type version tag is not available at the Python level.
The version tag has the C type ``unsigned int``. The cache is a global
hash table of 4096 entries, shared by all types. The cache is global to
"make it fast, have a deterministic and low memory footprint, and be
easy to invalidate". Each cache entry has a version tag. A global
version tag is used to create the next version tag, it also has the C
type ``unsigned int``.
By default, a type has its "valid version tag" flag cleared to indicate
that the version tag is invalid. When the first method of the type is
cached, the version tag and the "valid version tag" flag are set. When a
type is modified, the "valid version tag" flag of the type and its
subclasses is cleared. Later, when a cache entry of these types is used,
the entry is removed because its version tag is outdated.
On integer overflow, the whole cache is cleared and the global version
tag is reset to ``0``.
See `Method cache (issue #1685986)
<https://bugs.python.org/issue1685986>`_ and `Armin's method cache
optimization updated for Python 2.6 (issue #1700288)
<https://bugs.python.org/issue1700288>`_.
Globals / builtins cache
------------------------
In 2010, Antoine Pitrou proposed a `Globals / builtins cache (issue
#10401) <http://bugs.python.org/issue10401>`_ which adds a private
``ma_version`` field to the ``PyDictObject`` structure (``dict`` type),
the field has the C type ``Py_ssize_t``.
The patch adds a "global and builtin cache" to functions and frames, and
changes ``LOAD_GLOBAL`` and ``STORE_GLOBAL`` instructions to use the
cache.
The change on the ``PyDictObject`` structure is very similar to this
PEP.
Cached globals+builtins lookup
------------------------------
In 2006, Andrea Griffini proposed a patch implementing a `Cached
globals+builtins lookup optimization
<https://bugs.python.org/issue1616125>`_. The patch adds a private
``timestamp`` field to the ``PyDictObject`` structure (``dict`` type),
the field has the C type ``size_t``.
Thread on python-dev: `About dictionary lookup caching
<https://mail.python.org/pipermail/python-dev/2006-December/070348.html>`_.
Guard against changing dict during iteration
--------------------------------------------
In 2013, Serhiy Storchaka proposed `Guard against changing dict during
iteration (issue #19332) <https://bugs.python.org/issue19332>`_ which
adds a ``ma_count`` field to the ``PyDictObject`` structure (``dict``
type), the field has the C type ``size_t``. This field is incremented
when the dictionary is modified, and so is very similar to the proposed
dictionary version.
Sadly, the dictionary version proposed in this PEP doesn't help to
detect dictionary mutation. The dictionary version changes when values
are replaced, whereas modifying dictionary values while iterating on
dictionary keys is legit in Python.
PySizer
-------
`PySizer <http://pysizer.8325.org/>`_: a memory profiler for Python,
Google Summer of Code 2005 project by Nick Smallbone.
This project has a patch for CPython 2.4 which adds ``key_time`` and
``value_time`` fields to dictionary entries. It uses a global
process-wide counter for dictionaries, incremented each time that a
dictionary is modified. The times are used to decide when child objects
first appeared in their parent objects.
Discussion
==========
Thread on the mailing lists:
* python-dev: `PEP 509: Add a private version to dict
<https://mail.python.org/pipermail/python-dev/2016-January/142685.html>`_
(january 2016)
* python-ideas: `RFC: PEP: Add dict.__version__
<https://mail.python.org/pipermail/python-ideas/2016-January/037702.html>`_
(january 2016)
Copyright
=========
This document has been placed in the public domain.
Hi,
It’s getting a tradition for me to work on PEP 447 during the EuroPython sprints and disappear afterwards. Hopefully I can manage to avoid the latter step this year…
Last year the conclusion appeared to be that this is an acceptable PEP, but Mark Shannon had a concern about a default implementation for __getdescriptor__ on type in <https://mail.python.org/pipermail/python-dev/2015-July/140938.html> (follow the link for more context):
> "__getdescriptor__" is fundamentally different from "__getattribute__" in that
> is defined in terms of itself.
>
> object.__getattribute__ is defined in terms of type.__getattribute__, but
> type.__getattribute__ just does
> dictionary lookups. However defining type.__getattribute__ in terms of
> __descriptor__ causes a circularity as
> __descriptor__ has to be looked up on a type.
>
> So, not only must the cycle be broken by special casing "type", but that
> "__getdescriptor__" can be defined
> not only by a subclass, but also a metaclass that uses "__getdescriptor__" to
> define "__getdescriptor__" on the class.
> (and so on for meta-meta classes, etc.)
My reaction that year is in <https://mail.python.org/pipermail/python-dev/2015-August/141114.html>. As I wrote there I did not fully understand the concerns Mark has, probably because I’m focussed too much on the implementation in CPython. If removing type.__getdescriptor__ and leaving this special method as an optional hook for subclasses of type fixes the conceptual concerns then that’s fine by me. I used type.__getdescriptor__ as the default implementation both because it appears to be cleaner to me and because this gives subclasses an easy way to access the default implementation.
The implementation of the PEP in issue 18181 <http://bugs.python.org/issue18181> does special-case type.__getdescriptor__ but only as an optimisation, the code would work just as well without that special casing because the normal attribute lookup machinery is not used when accessing special methods written in C. That is, the implementation of object.__getattribute__ directly accesses fields of the type struct at the C level. Some magic behavior appears to be necessary even without the addition of __getdescriptor__ (type is a subclass of itself, object.__getattribute__ has direct access to dict.__getitem__, …).
I’m currently working on getting the patch in 18181 up-to-date w.r.t. the current trunk, the patch in the issue no longer applies cleanly. After that I’ll try to think up some tests that seriously try to break the new behaviour, and I want to update a patch I have for PyObjC to make use of the new functionality to make sure that the PEP actually fixes the issues I had w.r.t. builtin.super’s behavior.
What is the best way forward after that? As before this is a change in behavior that, unsurprisingly, few core devs appear to be comfortable with evaluating, combined with new functionality that will likely see little use beyond PyObjC (although my opinions of that shouldn’t carry much weight, I thought that decorators would have limited appeal when those where introduced and couldn’t have been more wrong about that).
Ronald
P.S. The PEP itself: <https://www.python.org/dev/peps/pep-0447>
Hello,
This is my first post on python-dev and I hope that I am not breaking any
rule.
I wanted to react on the discussion regarding PEP487.
This year, we have been working on a refactoring of the `traitlets`
library, an implementation of the descriptor pattern that is used in
Project Jupyter / IPython. The motivations for the refactoring was similar
to those of this PEP: having a more generic metaclass allowing more
flexibility in terms of types of descriptors, in order to avoid conflicts
between meta classes.
We ended up with:
- A metaclass called MetaHasDescriptor
- A base class of meta MetaHasDescriptor named HasDescriptors
Usage:
class MyClass(HasDescriptors):
attr = DesType()
DesType inherits from a base Descriptor type. The key is that their
initialization is done in three stages
- the main
DesType.__init__
- the part of the initialization of DesType that depends on the definition
of MyClass
DesType.class_init(self, cls, name)
which is called from MetaHasDescriptors.__new__
- a method of DesType that depends on the definition of instances of
MyClass
DesType.instance_init(self, obj)
which is called from HasDescriptors.__new__.
instance_init, may make modifications on the HasDescriptors instance.
My understanding is that the proposed __set_name__ in PEP487 exactly
corresponds to our class_init, although interestingly we often do much more
in class_init than setting the name of the descriptor, such as setting a
this_class attribute or calling class_init on contained descriptors.
Therefore I do not think that the names __set_name__ or __set_owner__ are
appropriate for this use case.
In a way, the long-form explicit names for our class_init and instance_init
methods would be something like __init_fom_owner_class__, and
__touch_instance__.
Thanks,
Sylvain
PS: thanks to Neil Girdhar for the heads up on the traitlets repo.
I have started [1] writing documentation for the new PEP 495 (Local
Time Disambiguation) features and ran into the following problem. The
current documentation is rather inconsistent in presenting the method
signatures. For example:
date.replace(year, month, day) [2], but
datetime.replace([year[, month[, day[, hour[, minute[, second[,
microsecond[, tzinfo]]]]]]]]) [3].
The new signature for datetime.replace in the Python implementation is
def replace(self, hour=None, minute=None, second=None, microsecond=None,
tzinfo=True, *, fold=None):
but the C implementation does not accept True for tzinfo or None for
the other arguments. The defaults in the Python implementation are
really just sentinels to detect which arguments are not provided.
How should I present the signature of the new replace method in the
documentation?
[1]: http://bugs.python.org/issue27595
[2]: https://docs.python.org/3/library/datetime.html#datetime.date.replace
[3]: https://docs.python.org/3/library/datetime.html#datetime.datetime.replace
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(a)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.
