Tutoriel sur les chaînes de caractères en Python

Si vous débutez en Python et souhaitez en savoir plus, suivez le cours Introduction à la science des données en Python de DataCamp.

Pratiquez les Docstrings en Python avec cet exercice pratique.

La chaîne de documentation Python, communément appelée docstring, est une chaîne littérale utilisée dans la définition d'une classe, d'un module, d'une fonction ou d'une méthode. Les chaînes de documents sont accessibles à partir de l'attribut doc (__doc__) pour n'importe quel objet Python, ainsi qu'avec la fonction intégrée help(). La docstring d'un objet est définie en incluant une constante de type chaîne de caractères comme première déclaration dans la définition de l'objet.

Les chaînes de texte sont très utiles pour comprendre la fonctionnalité de la plus grande partie du code, c'est-à-dire l'objectif général d'une classe, d'un module ou d'une fonction, tandis que les commentaires sont utilisés pour le code, les déclarations et les expressions, qui ont tendance à être de petite taille. Il s'agit d'un texte descriptif écrit par un programmeur principalement pour lui-même afin de savoir ce que fait la ligne de code ou l'expression et également pour le développeur qui souhaite contribuer à ce projet. Il est essentiel que la documentation de votre code Python soit suffisamment efficace pour vous permettre d'écrire un code propre et des programmes bien écrits.

Les docstrings vous aident à comprendre les capacités d'un module ou d'une fonction. Par exemple, disons que vous avez installé la bibliothèque scikit-learn et que vous aimeriez tout savoir sur le paquet sklearn, comme la description, les modules du paquet, etc., vous pouvez simplement utiliser la fonction help pour obtenir toutes les informations.

Importons rapidement le paquet.

import sklearn

help(sklearn)

Vous obtiendrez un résultat similaire à celui présenté ci-dessous :

Docstrings Python vs. Commentaire

Les docstrings sont similaires à l'esprit des commentaires, mais ce sont des versions améliorées, plus logiques et plus utiles des commentaires. Les chaînes de caractères servent de documentation pour la classe, le module et les paquets.

D'autre part, les commentaires sont principalement utilisés pour expliquer les parties non évidentes du code et peuvent être utiles pour les commentaires sur la correction des bogues et les tâches qui doivent être effectuées.

Les chaînes de documents sont représentées par des guillemets fermants et ouvrants, tandis que les commentaires commencent par un #.

Notez que les commentaires ne sont pas accessibles avec l'attribut intégré doc et la fonction help. Voyons ce qui se passe si vous essayez de le faire :

def string_reverse(str1):
    #Returns the reversed String.

    #Parameters:
    #    str1 (str):The string which is to be reversed.

    #Returns:
    #    reverse(str1):The string which gets reversed.   

    reverse_str1 = ''
    i = len(str1)
    while i > 0:
        reverse_str1 += str1[i - 1]
        i = i- 1
    return reverse_str1

print(string_reverse.__doc__)

None

help(string_reverse)

Help on function string_reverse in module __main__:

string_reverse(str1)

Il existe deux façons d'écrire ou d'utiliser une chaîne de documents, à savoir one-line docstring et multi-line docstring. Apprenons-les un par un.

Docstring à une ligne

Les Docstrings d'une ligne sont les Docstrings qui tiennent sur une seule ligne. Vous pouvez utiliser l'un des guillemets, c'est-à-dire un triple guillemet simple ou un triple guillemet double, et les guillemets ouvrants et fermants doivent être identiques. Dans les chaînes de documents d'une ligne, les guillemets fermants se trouvent sur la même ligne que les guillemets ouvrants. De plus, la convention standard est d'utiliser des guillemets triples et doubles.

def square(a):
    '''Returned argument a is squared.'''
    return a**a

print (square.__doc__)

Returned argument a is squared.

help(square)

Help on function square in module __main__:

square(a)
    Returned argument a is squared.

D'après la sortie Docstring ci-dessus, vous pouvez observer que :

• Dans ce cas, la ligne commence par une lettre majuscule, à savoir R, et se termine par un point (.).
• Les guillemets fermants sont sur la même ligne que les guillemets ouvrants. Cela convient mieux aux répliques.
• Une bonne pratique à suivre est de ne pas avoir de ligne blanche avant ou après la chaîne de caractères, comme le montre l'exemple ci-dessus.
• La sortie de l'attribut __doc__ est moins verbeuse que celle de la fonction help().

Docstring multiligne

Les chaînes de caractères multi-lignes contiennent également la même ligne de caractères littéraux que les chaînes de caractères monolignes, mais elle est suivie d'un blanc et d'un texte descriptif.

