search

python / cpython

The Python programming language
https://www.python.org
Other
62.59k stars 30.04k forks source link

help() is too noisy for types used like functions #89654

Open rhettinger opened 2 years ago

rhettinger commented 2 years ago
BPO 45491
Nosy @rhettinger

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: ```python assignee = None closed_at = None created_at = labels = ['type-feature', 'library', '3.11'] title = 'help() is too noisy for types used like functions' updated_at = user = 'https://github.com/rhettinger' ``` bugs.python.org fields: ```python activity = actor = 'rhettinger' assignee = 'none' closed = False closed_date = None closer = None components = ['Library (Lib)'] creation = creator = 'rhettinger' dependencies = [] files = [] hgrepos = [] issue_num = 45491 keywords = [] message_count = 1.0 messages = ['404050'] nosy_count = 1.0 nosy_names = ['rhettinger'] pr_nums = [] priority = 'normal' resolution = None stage = None status = 'open' superseder = None type = 'enhancement' url = 'https://bugs.python.org/issue45491' versions = ['Python 3.11'] ```

rhettinger commented 2 years ago

When someone requests help(range), help(zip), help(property), or help(classmethod), the expectation and need is to see something like what is shown in main documentation rather than being subjected to a listing of every standard dunder method.

It would be nice to have a way to mark types that are mostly used like functions so that help() output will be more focused and less noisy. Then help() can omit the Methods and Static methods sections. It would keep the section for non-standard descriptors such as start, stop, step, fget, fset, or fdel.

Alternatively, for all types, we can condense the Methods and Static Methods sections to just list the standard dunder methods rather that eating several rows of output per method.

vitrioil commented 2 years ago

This seems to be open. I would like to contribute to this.

While we are generating doc we could filter if __module__ is builtins for methods maybe? https://github.com/python/cpython/blob/36d42e701f8a4040e7daf70138217038bfde3c78/Lib/pydoc.py#L297-L306

This doesn't address marking types that are used as functions however. For that perhaps the class implementation will have to somehow inform that it doesn't want its standard dunder methods to be shown, maybe using a decorator?