Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Pydoc to list data descriptors in _fields order if it exists #69067

Closed
rhettinger opened this issue Aug 17, 2015 · 7 comments
Closed

Pydoc to list data descriptors in _fields order if it exists #69067

rhettinger opened this issue Aug 17, 2015 · 7 comments
Assignees
Labels
stdlib Python modules in the Lib dir type-feature A feature request or enhancement

Comments

@rhettinger
Copy link
Contributor

rhettinger commented Aug 17, 2015

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
    Copy link
    Contributor Author

    rhettinger commented Aug 17, 2015

    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 rhettinger added stdlib Python modules in the Lib dir type-feature A feature request or enhancement labels Aug 17, 2015
    @rhettinger rhettinger self-assigned this Aug 17, 2015
    @rhettinger
    Copy link
    Contributor Author

    rhettinger commented Aug 17, 2015

    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
    Copy link
    Member

    1st1 commented Aug 17, 2015

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

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

    @rhettinger
    Copy link
    Contributor Author

    rhettinger commented Aug 18, 2015

    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
    Copy link
    Member

    1st1 commented Aug 18, 2015

    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
    Copy link
    Member

    bitdancer commented Aug 18, 2015

    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
    Copy link
    Mannequin

    python-dev mannequin commented Aug 19, 2015

    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

    @ezio-melotti ezio-melotti transferred this issue from another repository Apr 10, 2022
    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
    Labels
    stdlib Python modules in the Lib dir type-feature A feature request or enhancement
    Projects
    None yet
    Development

    No branches or pull requests

    3 participants