🙍🏾 🍡 💃🏾 PEP 257 en russe. (Accord Docstrings) 🤓 👩🏿‍🚀 🖐🏼

Bonjour, Habr. Il y a des moments où vous voulez vous immerger autant que possible dans la langue et comprendre toutes ses subtilités. Dans le cas de Python, l'une des meilleures façons de le faire est de lire la documentation et les PEP sur le site officiel. Je ne l'ai pas fait à l'époque, car je ne comprenais pas beaucoup des aspects "techniques" et il n'y avait pas de variantes de la traduction russe. Maintenant, j'ai décidé de traduire moi-même PEP-257, qui raconte la bonne documentation du code, car cela aidera à coup sûr les débutants à mieux comprendre la véritable approche «Python» de l'écriture de code. J'ai traduit les exemples de code en russe, mais uniquement pour mieux transmettre le sens. Dans la vraie programmation, essayez d'écrire des lignes de documentation en anglais. Je dis aussi tout de suite qu'en tant que synonyme du terme «docstring», j'ai utilisé les mots: «documentation» et «documentation lines». Eh bien, passons à la traduction elle-même.

Dynamisme	257
Titre:	Accord Docstrings
Auteurs:	David Goodger <goodger at python.org>, Guido van Rossum <guido at python.org>
Discussion:	doc-sig sur python.org
Statut:	actif
Un type:	Informatif
Créé:	29 mai 2001
Publication:	13-juin-2001

annotation

Ce PEP documente la sémantique et les conventions associées à l'utilisation des docstrings Python.

Justification

Le but de ce PEP est de normaliser la structure de haut niveau des chaînes de documents: pour décrire exactement ce qu'elles doivent contenir et expliquer (nous ne discuterons pas de la syntaxe de balisage réelle). Le PEP ne contient pas de directives strictes, mais des recommandations:

«Les conventions conventionnelles offrent clarté, cohérence, facilité d'entretien et favorisent de bonnes habitudes de programmation. Mais ils ne vous obligent pas à agir contre votre volonté. C'est Python! "

Tim Peters sur comp.lang.python, 2001-06-16

Si vous évitez les accords généralement acceptés, vous serez louché au pire. Mais il existe certaines applications (par exemple, des systèmes de documentation comme Docutils) qui vous permettront d'obtenir un meilleur résultat si vous connaissez les accords et les respectez.

spécification

Qu'est-ce qu'un Docstring?

Une chaîne de documentation est un littéral de chaîne qui est la première instruction d'une définition de module, de fonction, de classe ou de méthode. Une telle chaîne devient disponible lors de la gestion de l'attribut spécial __doc__ de cet objet.

Toutes les bibliothèques, ainsi que les fonctions et classes exportées par elles, doivent avoir docstring. Les méthodes publiques (y compris le constructeur __ init__) doivent également avoir de la documentation. Le package lui-même peut être documenté dans le fichier __init__.py situé dans son répertoire correspondant.

Les littéraux de chaîne trouvés ailleurs dans le code peuvent également jouer le rôle de documentation. Ils ne sont pas reconnus par le compilateur de bytecode Python et ne sont pas disponibles en tant qu'attributs d'objet au moment de l'exécution (c'est-à-dire qu'ils manquent d'informations dans __ doc__). Mais il existe deux autres types de lignes de documentation qui sont récupérées à l'aide d'autres outils logiciels:

Les littéraux de chaîne qui se produisent immédiatement après une simple affectation au niveau du module, de la classe ou de __init__ sont appelés «chaînes de documentation d'attribut». (attribut docstrings)
Les littéraux de chaîne qui apparaissent immédiatement après une autre ligne de documentation sont appelés «lignes de documentation supplémentaires». (docstrings supplémentaires)

Veuillez consulter PEP 258, «Spécifications du projet Docutils», pour plus de détails sur l'attribut et les chaînes de documentation supplémentaires.

[environ. éd. Explication de PEP 258]

def f(x):
    """  docstring   __doc__ ."""
    """
     "additional docstrings",   , 
        Docutils.
    """
    return x**2

f.a = 1
""" "attribute docstrings"   : f.a"""

Pour des raisons de cohérence, utilisez toujours les "" "triples guillemets doubles" "" autour de la ligne de documentation. Si vous utilisez des barres obliques inverses ("\"), utilisez la r "" "chaîne entre guillemets bruts" "" dans votre documentation. Pour la docstring contenant des caractères Unicode, utilisez u "" "Chaîne Unicode entre guillemets doubles" "". [environ. les chaînes unicode ont perdu leur signification dans python 3.x]

Il existe deux formes de docstring: monoligne et multiligne.

Lignes de documentation sur une seule ligne

Les chaînes à une seule ligne sont utilisées pour les cas évidents et elles devraient vraiment être sur la même ligne. Par exemple:

def kos_root():
    """    root KOS"""
    global _kos_root
    if _kos_root: return _kos_root
    ...

Remarques:

. .
, . docstring .
, .
— «», . (« », « »), . , : « ...».

« » «Return pathname» «Returns pathname». PEP-257 , .

«», / ( ). :

def function(a, b):
    """function(a, b) -> list"""

, C ( ), . . - :

def function(a, b):
    def function(a, b):
    """ X   ."""

( -, « X» !)

, : « », «description» . , , .

La documentation multi-lignes se compose d'une ligne récapitulative qui a la même structure qu'une docstring sur une seule ligne, suivie d'une ligne vide, puis d'une description plus complexe. La "ligne récapitulative" peut être utilisée au moyen d'une documentation automatique; par conséquent, il est si important de le placer sur une seule ligne, puis de faire une passe sur une seule ligne. La ligne récapitulative est écrite immédiatement après les guillemets d'ouverture, mais elle est autorisée à faire une césure et à partir de la ligne suivante. [environ. après cette phrase, j'étais heureux, car il y avait des gens qui essayaient constamment de me prouver qu'il était impossible d'effectuer un transfert dans tous les cas :-)] En même temps, l'ensemble de la docstring devrait avoir le même retrait que les guillemets d'ouverture de la première ligne (voir l'exemple au dessous de).

Laissez une ligne vide après toute la documentation (monoligne ou multiligne) utilisée dans la classe; de manière générale, les méthodes de classe doivent être séparées les unes des autres par une ligne vide, donc la ligne de documentation de classe doit également être séparée de cette manière de la première méthode.

La documentation du script (programme autonome) est un message «sur l'utilisation appropriée» et sera probablement imprimée lorsque le script sera appelé avec des arguments invalides ou manquants (ou avec l'option «-h» pour obtenir «aide»). Une telle ligne de documentation devrait décrire la fonctionnalité et la syntaxe des paramètres de script, ainsi que les variables d'environnement et les fichiers utilisés. Ce message peut s'avérer assez compliqué (le manuel est long de plusieurs écrans), mais en même temps, il devrait être pratique pour les nouveaux utilisateurs afin qu'ils puissent utiliser la commande correctement. De plus, le manuel devrait donner une description claire de tous les paramètres et arguments pour les utilisateurs plus expérimentés.

