Have inspect.getdoc follow the MRO when a method docstring is only one line.
Personne n'a encore pris cette issue.
- Langage dominant
- Python
- Étoiles
- 77.2k
- Forks
- 36k
- Métriques de merge des PR
- Métriques de PR en attente
Description
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.
Guide de contribution
Ouvrir le guide de contribution
Par où commencer
- Lisez l'issue en entier, puis le guide de contribution du projet.
- Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
- Forkez le dépôt et travaillez sur une branche.
- Ouvrez une pull request qui référence le numéro de l'issue.
Piste de recherche
Commencez par le point d’entrée inspect.getdoc et les exemples proposés dans l’issue. Déterminez comment la recherche récursive de MRO doit gérer les docstrings sur une seule ligne et le texte dupliqué, puis vérifiez que la documentation résultante conserve la forme développée souhaitée sans lignes répétées.
Rédigé par le modèle d'indexation à partir du texte de l'issue.
Évaluation
- Stack technique
- python
- Domaine
- tooling
- Type d'issue
- Fonctionnalité
- Difficulté
- 5/5
- Temps estimé
- Plus d'une semaine
- Activité
- À l'abandon
- Clarté
- Plutôt claire
- Accessibilité débutants
- 35/100