[Python-checkins] peps: PEP 509: don't require to always increase the version

Wed Apr 20 19:42:57 EDT 2016

https://hg.python.org/peps/rev/16393fc7e31a
changeset: 6290:16393fc7e31a
user: Victor Stinner <victor.stinner at gmail.com>
date: Thu Apr 21 01:15:25 2016 +0200
summary:
 PEP 509: don't require to always increase the version
Don't require to increase the dict version if the dictionary content does not
change. Leave this choice to the Python implementation.
files:
 pep-0509.txt | 64 ++++++++++++++++++++++++++++-----------
 1 files changed, 45 insertions(+), 19 deletions(-)

diff --git a/pep-0509.txt b/pep-0509.txt
--- a/pep-0509.txt
+++ b/pep-0509.txt
@@ -180,21 +180,52 @@
 
 Add a ``ma_version_tag`` field to the ``PyDictObject`` structure with
 the C type ``PY_UINT64_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:
+dictionary version.
 
-* ``clear()`` if the dict is non-empty
-* ``pop(key)`` if the key exists
-* ``popitem()`` if the dict is non-empty
-* ``setdefault(key, value)`` if the key does not exist
-* ``__delitem__(key)`` if the key exists
-* ``__setitem__(key, value)`` always increases the version
-* ``update(...)`` if called with arguments
+Each time a dictionary is created, the global version is incremented and
+the dictionary version is initialized to the global version.
+
+Each time the dictionary content is modified, the global version must be
+incremented and copied to the dictionary version. Dictionary methods
+which can modify its content:
+
+* ``clear()``
+* ``pop(key)``
+* ``popitem()``
+* ``setdefault(key, value)``
+* ``__delitem__(key)``
+* ``__setitem__(key, value)``
+* ``update(...)``
+
+The choice of increasing or not the version when a dictionary method
+does not change its content is left to the Python implementation. A
+Python implementation can decide to not increase the version to avoid
+dictionary lookups in guards. Examples of cases when dictionary methods
+don't modify its content:
+
+* ``clear()`` if the dict is already empty
+* ``pop(key)`` if the key does not exist
+* ``popitem()`` if the dict is empty
+* ``setdefault(key, value)`` if the key already exists
+* ``__delitem__(key)`` if the key does not exist
+* ``__setitem__(key, value)`` if the new value is identical to the
+ current value
+* ``update()`` if called without argument or if new values are identical
+ to current values
+
+Setting a key to a new value equals to the old value is also considered
+as an operation modifying the dictionary content.
+
+Two different empty dictionaries must have a different version to be
+able to identify a dictionary just by its version. It allows to verify
+in a guard that a namespace was not replaced without storing a strong
+reference to the dictionary. Using a borrowed reference does not work:
+if the old dictionary is destroyed, it is possible that a new dictionary
+is allocated at the same memory address. By the way, dictionaries don't
+support weak references.
 
 The version increase must be atomic. In CPython, the Global Interpreter
-Lock (GIL) already protects ``dict`` methods to make them atomic.
+Lock (GIL) already protects ``dict`` methods to make changes atomic.
 
 Example using an hypothetical ``dict_get_version(dict)`` function::
 
@@ -211,15 +242,10 @@
 >>> dict_get_version(d)
 103
 
-``dict.__setitem__(key, value)`` and ``dict.update(...)`` always
-increase the version, even if the new value is identical or is equal to
-the current value (even if ``(dict[key] is value) or (dict[key] ==
-value)``).
-
 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 is wrong most of the time after an
-integer overflow.
+than ``version <= old_version`` which becomes wrong after an integer
+overflow.
 
 
 Backwards Compatibility
-- 
Repository URL: https://hg.python.org/peps
