Accéder aux Docstrings en Python

1. Docstrings Python à ligne unique
2. Docstrings multilignes Python

Selon le glossaire Python, docstring est le premier littéral de chaîne qui apparaît immédiatement après la définition d’une classe, d’une méthode ou d’une fonction.

Les Docstring définies après la définition de n’importe quel objet sont souvent associées à cet objet particulier et sont accessibles en utilisant l’attribut __doc__ avec la fonction print ou help(). Les docstrings sont généralement définis en encadrant les littéraux de chaîne entre guillemets triples simples ou triples doubles, comme indiqué ci-dessous :

def addtwo(x):
    """Takes in a number x and adds two to it."""
    return x + 2


print(addtwo.__doc__)

Production :

Takes in a number x and adds two to it.

L’une des meilleures pratiques pour écrire du code propre consiste à fournir une chaîne de documentation décrivant le fonctionnement d’une fonction ou d’un module particulier. En plus de fournir des informations vitales au développeur, l’utilisation de chaînes de documentation Sphinx peut être extraite pour créer une belle documentation dans différents formats tels que texte brut, HTML, ePub ou PDF.

Les docstrings sont en grande partie classés en deux catégories :

• Une seule ligne
• Multiligne

Docstrings Python à ligne unique

Classiquement, les docstrings sont considérés comme une seule ligne uniquement si les triples simples ou triples doubles d’ouverture et de fermeture sont sur la même ligne.

Les lignes simples suivent souvent un format similaire et sont moins descriptives. Au lieu de cela, ils fournissent une brève explication de ce que fait l’objet et de sa valeur de retour.

De plus, les chaînes docs d’une seule ligne ne doivent pas avoir d’espace vide au début et doivent toujours commencer par une lettre majuscule et un point marquant la fin. L’attribut __doc__ peut également être utilisé pour accéder à des chaînes de documentation sur une seule ligne, comme indiqué ci-dessous.

def square(x):
    """Takes in a number x and returns its square."""
    return x ** 2


print(square(10))
print(square.__doc__)

Production :

100
Takes in a number x and adds two to it.

Docstrings multilignes Python

De même, les docstrings multilignes sont également définies par l’inclusion de littéraux de chaîne entre guillemets triples simples ou triples doubles. Cependant, les chaînes de documents multilignes suivent généralement une structure ou un format différent.

Les docstrings multilignes s’étendent généralement sur plus d’une ligne. La première ligne est normalement dédiée à fournir uniquement une brève description de l’objet.

Cette description est suivie d’une ligne vierge et d’une description plus élaborée du paramètre, le cas échéant, et renvoie les arguments de l’objet dans les lignes suivantes. Les grandes bibliothèques telles que scikit learn ou pandas comprennent également une section répertoriant les packages disponibles dans cette bibliothèque.

Bien que les docstrings multilignes aient généralement une structure similaire, certaines différences dépendent du type d’objet. Dans les objets fonction, les docstrings suivraient la structure ci-dessous.

def add_numbers(x, y):
    """
    Function takes to arguments and returns the sum of the two

         Parameter:
                 x (int): An integer
                 y (int): Another integer

        Returns:
               sum(int): Returns an integer sum of x and y

    """
    sum = x + y
    return sum


print(add_numbers.__doc__)

Production :

Function takes to arguments and returns the sum of the two
    
         Parameter:
                 x (int): An integer
                 y (int): Another integer
                 
        Returns:
               sum(int): Returns an integer sum of x and y

Dans les grands modules tels que Scikit, NumPy ou Pandas, les docstrings suivent le format ci-dessous.

On peut aussi utiliser la fonction help() et l’attribut __doc__ pour accéder aux docstrings, comme nous le verrons plus loin. Nous pouvons utiliser l’attribut __doc__ pour accéder aux docstrings dans les modules comme ci-dessous.

import pandas as pd

print(pd.__doc__)

Production :

Les docstrings créées sous les classes doivent indiquer la fonctionnalité de la classe, répertorier toutes les variables d’instance de cette classe spécifique et toutes les méthodes publiques. Les classes qui héritent de la classe principale, également appelées sous-classes, doivent avoir leurs docstrings accessibles séparément.

Comme indiqué ci-dessous, les docstrings peuvent être créées et accessibles dans les classes à l’aide de l’attribut __doc___.

class Car:
    """
    A class to represent a car.

    ...

    Attributes
    ----------
    manufacturer : str
        company that manufactured the car
    model : str
        model of the car
    color : str
        color of the car

    Methods
    -------
    display_info():
        Prints out the car manufacturer, model and color
    """

    def __init__(self, manufacturer, model, color):
        """
        Constructs all the attributes for the car object.

        Parameters
        ----------
                manufacturer : str
                   company that manufactured the car
                model : str
                   model of the car
                color : str
                   color of the car
        """

        self.model = model
        self.color = color
        self.manufacturer = manufacturer

    def display_info(self, color, model, manufacturer):
        """
        Prints the model of the car its color and the manufacturer.

        Parameters
        ----------
        model : str
        color : str
        manufacture: str

        Returns
        -------
        None
        """

        print(f"The {self.color} {self.model} is manufactured by {self.manufacturer}")


print(Car.__doc__)
help(Car)

Production :

A class to represent a car.

    ...

    Attributes
    ----------
    manufacturer : str
        company that manufactured the car
    model : str
        model of the car
    color : str
        color of the car

    Methods
    -------
    display_info():
        Prints out the car manufacturer, model and color
    
Help on class Car in module __main__:

class Car(builtins.object)
 |  Car(manufacturer, model, color)
 |  
 |  A class to represent a car.
 |  
 |  ...
 |  
 |  Attributes
 |  ----------

Alors que les docstrings Python semblent jouer des rôles similaires pour aider les développeurs à comprendre leur code, les commentaires sont ignorés par les interprètes. En Python, les commentaires d’une seule ligne sont précédés d’un symbole dièse et ne peuvent pas comporter plus d’une ligne.

Bien que les commentaires multilignes soient également écrits entre guillemets triple-double ou triple-simple, les commentaires ne suivent généralement pas une structure spécifique. Contrairement aux docstrings qui semblent avoir des formats légèrement différents selon les circonstances dans lesquelles elles ont été utilisées, les commentaires, en revanche, sont généralement utilisés de la même manière quel que soit le programme.