La documentation du module doit généralement contenir une liste des classes, exceptions et fonctions (et tout autre objet important) qui sont exportées à l'aide de la bibliothèque, ainsi qu'une explication sur une ligne pour chacune d'entre elles. (Ce résumé, en règle générale, donne moins de détails que la ligne de résumé dans la docstring de l'objet lui-même). La documentation du package (c'est-à-dire la docstring de module dans __init__.py) doit également décrire et lister les modules et sous-packages exportés par le module principal.

La documentation d'une fonction ou d'une méthode doit décrire leur comportement, leurs arguments, leurs valeurs de retour, leurs effets secondaires, leurs exceptions et leurs restrictions quant au moment où elles peuvent être appelées (le cas échéant). Vous devez également spécifier des arguments facultatifs. Il convient de préciser si les arguments clés font partie de l'interface.

La documentation de classe doit résumer son comportement et répertorier les méthodes publiques ainsi que les variables d'instance. Si la classe aura des sous-classes avec une interface supplémentaire, alors cette interface doit être spécifiée séparément (mais tout est également dans cette documentation). Le constructeur de classe doit avoir sa propre ligne de documentation distincte pour la méthode __init__. Les méthodes indépendantes (individuelles) doivent avoir leur propre documentation.

Si une classe est un descendant et que son comportement est principalement hérité de la classe principale, il est nécessaire de le mentionner dans sa documentation et de décrire les différences possibles. Utilisez le verbe «override» pour indiquer qu'une méthode a été modifiée et que, par conséquent, la méthode de superclasse ne sera pas appelée. Utilisez le verbe «étend» si la méthode de sous-classe appelle la méthode de super-classe (en plus de son propre comportement).

N'utilisez pas la convention Emacs pour mentionner des arguments de fonction ou des méthodes en majuscules. Python est sensible à la casse et les noms d'arguments peuvent parfois être utilisés lors de leur transmission par clés, la documentation doit donc contenir de vrais noms de variables. Il est préférable de répertorier chaque argument sur une ligne distincte. Par exemple:

def complex(real=0.0, imag=0.0):
    """  .

     :
    real --   (  0.0)
    imag --   (  0.0)
    """
    if imag == 0.0 and real == 0.0:
        return complex_zero
    ...

Si l'ensemble de la docstring ne tient pas sur la ligne, vous pouvez placer les guillemets de fermeture sur une ligne distincte. Ainsi, il sera possible d'utiliser la commande Emacs: fill-paragraph

Traitement Docstring

Les outils de traitement des lignes de documentation doivent supprimer le même nombre d'indentations égal à l'indentation minimale de toutes les lignes non vides, à partir de la seconde. Toute indentation dans la première ligne de la documentation n'est pas significative et sera supprimée. L'indentation relative des lignes ultérieures de la ligne de document est conservée. Les lignes vides doivent être supprimées du début et de la fin de la ligne du document.

Puisque le code est beaucoup plus précis que les mots, voici l'implémentation de l'algorithme:

def trim(docstring):
    if not docstring:
        return ''
    #     (  Python)
    #      :
    lines = docstring.expandtabs().splitlines()
    #    (   ):
    indent = sys.maxsize
    for line in lines[1:]:
        stripped = line.lstrip()
        if stripped:
            indent = min(indent, len(line) - len(stripped))
    #   (   ):
    trimmed = [lines[0].strip()]
    if indent < sys.maxsize:
        for line in lines[1:]:
            trimmed.append(line[indent:].rstrip())
    #       :
    while trimmed and not trimmed[-1]:
        trimmed.pop()
    while trimmed and not trimmed[0]:
        trimmed.pop(0)
    #    :
    return '\n'.join(trimmed)

Note du traducteur

, python3 sys.maxint sys.maxsize, .

La documentation de l'exemple suivant contient deux nouvelles lignes et a donc une longueur de trois. La première et la dernière ligne sont vides:

def foo ():
    """
       .
    """

Nous illustrons:

>>> print repr(foo.__doc__)
'\n        .\n    '
>>> foo.__doc__.splitlines()
['', '        .', '    ']
>>> trim(foo.__doc__)
'    .'

Ainsi, après traitement, les lignes de documentation suivantes seront équivalentes:

def foo():
    """ 
     .
    """

def bar():
    """
     
     .
    """