Have inspect.getdoc follow the MRO when a method docstring is only one line.
Nessuno ha ancora preso questa issue.
- Lingua principale
- Python
- Stelle
- 77.2k
- Fork
- 36k
- Metriche di merge delle PR
- Metriche PR in attesa
Descrizione
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.
Guida per i contributori
Apri la guida per i contributori
Come iniziare
- Leggi tutta la issue e poi la guida ai contributi del progetto.
- Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
- Fai un fork del repository e lavora su un branch.
- Apri una pull request che faccia riferimento al numero della issue.
Direzione di ricerca
Inizia dal punto di ingresso inspect.getdoc e dagli esempi proposti nell’issue. Determina come la ricerca ricorsiva di MRO debba gestire le docstring su una sola riga e il testo duplicato, quindi verifica che la documentazione risultante mantenga la forma espansa desiderata senza righe ripetute.
Scritto dal modello di indicizzazione a partire dal testo della issue.
Valutazione
- Stack tecnologico
- python
- Ambito
- tooling
- Tipo di issue
- Funzionalità
- Difficoltà
- 5/5
- Tempo stimato
- Più di una settimana
- Stato di attività
- Ferma
- Chiarezza
- Abbastanza chiara
- Idoneità per principianti
- 35/100