classification
Title: Incorrect documentation for PyMapping_Items and like
Type: behavior Stage:
Components: Documentation Versions: Python 3.6, Python 3.5
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: orsenthil Nosy List: docs@python, martin.panter, mine0901, orsenthil, python-dev, r.david.murray, serhiy.storchaka
Priority: normal Keywords: patch

Created on 2015-12-19 11:38 by serhiy.storchaka, last changed 2016-09-26 17:54 by python-dev. This issue is now closed.

Files
File name Uploaded Description Edit
bug.patch mine0901, 2015-12-20 15:12 edited document review
bug.patch mine0901, 2016-01-02 07:40 review
Messages (10)
msg256727 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2015-12-19 11:38
The documentation and comments for PyMapping_Items, PyMapping_Keys and PyMapping_Values are not correct about return type.

The documentation says that return type is a list. For example for PyMapping_Items:

   On success, return a list of the items in object *o*, where each item is a tuple
   containing a key-value pair.  On failure, return *NULL*. This is equivalent to
   the Python expression ``list(o.items())``.

The comment in Include/abstract.h is more correct, it mentions tuple:

     On success, return a list or tuple of the items in object o,
     where each item is a tuple containing a key-value pair.
     On failure, return NULL.

Actually PyMapping_Items in 3.x can return a list, a tuple, or a dict view (for dict).

The same for PyMapping_Keys and PyMapping_Values.
msg256765 - (view) Author: Sonali Gupta (mine0901) * Date: 2015-12-20 15:12
The documentation now says that On success, return a list, a tuple or a dictionary view for PyMapping_Items, PyMapping_Values and PyMapping_Keys.
msg256768 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2015-12-20 16:03
> This is equivalent to the Python expression ``list(o.keys())``.

This sentence is not correct.

And comments in Include/abstract.h are not absolutely correct too.
msg256779 - (view) Author: Sonali Gupta (mine0901) * Date: 2015-12-20 18:54
Should the sentence be removed completely?
> This is equivalent to the Python expression ``list(o.keys())``.

comments in Include/abstract.h are not absolutely correct too so should dictionary view be included in the return of PyMapping_Values, PyMapping_Keys and PyMapping_Items ??
msg256962 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2015-12-24 13:15
Yes, the documentation and comments (and all other mentions if exist) should be corrected.

We can also consider the option to change current behavior, since it is already differ from 2.x, but this is other issue.
msg257332 - (view) Author: Sonali Gupta (mine0901) * Date: 2016-01-02 07:40
The documentation in mapping.rst and the comments in abstract.h have been changed for PyMapping_Items, PyMapping_Keys and PyMapping_Values.
msg258761 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2016-01-21 17:38
New changeset e57949f5d0a9 by Senthil Kumaran in branch '3.5':
issue25909 - Correct the documentation of PyMapping_Items, PyMapping_Keys and
https://hg.python.org/cpython/rev/e57949f5d0a9

New changeset 739e1b0032c6 by Senthil Kumaran in branch 'default':
merge from 3.5
https://hg.python.org/cpython/rev/739e1b0032c6
msg258763 - (view) Author: Senthil Kumaran (orsenthil) * (Python committer) Date: 2016-01-21 17:41
Thanks for the patch. I had to do some minor clarification like mention view types apply only to dict and also remove the sentence which mentioned those equivalent to list(o.values()) and list(o.items()) in the patch.

With those fixed, I have commited the change.
msg277437 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2016-09-26 17:50
Seems I was wrong. PyDict_Keys/PyDict_Values/PyDict_Items return a list in Python 3. Thus comments in Include/abstract.h were correct. Xiang Zhang noticed this in issue28211.
msg277439 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2016-09-26 17:54
New changeset 68fc808bed9f by Serhiy Storchaka in branch '3.5':
Issues #25909, #28211: Restored correct documentation of PyMapping_Items,
https://hg.python.org/cpython/rev/68fc808bed9f

New changeset 21336392a680 by Serhiy Storchaka in branch '3.6':
Issues #25909, #28211: Restored correct documentation of PyMapping_Items,
https://hg.python.org/cpython/rev/21336392a680

New changeset 1229de1ab5c8 by Serhiy Storchaka in branch 'default':
Issues #25909, #28211: Restored correct documentation of PyMapping_Items,
https://hg.python.org/cpython/rev/1229de1ab5c8
History
Date User Action Args
2016-09-26 17:54:51python-devsetmessages: + msg277439
2016-09-26 17:50:18serhiy.storchakasetmessages: + msg277437
2016-01-21 17:41:42orsenthilsetstatus: open -> closed

nosy: + orsenthil
messages: + msg258763

assignee: docs@python -> orsenthil
resolution: fixed
2016-01-21 17:38:40python-devsetnosy: + python-dev
messages: + msg258761
2016-01-02 07:40:52mine0901setfiles: + bug.patch

messages: + msg257332
2015-12-24 13:15:59serhiy.storchakasetmessages: + msg256962
2015-12-20 18:54:35mine0901setmessages: + msg256779
2015-12-20 16:03:25serhiy.storchakasetmessages: + msg256768
2015-12-20 15:57:54serhiy.storchakasetnosy: + r.david.murray, martin.panter
2015-12-20 15:12:56mine0901setfiles: + bug.patch

nosy: + mine0901
messages: + msg256765

keywords: + patch
2015-12-19 11:38:05serhiy.storchakacreate