Le format général d'écriture d'une chaîne de documents multi-lignes est le suivant :

def some_function(argument1):
    """Summary or Description of the Function

    Parameters:
    argument1 (int): Description of arg1

    Returns:
    int:Returning value

   """

    return argument1

print(some_function.__doc__)

Summary or Description of the Function

    Parameters:
    argument1 (int): Description of arg1

    Returns:
    int:Returning value

help(some_function)

Help on function some_function in module __main__:

some_function(argument1)
    Summary or Description of the Function

    Parameters:
    argument1 (int): Description of arg1

    Returns:
    int:Returning value

Examinons l'exemple qui montre comment les chaînes de caractères multilignes peuvent être utilisées en détail :

def string_reverse(str1):
    '''
    Returns the reversed String.

    Parameters:
        str1 (str):The string which is to be reversed.

    Returns:
        reverse(str1):The string which gets reversed.   
    '''

    reverse_str1 = ''
    i = len(str1)
    while i > 0:
        reverse_str1 += str1[i - 1]
        i = i- 1
    return reverse_str1

print(string_reverse('DeepLearningDataCamp'))

pmaCataDgninraeLpeeD

help(string_reverse)

Help on function string_reverse in module __main__:

string_reverse(str1)
    Returns the reversed String.

    Parameters:
        str1 (str):The string which is to be reversed.

    Returns:
        reverse(str1):The string which gets reversed.

Vous pouvez voir ci-dessus que la ligne de résumé se trouve sur une seule ligne et qu'elle est également séparée du reste du contenu par une seule ligne vierge. Cette convention doit être respectée, ce qui est utile pour les outils d'indexation automatique.

Chaîne de documents intégrée à Python

Voyons les chaînes de caractères intégrées à Python.

Toutes les fonctions, classes et méthodes intégrées sont accompagnées d'une description humaine. Vous pouvez y accéder de deux manières.

• Attribut du document
• La fonction d'aide

Vous remarquerez que la sortie de la fonction help est plus verbeuse que l'attribut __doc__.

Par exemple :

import math
print(math.__doc__)

This module provides access to the mathematical functions
defined by the C standard.

De même, vous pouvez utiliser la fonction d'aide :

help(math)

Python Docstring dans les classes

