classification
Title: Pydoc to list data descriptors in _fields order if it exists
Type: enhancement Stage: resolved
Components: Library (Lib) Versions: Python 3.6
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: rhettinger Nosy List: python-dev, r.david.murray, rhettinger, yselivanov
Priority: normal Keywords: patch

Created on 2015-08-17 05:33 by rhettinger, last changed 2015-08-19 05:26 by rhettinger. This issue is now closed.

Files
File name Uploaded Description Edit
pydoc.diff rhettinger, 2015-08-17 06:27 Rough draft patch review
pydoc2.diff rhettinger, 2015-08-18 18:28 Updated patch with tests review
Messages (7)
msg248714 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2015-08-17 05:33
Currently, help() lists out data descriptors in alphabetical order.  This is fine in the general case, however if the fields are parts of a named tuple, it is more sensible to list them in the order found in the tuple.

The presence of a named tuple can be detected by the presence of a _fields attribute that is a list of strings.  That strings can be used as a primary sort key before an alphabetical sort of anything not listed in _fields.

>>> Person = namedtuple('Person', ['nickname', 'firstname', 'age'])
>>> help(Person)
Help on class Person in module __main__:

class Person(builtins.tuple)
 |  Person(nickname, firstname, age)
 |  
 ...
 |  
 |  ----------------------------------------------------------------------
 |  Static methods defined here:
 |  
 |  __new__(_cls, nickname, firstname, age)
 |      Create new instance of Person(nickname, firstname, age)
 |  
 |  ----------------------------------------------------------------------
 |  Data descriptors defined here:
 |  
 |  __dict__
 |      A new OrderedDict mapping field names to their values
 |  
 |  age
 |      Alias for field number 2
 |  
 |  firstname
 |      Alias for field number 1
 |  
 |  nickname
 |      Alias for field number 0
 |  
 |  ----------------------------------------------------------------------
 |  Data and other attributes defined here:
 |  
 |  _fields = ('nickname', 'firstname', 'age')
 |  
 ...

The data descriptors should list nickname, then firstname, then age to match the tuple order in _fields.
msg248718 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2015-08-17 06:44
With the attached patch, the new output is:

 |  ----------------------------------------------------------------------
 |  Data descriptors defined here:
 |  
 |  nickname
 |      Alias for field number 0
 |   
 |  firstname
 |      Alias for field number 1 
 | 
 |  age
 |      Alias for field number 2
 | 
 |  __dict__
 |      A new OrderedDict mapping field names to their values
msg248745 - (view) Author: Yury Selivanov (yselivanov) * (Python committer) Date: 2015-08-17 18:44
Can this be enabled only for namedtuples?  Otherwise this might be a backwards incompatible change, for example:

  class Foo:
    '''spam'''
    _fields = None
msg248751 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2015-08-18 01:59
Named tuples are not a type, they are a protocol.  Guido has agreed that checking for _fields is an acceptable and preferred way of finding out whether something is a namedtuple.    I can add a check to at least check the value of _fields is an iterable of strings.  If it still aliases with some random use of _fields, the only consequence is that the matching field names will appear in a different order.
msg248756 - (view) Author: Yury Selivanov (yselivanov) * (Python committer) Date: 2015-08-18 03:29
> Named tuples are not a type, they are a protocol.  Guido has agreed that checking for _fields is an acceptable and preferred way of finding out whether something is a namedtuple.

They are, but for protocols we usually use dunder names.  "_fields" is a common enough attribute name for all kinds of objects, not necessarily namedtuples.

Can we at least check if the class is a tuple subclass and then use its '_fields' for sorting?

> I can add a check to at least check the value of _fields is an iterable of strings.  If it still aliases with some random use of _fields, the only consequence is that the matching field names will appear in a different order.

+1 for checking if it's an iterable of strings.
msg248772 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2015-08-18 13:40
No, protocols and duck typing do not always use dunder names.  In fact checking for dunder names explicitly is probably the less common of the two cases.  (We are talking about "protocol" here in a generic sense, not the restricted set of those that include dunder methods.)
msg248817 - (view) Author: Roundup Robot (python-dev) Date: 2015-08-19 05:25
New changeset f5c40ab9e233 by Raymond Hettinger in branch 'default':
Issue #24879:  Teach pydoc to display named tuple fields in the order they were defined.
https://hg.python.org/cpython/rev/f5c40ab9e233
History
Date User Action Args
2015-08-19 05:26:24rhettingersetstatus: open -> closed
resolution: fixed
stage: patch review -> resolved
2015-08-19 05:25:31python-devsetnosy: + python-dev
messages: + msg248817
2015-08-18 18:28:29rhettingersetfiles: + pydoc2.diff
2015-08-18 13:40:55r.david.murraysetnosy: + r.david.murray
messages: + msg248772
2015-08-18 03:29:41yselivanovsetmessages: + msg248756
2015-08-18 01:59:54rhettingersetmessages: + msg248751
2015-08-17 18:44:38yselivanovsetnosy: + yselivanov
messages: + msg248745
2015-08-17 06:44:39rhettingersetmessages: + msg248718
2015-08-17 06:28:06rhettingersetassignee: rhettinger
stage: patch review
2015-08-17 06:27:50rhettingersetfiles: + pydoc.diff
keywords: + patch
2015-08-17 05:33:10rhettingercreate