bpo-30662: fixed OrderedDict.__init__ docstring re PEP 468 #2179
Conversation
|
@jonathaneunice, thanks for your PR! By analyzing the history of the files in this pull request, we identified @rhettinger, @serhiy-storchaka and @tiran to be potential reviewers. |
|
Would be happy with it simply saying "Initialize an ordered dictionary. The signature is the same as regular dictionaries." I.e., just truncating it so not actively wrong wrt PEP 468. But it's a big change in semantic guarantees, so a bit more explantation might be warranted. Pending further review, have tightened comment wording and made sure the C implementation has an equivalent comment. (Thanks to Serhiy Storchaka suggestion on bugs.python.org) |
|
Have just reviewed the collections docs ( |
Lib/collections/__init__.py
Outdated
| regular dictionaries, but keyword arguments are not recommended because | ||
| their insertion order is arbitrary. | ||
|
|
||
| regular dictionaries. As of Python 3.6, keyword argument insertion |
There was a problem hiding this comment.
There should be an extra whitespace aftere the period.
Lib/collections/__init__.py
Outdated
| their insertion order is arbitrary. | ||
|
|
||
| regular dictionaries. As of Python 3.6, keyword argument insertion | ||
| order is stable. (PEP 468) |
There was a problem hiding this comment.
IMHO preserved is more meaningful than stable.
Objects/odictobject.c
Outdated
| @@ -882,8 +882,8 @@ odict_eq(PyObject *a, PyObject *b) | |||
|
|
|||
| PyDoc_STRVAR(odict_init__doc__, | |||
| "Initialize an ordered dictionary. The signature is the same as\n\ | |||
| regular dictionaries, but keyword arguments are not recommended because\n\ | |||
| their insertion order is arbitrary.\n\ | |||
| regular dictionaries. As of Python 3.6, keyword argument insertion\n\ | |||
There was a problem hiding this comment.
The same as in the previous comment: extra whitespace after period, preserved instead of stable.
There was a problem hiding this comment.
@marco-buttu Thank you. Wording and post-period spacing updated.
Lib/collections/__init__.py
Outdated
| regular dictionaries, but keyword arguments are not recommended because | ||
| their insertion order is arbitrary. | ||
|
|
||
| regular dictionaries. As of Python 3.6, keyword argument insertion |
There was a problem hiding this comment.
Don't mention Python 3.6 or PEP 468 as that's the past and just how things are in Python 3.7 which this docstring is for. Same goes for the other docstring change.
There was a problem hiding this comment.
Should I mention that keyword order is preserved? Or just drop that altogether and fall back to the compatibility claim alone?
There was a problem hiding this comment.
How about something like "regular dictionaries. Keyword argument order is preserved."
There was a problem hiding this comment.
@ericsnowcurrently Agreed. That's exactly the current proposal.
Lib/collections/__init__.py
Outdated
| regular dictionaries, but keyword arguments are not recommended because | ||
| their insertion order is arbitrary. | ||
|
|
||
| regular dictionaries. As of Python 3.6, keyword argument insertion |
There was a problem hiding this comment.
@ericsnowcurrently Agreed. That's exactly the current proposal.
…honGH-2179) * fixed OrderedDict.__init__ docstring re PEP 468 * tightened comment and mirrored to C impl * added space after period per marco-buttu * preserved substituted for stable * drop references to Python 3.6 and PEP 468 (cherry picked from commit faa57cb)
|
GH-3370 is a backport of this pull request to the 3.6 branch. |
* fixed OrderedDict.__init__ docstring re PEP 468 * tightened comment and mirrored to C impl * added space after period per marco-buttu * preserved substituted for stable * drop references to Python 3.6 and PEP 468
As of Python 3.6, PEP 468 indicates that kwarg order is no longer arbitrary, but stable wrt to the order of args stated in source code. OrderedDict's docstring should be clear about that, not describe the situation that obtained in Python 3.5 and prior.