diff --git a/pep-0372.txt b/pep-0372.txt index 7d1ac7fac..4bc43f10e 100644 --- a/pep-0372.txt +++ b/pep-0372.txt @@ -31,8 +31,8 @@ hard to use dictionaries as data storage for some specific use cases. Some dynamic programming languages like PHP and Ruby 1.9 guarantee a certain order on iteration. In those languages, and existing Python ordered-dict implementations, the ordering of items is defined by the -time of insertion of the key. New keys are appended at the end, keys -that are overwritten and not moved. +time of insertion of the key. New keys are appended at the end, but +keys that are overwritten are not moved to the end. The following example shows the behavior for simple assignments: @@ -67,6 +67,11 @@ situations: Django currently uses an ugly hack to restore the ordering of members in database models. +- The RawConfigParser class accepts a ``dict_type`` argument that + allows an application to set the type of dictionary used internally. + The motivation for this addition was expressly to allow users to + provide an ordered dictionary. [1]_ + - Code ported from other programming languages such as PHP often depends on a ordered dict. Having an implementation of an ordering-preserving dictionary in the standard library could ease @@ -106,34 +111,37 @@ pair was inserted: New methods not available on dict: - ``odict.byindex(index)`` +``odict.byindex(index)`` - Index-based lookup is supported by ``byindex()`` which returns - the key/value pair for an index, that is, the "position" of a - key in the ordered dict. 0 is the first key/value pair, -1 - the last. + Returns the key/value pair for an index, that is, the "position" of a key in + the ordered dict. 0 is the first key/value pair, -1 the last. - >>> d.byindex(2) - ('foo', 'bar') + >>> d.byindex(2) + ('foo', 'bar') - ``odict.sort(cmp=None, key=None, reverse=False)`` + If there is no key for index an `IndexError` is raised. - Sorts the odict in place by cmp or key. This works exactly - like ``list.sort()``, but the comparison functions are passed - a key/value tuple, not only the value. +``odict.index(key)`` - >>> d = odict([(42, 1), (1, 4), (23, 7)]) - >>> d.sort() - >>> d - collections.odict([(1, 4), (23, 7), (42, 1)]) + Returns the index of a key. If the key does not exist, a `ValueError` is + raised. - ``odict.reverse()`` +``odict.sort(cmp=None, key=None, reverse=False)`` - Reverses the odict in place. + Sorts the odict in place by cmp or key. This works exactly like + ``list.sort()``, but the comparison functions are passed a key/value tuple, + not only the value. - ``odict.__reverse__()`` + >>> d = odict([(42, 1), (1, 4), (23, 7)]) d.sort() d + collections.odict([(1, 4), (23, 7), (42, 1)]) - Supports reverse iteration by key. +``odict.reverse()`` + + Reverses the odict in place. + +``odict.__reverse__()`` + + Supports reverse iteration by key. Questions and Answers @@ -145,10 +153,10 @@ What happens if an existing key is reassigned? consistent with existing implementations and allows subclasses to change the behavior easily:: - class movingcollections.odict): + class moving_odict(collections.odict): def __setitem__(self, key, value): self.pop(key, None) - odict.__setitem__(self, key, value) + collections.odict.__setitem__(self, key, value) What happens if keys appear multiple times in the list passed to the constructor? @@ -217,6 +225,12 @@ could return odicts in the future that retain the attribute ordering of the source file. +References +========== + +.. [1] http://bugs.python.org/issue1371075 + + Copyright =========