Pydoc to list data descriptors in _fields order if it exists

[rhettinger]

BPO	24879
Nosy	@rhettinger, @bitdancer, @1st1
Files	pydoc.diff: Rough draft patch pydoc2.diff: Updated patch with tests

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/rhettinger'
closed_at = <Date 2015-08-19.05:26:24.790>
created_at = <Date 2015-08-17.05:33:10.407>
labels = ['type-feature', 'library']
title = 'Pydoc to list data descriptors in _fields order if it exists'
updated_at = <Date 2015-08-19.05:26:24.789>
user = 'https://github.com/rhettinger'

bugs.python.org fields:

activity = <Date 2015-08-19.05:26:24.789>
actor = 'rhettinger'
assignee = 'rhettinger'
closed = True
closed_date = <Date 2015-08-19.05:26:24.790>
closer = 'rhettinger'
components = ['Library (Lib)']
creation = <Date 2015-08-17.05:33:10.407>
creator = 'rhettinger'
dependencies = []
files = ['40194', '40203']
hgrepos = []
issue_num = 24879
keywords = ['patch']
message_count = 7.0
messages = ['248714', '248718', '248745', '248751', '248756', '248772', '248817']
nosy_count = 4.0
nosy_names = ['rhettinger', 'r.david.murray', 'python-dev', 'yselivanov']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue24879'
versions = ['Python 3.6']

[rhettinger]

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.

[rhettinger]

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

[1st1]

Can this be enabled only for namedtuples? Otherwise this might be a backwards incompatible change, for example:

  class Foo:
    '''spam'''
    _fields = None

[rhettinger]

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.

[1st1]

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.

[bitdancer]

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.)

[python-dev]

New changeset f5c40ab9e233 by Raymond Hettinger in branch 'default':
Issue bpo-24879: Teach pydoc to display named tuple fields in the order they were defined.
https://hg.python.org/cpython/rev/f5c40ab9e233