python / python/cpython

Have inspect.getdoc follow the MRO when a method docstring is only one line.

Offen
#94,470 4 Kommentare 1 Reaktion 0 zugewiesene Personen Auf GitHub ansehen

Dieses Issue hat noch niemand übernommen.

stdlib type-feature
Vorherrschende Sprache
Python
Sterne
77.2k
Forks
36k
PR-Merge-Kennzahlen
PR-Kennzahlen ausstehend

Beschreibung

Feature or enhancement

"Hot" on the heels of 3.5ish's https://github.com/python/cpython/issues/59787 comes another idea: An age old pattern we have in our codebase is for people to put """See base class.""" as the docstring on methods to appease lint tooling demanding a docstring on non-trivial methods. As a consequence code written this way doesn't trigger the inspect.getdoc() feature from #59787 and the help() text in a Notebook for such functions is the content-free oneliner instead of heading up the MRO chain.

I propose a new feature: If the docstring for a method exists but is <= 1 line, follow the MRO as if there were no docstring and return

f"{onelinedoc}:\n{mro_doc}" as the docstring. Do this recursively, but collapse duplicate docstrings gathered along the way so that you could wind up with [good]:

"""See base class:
Fill a hovercraft with eels of the chosen species.

Args:
  species: A set of allowed Eel types.
  count: float, a non-negative number of eels to add. Fractions are allowed.
"""

rather than this degenerate pattern in deep heirarchies that could otherwise result [bad]:

"""See base class:
See base class:
See base class:
Fill a hovercraft with ...
"""

Collapsing identical docstrings along the heirarchy in this case also works for the situation where they're all the same cut and pasted oneliner and nothing else.

Beitragsleitfaden

Beitragsleitfaden öffnen

Erste Schritte

  1. Lies das ganze Issue und danach den Beitragsleitfaden des Projekts.
  2. Schreib ins Issue, dass du es übernimmst — das erspart doppelte Arbeit.
  3. Forke das Repository und arbeite in einem Branch.
  4. Öffne einen Pull Request, der die Issue-Nummer nennt.

Rechercherichtung

Beginnen Sie mit dem Einstiegspunkt inspect.getdoc und den vorgeschlagenen Beispielen des Issues. Ermitteln Sie, wie die rekursive MRO-Suche einzeilige Docstrings und doppelten Text behandeln soll, und überprüfen Sie anschließend, dass die resultierende Dokumentation die gewünschte erweiterte Form ohne wiederholte Zeilen beibehält.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Tech-Stack
python
Bereich
tooling
Issue-Typ
Feature
Schwierigkeit
5/5
Geschätzter Aufwand
Über eine Woche
Aktivitätsstatus
Veraltet
Klarheit
Größtenteils klar
Anfängerfreundlichkeit
35/100

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.