bpo-36059: Update OrderedDict() docs to reflect that regular dicts are now ordered #11966
Conversation
rhettinger
added
docs
| return self.__class__, (OrderedDict(self),) | ||
| def __getitem__(self, key): | ||
| value = super().__getitem__(key) | ||
| self.move_to_end(key) |
There was a problem hiding this comment.
Yes. Thanks for noticing.
| super().__setitem__(key, value) | ||
| if len(self) > self.maxsize: | ||
| oldest = next(iter(self)) | ||
| del self[oldest] |
There was a problem hiding this comment.
It's a bummer but that actually doesn't work in this example. Unfortunately, popitem() calls the overridden _getitem_() method which moves the value.
Doc/library/collections.rst
Outdated
| * A regular :class:`dict` was designed to be very good at mapping | ||
| operations. Tracking insertion order was secondary. In contrast, | ||
| :class:`OrderedDict` was designed to be good at reordering operations. | ||
| Efficient mapping operations were secondary. |
There was a problem hiding this comment.
This is misleading. Mapping in OrderedDict is so effective as in dict. Only mutating operations (and maybe iteration) can be slower.
There was a problem hiding this comment.
Okay. I'll add a clarification.
Doc/library/collections.rst
Outdated
| the equality operation for :class:`dict` only requires equal contents | ||
| regardless of order. | ||
|
|
||
| * The :class:`OrderedDict` class has a :meth:`popitem` method that accepts an |
There was a problem hiding this comment.
The dict class also has a popitem method. Maybe reword this entry as "The popitem method of the OrderedDict class accepts ..."?
|
I would make descriptions of differences between OrderedDict and dict more brief. More details can be added below, in the main text or in FAQ. For example, keep just "Equality tests between :class: |
|
I prefer having the bullet points up front. Once dicts became ordered, the top documentation question about OrderedDict has become, "how is its API and performance" different from a regular dict that remembers insertion order. In particular, there are now two central questions to be answered 1) what are the implications from substituting a regular dict for an OrderedDict in existing code that uses an OrderedDict (this question has come up for core-devs several times), and 2) what capabilities does the OrderedDict have that justifies that it still exists. I would like to answer these up front and completely. The brief descriptions of what the methods do are in the regular class docs that follow. |
|
Thanks @rhettinger for the PR 🌮🎉.. I'm working now to backport this PR to: 3.7. |
|
GH-11972 is a backport of this pull request to the 3.7 branch. |
…e now ordered (pythonGH-11966) (cherry picked from commit 49fd6dd) Co-authored-by: Raymond Hettinger <rhettinger@users.noreply.github.com>
Describes the diminished significance of OrderedDict
Enumerate the differences with a regular dict (people need to know this in detail before migrating existing code from OrderedDict to regular dicts).
Remove examples that are no longer meaningful.
Update other examples and a new one
https://bugs.python.org/issue36059