Dans une définition de classe, une docstring peut être utilisée pour fournir de la documentation sur la classe dans son ensemble. Vous la placez généralement juste après la définition de la classe et elle est entourée de guillemets triples ("""). Par exemple :

class MyClass:
    """This is the documentation for MyClass."""

    def __init__(self):
        """This is the documentation for the __init__ method."""
        pass

Les docstrings sont accessibles à l'aide de l'attribut __doc__ de la classe ou de la méthode. Par exemple, vous pouvez accéder à la docstring de MyClass en utilisant MyClass.__doc__.

Examinons maintenant quelques formats de chaînes de caractères populaires et comprenons-les en détail.

Formats des chaînes de caractères Python

Il existe de nombreux formats de Docstrings disponibles, mais il est toujours préférable d'utiliser les formats qui sont facilement reconnus par l'analyseur Docstring et par les autres Data Scientists/programmeurs. Il n'y a pas de règles ou de règlements pour choisir un format de Docstring, mais il est nécessaire de choisir le même format tout au long du projet. Il est également préférable d'utiliser le type de formatage, qui est le plus souvent pris en charge par Sphinx.

Les formats les plus courants sont énumérés ci-dessous.

Il peut y avoir différentes chaînes de documentation disponibles. Vous n'avez pas à vous inquiéter de devoir réinventer la roue pour tout étudier. Les formats de toutes les chaînes de documentation sont presque similaires. Les modèles sont similaires, mais il n'y a que des changements mineurs dans chaque format. Vous examinerez l'exemple d'un format populaire de chaîne de documentation disponible avec leur utilisation.

Dans un premier temps, vous verrez le style Sphinx en détail, puis vous pourrez facilement suivre d'autres formats.

Style Sphinx

Sphinx est le style facile et traditionnel, verbeux, et a été initialement créé spécifiquement pour la documentation Python. Sphinx utilise un texte reStructuré, dont l'utilisation est similaire à celle de Markdown.

class Vehicle(object):
    '''
    The Vehicle object contains lots of vehicles
    :param arg: The arg is used for ...
    :type arg: str
    :param `*args`: The variable arguments are used for ...
    :param `**kwargs`: The keyword arguments are used for ...
    :ivar arg: This is where we store arg
    :vartype arg: str
    '''


    def __init__(self, arg, *args, **kwargs):
        self.arg = arg

    def cars(self, distance, destination):
        '''We can't travel a certain distance in vehicles without fuels, so here's the fuels

        :param distance: The amount of distance traveled
        :type amount: int
        :param bool destinationReached: Should the fuels be refilled to cover required distance?
        :raises: :class:`RuntimeError`: Out of fuel

        :returns: A Car mileage
        :rtype: Cars
        '''  
        pass

Sphinx utilise l'adresse keyword(reserved word); c'est le cas de la plupart des langages de programmation. Mais il est explicitement appelé role dans Sphinx. Dans le code ci-dessus, Sphinx considère param comme un rôle, et type comme un rôle, qui est le type de données Sphinx pour param. Le rôle type est facultatif, mais param est obligatoire. Les rôles de retour documentent l'objet retourné. Il est différent du rôle param. Le rôle de retour ne dépend pas du type de retour et vice-versa. Le type r est le type d'objet renvoyé par la fonction donnée.

Google Style

Google Style est plus facile et plus intuitif à utiliser. Il peut être utilisé pour la forme courte de la documentation. Une configuration du fichier python doit être effectuée pour démarrer, vous devez donc ajouter sphinx.ext.napoleon ou sphinxcontrib.napoleon à la liste des extensions dans conf.py.

class Vehicles(object):
    '''
    The Vehicle object contains a lot of vehicles

    Args:
        arg (str): The arg is used for...
        *args: The variable arguments are used for...
        **kwargs: The keyword arguments are used for...

    Attributes:
        arg (str): This is where we store arg,
    '''
    def __init__(self, arg, *args, **kwargs):
        self.arg = arg

    def cars(self, distance,destination):
        '''We can't travel distance in vehicles without fuels, so here is the fuels

        Args:
            distance (int): The amount of distance traveled
            destination (bool): Should the fuels refilled to cover the distance?

        Raises:
            RuntimeError: Out of fuel

        Returns:
            cars: A car mileage
        '''
        pass

Le style Google est meilleur que le style Sphinx. Il présente également une caractéristique gênante : dans le code ci-dessus, la description de la distance sur plusieurs lignes serait désordonnée. C'est pourquoi le Numpy peut être utilisé pour une forme plus étendue de documentation.

Style Numpy

Le style Numpy est très détaillé dans la documentation. Elle est plus verbeuse que d'autres documentations, mais c'est un excellent choix si vous souhaitez réaliser une documentation détaillée, c'est-à-dire une documentation exhaustive de toutes les fonctions et de tous les paramètres.

class Vehicles(object):
    '''
    The Vehicles object contains lots of vehicles

    Parameters
    ----------
    arg : str
        The arg is used for ...
    *args
        The variable arguments are used for ...
    **kwargs
        The keyword arguments are used for ...

    Attributes
    ----------
    arg : str
        This is where we store arg,
    '''
    def __init__(self, arg, *args, **kwargs):
        self.arg = arg

    def cars(self, distance, destination):
        '''We can't travel distance in vehicles without fuels, so here is the fuels

        Parameters
        ----------
        distance : int
            The amount of distance traveled
        destination : bool
            Should the fuels refilled to cover the distance?

        Raises
        ------
        RuntimeError
            Out of fuel

        Returns
        -------
        cars
            A car mileage
        '''
        pass

L'exemple ci-dessus est plus verbeux que toute autre documentation. Il est plus long et ne peut être utilisé que pour une documentation longue et détaillée.

PyDoc

Comme vous l'avez appris, les docstrings sont accessibles via l'attribut intégré de Python __doc__ et la fonction help(). Vous pouvez également utiliser le module intégré connu sous le nom de Pydoc, qui est très différent en termes de caractéristiques et de fonctionnalités par rapport à l'attribut doc et à la fonction d'aide.

Pydoc est un outil qui vous sera utile si vous souhaitez partager le code avec vos collègues ou le rendre open-source, auquel cas vous vous adresserez à un public beaucoup plus large. Il peut générer des pages web à partir de votre documentation Python et peut également lancer un serveur web.

Voyons comment cela fonctionne.

La manière la plus simple et la plus pratique d'exécuter le module Pydoc est de l'exécuter en tant que script. Pour l'exécuter à l'intérieur de la cellule du laboratoire jupyter, vous devez utiliser le point d'exclamation ( !).

• Pydoc en tant que module

!python -m pydoc

pydoc - the Python documentation tool

pydoc <name> ...
    Show text documentation on something.  <name> may be the name of a
    Python keyword, topic, function, module, or package, or a dotted
    reference to a class or function within a module or module in a
    package.  If <name> contains a '\', it is used as the path to a
    Python source file to document. If name is 'keywords', 'topics',
    or 'modules', a listing of these things is displayed.

pydoc -k <keyword>
    Search for a keyword in the synopsis lines of all available modules.

pydoc -n <hostname>
    Start an HTTP server with the given hostname (default: localhost).

pydoc -p <port>
    Start an HTTP server on the given port on the local machine.  Port
    number 0 can be used to get an arbitrary unused port.

pydoc -b
    Start an HTTP server on an arbitrary unused port and open a Web browser
    to interactively browse documentation.  This option can be used in
    combination with -n and/or -p.

pydoc -w <name> ...
    Write out the HTML documentation for a module to a file in the current
    directory.  If <name> contains a '\', it is treated as a filename; if
    it names a directory, documentation is written for all the contents.

Si vous regardez la sortie ci-dessus, la toute première utilisation de Pydoc est d'afficher de la documentation texte sur une fonction, un module, une classe, etc., alors voyons comment vous pouvez l'exploiter mieux que la fonction help.

!python -m pydoc glob

Help on module glob:

NAME
    glob - Filename globbing utility.

MODULE REFERENCE
    https://docs.python.org/3.7/library/glob

    The following documentation is automatically generated from the Python
    source files.  It may be incomplete, incorrect or include features that
    are considered implementation detail and may vary between Python
    implementations.  When in doubt, consult the module reference at the
    location listed above.

FUNCTIONS
    escape(pathname)
        Escape all special characters.

    glob(pathname, *, recursive=False)
        Return a list of paths matching a pathname pattern.

        The pattern may contain simple shell-style wildcards a la
        fnmatch. However, unlike fnmatch, filenames starting with a
        dot are special cases that are not matched by '*' and '?'
        patterns.

        If recursive is true, the pattern '**' will match any files and
        zero or more directories and subdirectories.

    iglob(pathname, *, recursive=False)
        Return an iterator which yields the paths matching a pathname pattern.

        The pattern may contain simple shell-style wildcards a la
        fnmatch. However, unlike fnmatch, filenames starting with a
        dot are special cases that are not matched by '*' and '?'
        patterns.

        If recursive is true, the pattern '**' will match any files and
        zero or more directories and subdirectories.

DATA
    __all__ = ['glob', 'iglob', 'escape']

FILE
    c:\users\hda3kor\.conda\envs\test\lib\glob.py

Maintenant, extrayons la documentation de glob à l'aide de la fonction help.

help(glob)

---------------------------------------------------------------------------

NameError                                 Traceback (most recent call last)

<ipython-input-6-6f504109e3a2> in <module>
----> 1 help(glob)


NameError: name 'glob' is not defined

Comme vous pouvez le voir, il y a une erreur de nom car le glob n'est pas défini. Ainsi, pour utiliser la fonction d'aide pour extraire la documentation, vous devez d'abord importer ce module, ce qui n'est pas le cas dans Pydoc.

• Pydoc en tant que service web

Explorons la fonctionnalité la plus intéressante du module Pydoc, à savoir l'exécution de Pydoc en tant que service web.

Pour ce faire, il vous suffit d'exécuter Pydoc comme un script, mais avec un argument -b qui lancera un serveur HTTP sur un port arbitraire inutilisé et ouvrira un navigateur Web pour parcourir la documentation de manière interactive. Cette fonction est utile, en particulier lorsque vous avez plusieurs autres services en cours d'exécution sur votre système et que vous ne vous souvenez pas du port qui serait en état d'inactivité.

!python -m pydoc -b

^C

Dès que vous exécutez la cellule ci-dessus, une nouvelle fenêtre s'ouvre sur un numéro de port arbitraire, et le navigateur web ressemble à celui illustré ci-dessous.

Examinons la documentation du module h5py, qui est un format de fichier utilisé pour stocker les poids de l'architecture des réseaux neuronaux.

Conclusion

Félicitations pour avoir terminé le tutoriel docstring en Python.

Ce tutoriel a pour objectif principal de vous permettre de commencer à utiliser les chaînes de documents en abordant les sujets essentiels. Cependant, Docstrings est un vaste sujet, et certains concepts ont pu rester inexplorés. Si vous souhaitez en savoir plus, consultez notre tutoriel sur les chaînes de caractères en Python et notre cours sur l'écriture de fonctions en Python.

Si vous débutez en Python et souhaitez en savoir plus, suivez le cours Introduction à la science des données en Python de DataCamp.