python / python/cpython

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

Ouverte
#94,470 4 commentaires 1 réaction 0 personnes assignées Voir sur GitHub

Personne n'a encore pris cette issue.

stdlib type-feature
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

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. 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

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.