Issue 30959: Constructor signature is duplicated in the help of namedtuples (original) (raw)

Issue30959

Created on 2017-07-18 11:04 by serhiy.storchaka, last changed 2022-04-11 14:58 by admin.

| Messages (3) | | | | | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------ | | ---------------------------- | | msg298582 - (view) | Author: Serhiy Storchaka (serhiy.storchaka) * | Date: 2017-07-18 11:04 | | | | The docstring of namedtuple class starts with the signature of the constructor. But pydoc now outputs the signature of the constructor for classes (see ). As a result, the signature is duplicated in the output. For example: $ ./python -m pydoc functools._CacheInfo Help on class CacheInfo in functools: functools._CacheInfo = class CacheInfo(builtins.tuple) | functools._CacheInfo(hits, misses, maxsize, currsize) | | CacheInfo(hits, misses, maxsize, currsize) | | Method resolution order: ... | | msg298766 - (view) | Author: Raymond Hettinger (rhettinger) * | Date: 2017-07-21 03:52 | | | | Pydoc isn't the only tool for looking at docstrings. I'm worried that you're systematically killing-off useful docstrings because of a world view that all tools will use pydoc and signatures. As a result, IDLE's tooltips are now useless (this comes up every single day when I teach python courses). BPython is thrown-off, etc. Here's one of many problem examples of the docstring losing information: Python 3.4.4 (v3.4.4:737efcadf5a6, Dec 19 2015, 20:38:52) [GCC 4.2.1 (Apple Inc. build 5666) (dot 3)] on darwin Type "help", "copyright", "credits" or "license" for more information. >>> print(sorted.__doc__) sorted(iterable, key=None, reverse=False) --> new sorted list >>> print(sorted.__doc__) Return a new list containing all items from the iterable in ascending order. A custom key function can be supplied to customize the sort order, and the reverse flag can be set to request the result in descending order. | | | | | | msg298784 - (view) | Author: SylvainDe (SylvainDe) * | Date: 2017-07-21 08:54 | | | | Regarding the `sorted.__doc__` issue, it seems like the signature does not appear in the `__doc__` member but it does appear when using `help(sorted)` which is probably what really matters. In any case, I find PEP 257 about this part a bit ambiguous : "The one-line docstring should NOT be a "signature"". Even though is should not be JUST a signature, should it CONTAIN the signature ? | | | | |