Text of peps.python.org › pep-0469 as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

PEP 469 – Migration of dict iteration code to Python 3 | peps.python.org

PEP 469 – Migration of dict iteration code to Python 3 PEP 469 – Migration of dict iteration code to Python 3 Author : Alyssa Coghlan <ncoghlan at gmail.com> Status : Withdrawn Type : Standards Track Created : 18-Apr-2014 Python-Version : 3.5 Post-History : 18-Apr-2014, 21-Apr-2014 Table of Contents Abstract PEP Withdrawal Mapping iteration models Lists as mutable snapshots Iterator objects Set based dynamic views Migrating directly to Python 3 Migrating to the common subset of Python 2 and 3 Migrating from Python 3 to the common subset with Python 2.7 Possible changes to Python 3.5+ Discussion Acknowledgements Copyright Abstract For Python 3, PEP 3106 changed the design of the dict builtin and the mapping API in general to replace the separate list based and iterator based APIs in Python 2 with a merged, memory efficient set and multiset view based API.

This new style of dict iteration was also added to the Python 2.7 dict type as a new set of iteration methods. This means that there are now 3 different kinds of dict iteration that may need to be migrated to Python 3 when an application makes the transition: Lists as mutable snapshots: d.items() -> list(d.items()) Iterator objects: d.iteritems() -> iter(d.items()) Set based dynamic views: d.viewitems() -> d.items() There is currently no widely agreed best practice on how to reliably convert all Python 2 dict iteration code to the common subset of Python 2 and 3, especially when test coverage of the ported code is limited.

This PEP reviews the various ways the Python 2 iteration APIs may be accessed, and looks at the available options for migrating that code to Python 3 by way of the common subset of Python 2.6+ and Python 3.0+. The PEP also considers the question of whether or not there are any additions that may be worth making to Python 3.5 that may ease the transition process for application code that doesn’t need to worry about supporting earlier versions when eventually making the leap to Python 3.

PEP Withdrawal In writing the second draft of this PEP, I came to the conclusion that the readability of hybrid Python 2/3 mapping code can actually be best enhanced by better helper functions rather than by making changes to Python 3.5+. The main value I now see in this PEP is as a clear record of the recommended approaches to migrating mapping iteration code from Python 2 to Python 3, as well as suggesting ways to keep things readable and maintainable when writing hybrid code that supports both versions.

Notably, I recommend that hybrid code avoid calling mapping iteration methods directly, and instead rely on builtin functions where possible, and some additional helper functions for cases that would be a simple combination of a builtin and a mapping method in pure Python 3 code, but need to be handled slightly differently to get the exact same semantics in Python 2. Static code checkers like pylint could potentially be extended with an optional warning regarding direct use of the mapping iteration methods in a hybrid code base.

Mapping iteration models Python 2.7 provides three different sets of methods to extract the keys, values and items from a dict instance, accounting for 9 out of the 18 public methods of the dict type. In Python 3, this has been rationalised to just 3 out of 11 public methods (as the has_key method has also been removed). Lists as mutable snapshots This is the oldest of the three styles of dict iteration, and hence the one implemented by the d.keys() , d.values() and d.items() methods in Python 2.

These methods all return lists that are snapshots of the state of the mapping at the time the method was called. This has a few consequences: the original object can be mutated freely without affecting iteration over the snapshot the snapshot can be modified independently of the original object the snapshot consumes memory proportional to the size of the original mapping The semantic equivalent of these operations in Python 3 are list(d.keys()) , list(d.values()) and list(d.iteritems()) .

Iterator objects In Python 2.2, dict objects gained support for the then-new iterator protocol, allowing direct iteration over the keys stored in the dictionary, thus avoiding the need to build a list just to iterate over the dictionary contents one entry at a time. iter(d) provides direct access to the iterator object for the keys. Python 2 also provides a d.iterkeys() method that is essentially synonymous with iter(d) , along with d.itervalues() and d.iteritems() methods.

These iterators provide live views of the underlying object, and hence may fail if the set of keys in the underlying object is changed during iteration: >>> d = dict ( a = 1 ) >>> for k in d : ... del d [ k ] ... Traceback (most recent call last): File "<stdin>" , line 1 , in <module> RuntimeError : dictionary changed size during iteration As iterators, iteration over these objects is also a one-time operation: once the iterator is exhausted, you have to go back to the original mapping in order to iterate again.

In Python 3, direct iteration over mappings works the same way as it does in Python 2. There are no method based equivalents - the semantic equivalents of d.itervalues() and d.iteritems() in Python 3 are iter(d.values()) and iter(d.items()) . The six and future.utils compatibility modules also both provide iterkeys() , itervalues() and iteritems() helper functions that provide efficient iterator semantics in both Python 2 and 3.

Set based dynamic views The model that is provided in Python 3 as a method based API is that of set based dynamic views (technically multisets in the case of the values() view). In Python 3, the objects returned by d.keys() , d.values() and d. items() provide a live view of the current state of the underlying object, rather than taking a full snapshot of the current state as they did in Python 2. This change is safe in many circumstances, but does mean that, as with the direct iteration API, it is necessary to avoid adding or removing keys during iteration, in order to avoid encountering the following error: >>> d = dict ( a = 1 ) >>> for k , v in d . items (): ... del d [ k ] ...

Traceback (most recent call last): File "<stdin>" , line 1 , in <module> RuntimeError : dictionary changed size during iteration Unlike the iteration API, these objects are iterables, rather than iterators: you can iterate over them multiple times, and each time they will iterate over the entire underlying mapping. These semantics are also available in Python 2.7 as the d.viewkeys() , d.viewvalues() and d.viewitems() methods.

The future.utils compatibility module also provides viewkeys() , viewvalues() and viewitems() helper functions when running on Python 2.7 or Python 3.x. Migrating directly to Python 3 The 2to3 migration tool handles direct migrations to Python 3 in accordance with the semantic equivalents described above: d.keys() -> list(d.keys()) d.values() -> list(d.values()) d.items() -> list(d.items()) d.iterkeys() -> iter(d.keys()) d.itervalues() -> iter(d.values()) d.iteritems() -> iter(d.items()) d.viewkeys() -> d.keys() d.viewvalues() -> d.values() d.viewitems() -> d.items() Rather than 9 distinct mapping methods for iteration, there are now only the 3 view methods, which combine in straightforward ways with the two relevant builtin functions to cover all of the behaviours that are available as dict methods in Python 2.7.

Note that in many cases d.keys() can be replaced by just d , but the 2to3 migration tool doesn’t attempt that replacement. The 2to3 migration tool also does not provide any automatic assistance for migrating references to these objects as bound or unbound methods - it only automates conversions where the API is called immediately. Migrating to the common subset of Python 2 and 3 When migrating to the common subset of Python 2 and 3, the above transformations are not generally appropriate, as they all either result in the creation of a redundant list in Python 2, have unexpected

The rest of this page is on the live site.