Lorsqu’il s’agit d’écrire du code propre et bien documenté, les développeurs Python disposent d’une arme secrète : les docstrings. Les docstrings, abréviation de chaînes de documentation, sont essentiels pour transmettre l'objectif et la fonctionnalité de Python fonctions, modules et classes.
Que sont les docstrings en Python ?
Python les chaînes de documentation (ou docstrings) fournissent un moyen pratique d'associer la documentation à Modules Python , fonctions, classes et méthodes. Il est spécifié dans le code source qui est utilisé, comme un commentaire, pour documenter un segment spécifique de code. Contrairement aux commentaires conventionnels sur le code source, la docstring doit décrire ce que fait la fonction, et non comment.
- Déclarer des Docstrings : Les docstrings sont déclarées à l’aide de « triples guillemets simples » ou de triples guillemets doubles juste en dessous de la déclaration de classe, de méthode ou de fonction. Toutes les fonctions doivent avoir une docstring.
- Accéder aux Docstrings : Les docstrings sont accessibles via la méthode __doc__ de l'objet ou via la fonction d'aide. Les exemples ci-dessous montrent comment déclarer et accéder à une docstring.
À quoi devrait ressembler une docstring ?
- La ligne de chaîne du document doit commencer par une lettre majuscule et se terminer par un point.
- La première ligne doit être une brève description.
- S'il y a plus de lignes dans la chaîne de documentation, la deuxième ligne doit être vide, séparant visuellement le résumé du reste de la description.
- Les lignes suivantes doivent être constituées d'un ou plusieurs paragraphes décrivant les conventions d'appel de l'objet, les effets secondaires, etc.
Docstrings en Python
Voici les sujets que nous aborderons dans cet article :
- Chaînes entre guillemets triples
- Documents de style Google
- Docstrings de style Numpydoc
- Docstrings sur une seule ligne
- Docstrings multilignes
- Indentation dans les Docstrings
- Docstrings dans les classes
- Différence entre les commentaires Python et les docstrings
Chaînes entre guillemets triples
Il s'agit du format docstring le plus courant en Python. Cela implique l’utilisation de guillemets triples (simples ou doubles) pour encadrer le texte de la documentation. Les chaînes entre guillemets triples peuvent s'étendre sur plusieurs lignes et sont souvent placées immédiatement sous la définition de la fonction, de la classe ou du module.
Exemple 1: Utiliser des guillemets simples triples
Python3
def> my_function():> >'''Demonstrates triple double quotes> >docstrings and does nothing really.'''> > >return> None> print>(>'Using __doc__:'>)> print>(my_function.__doc__)> print>(>'Using help:'>)> help>(my_function)> |
>
>
Sortir:
Using __doc__: Demonstrates triple double quotes docstrings and does nothing really. Using help: Help on function my_function in module __main__: my_function() Demonstrates triple double quotes docstrings and does nothing really.>
Exemple 2 : Utilisation de guillemets triples-doubles
Python3
def> my_function():> >' '> 'Demonstrates triple double quotes docstrings and does nothing really'> ' '> > >return> None> print>(>'Using __doc__:'>)> print>(my_function.__doc__)> print>(>'Using help:'>)> help>(my_function)> |
>
>
Sortir:
Using __doc__: Demonstrates triple double quotes docstrings and does nothing really. Using help: Help on function my_function in module __main__: my_function() Demonstrates triple double quotes docstrings and does nothing really.>
Documents de style Google
Les docstrings de style Google suivent un format spécifique et s'inspirent du guide de style de documentation de Google. Ils fournissent un moyen structuré de documenter le code Python, y compris les paramètres, les valeurs de retour et les descriptions.
Python3
alphabet des chiffres
def> multiply_numbers(a, b):> >'''> >Multiplies two numbers and returns the result.> >Args:> >a (int): The first number.> >b (int): The second number.> >Returns:> >int: The product of a and b.> >'''> >return> a>*> b> print>(multiply_numbers(>3>,>5>))> |
>
>Sortir
15>
Docstrings de style Numpydoc
Les docstrings de style Numpydoc sont largement utilisés dans la communauté scientifique et d'analyse de données, en particulier pour documenter les fonctions et les classes liées aux calculs numériques et à la manipulation de données. Il s'agit d'une extension des docstrings de style Google, avec quelques conventions supplémentaires pour documenter les paramètres et les valeurs de retour.
Python3
def> divide_numbers(a, b):> >'''> >Divide two numbers.> >Parameters> >----------> >a : float> >The dividend.> >b : float> >The divisor.> >Returns> >-------> >float> >The quotient of the division.> >'''> >if> b>=>=> 0>:> >raise> ValueError(>'Division by zero is not allowed.'>)> >return> a>/> b> print>(divide_numbers(>3>,>6>))> |
>
>Sortir
0.5>
Docstrings sur une seule ligne
Comme leur nom l'indique, les docstrings d'une seule ligne tiennent sur une seule ligne. Ils sont utilisés dans des cas évidents. Les guillemets de clôture sont sur la même ligne que les guillemets d’ouverture. Cela semble mieux pour les one-liners. Par exemple:
Python3
def> power(a, b):> >' '> 'Returns arg1 raised to power arg2.'> ' '> > >return> a>*>*>b> print>(power.__doc__)> |
>
>
Sortir:
Returns arg1 raised to power arg2.>
Docstrings multilignes
Les docstrings multilignes se composent d'une ligne récapitulative, tout comme une docstring d'une seule ligne, suivie d'une ligne vide, suivie d'une description plus élaborée. La ligne de résumé peut être sur la même ligne que les guillemets d'ouverture ou sur la ligne suivante. L'exemple ci-dessous montre une docstring multiligne.
Python3
def> add_numbers(a, b):> >'''> >This function takes two numbers as input and returns their sum.> >Parameters:> >a (int): The first number.> >b (int): The second number.> >Returns:> >int: The sum of a and b.> >'''> >return> a>+> b> print>(add_numbers(>3>,>5>))> |
>
>
Sortir:
8>
Indentation dans les Docstrings
La docstring entière est mise en retrait de la même manière que les guillemets de sa première ligne. Les outils de traitement de docstring supprimeront une quantité uniforme d'indentation de la deuxième ligne et des lignes suivantes de la docstring, égale à l'indentation minimale de toutes les lignes non vides après la première ligne. Toute indentation dans la première ligne de la docstring (c'est-à-dire jusqu'à la première nouvelle ligne) est insignifiante et supprimée. L'indentation relative des lignes ultérieures de la docstring est conservée.
Python3
class> Employee:> >'''> >A class representing an employee.> >Attributes:> >name (str): The name of the employee.> >age (int): The age of the employee.> >department (str): The department the employee works in.> >salary (float): The salary of the employee.> >'''> >def> __init__(>self>, name, age, department, salary):> >'''> >Initializes an Employee object.> >Parameters:> >name (str): The name of the employee.> >age (int): The age of the employee.> >department (str): The department the employee works in.> >salary (float): The salary of the employee.> >'''> >self>.name>=> name> >self>.age>=> age> >self>.department>=> department> >self>.salary>=> salary> >def> promote(>self>, raise_amount):> >'''> >Promotes the employee and increases their salary.> >Parameters:> >raise_amount (float): The raise amount to increase the salary.> >Returns:> >str: A message indicating the promotion and new salary.> >'''> >self>.salary>+>=> raise_amount> >return> f>'{self.name} has been promoted! New salary: ${self.salary:.2f}'> >def> retire(>self>):> >'''> >Marks the employee as retired.> >Returns:> >str: A message indicating the retirement status.> >'''> ># Some implementation for retiring an employee> >return> f>'{self.name} has retired. Thank you for your service!'> # Access the Class docstring using help()> help>(Employee)> |
>
>
Sortir:
class Employee | A class representing an employee. | | Attributes: | name (str): The name of the employee. | age (int): The age of the employee. | department (str): The department the employee works in. | salary (float): The salary of the employee. | | Methods defined here: | | __init__(self, name, age, department, salary) | Initializes an Employee object. | | Parameters: | name (str): The name of the employee. | age (int): The age of the employee. | department (str): The department the employee works in. | salary (float): The salary of the employee. | | promote(self, raise_amount) | Promotes the employee and increases their salary. | | Parameters: | raise_amount (float): The raise amount to increase the salary. | | Returns: | str: A message indicating the promotion and new salary. | | retire(self) | Marks the employee as retired. | | Returns: | str: A message indicating the retirement status.>
Docstrings dans les classes
Prenons un exemple pour montrer comment écrire des docstrings pour une classe et la méthode ' aide' est utilisé pour accéder à la docstring.
Python3
class> ComplexNumber:> >'''> >This is a class for mathematical operations on complex numbers.> >Attributes:> >real (int): The real part of the complex number.> >imag (int): The imaginary part of the complex number.> >'''> >def> __init__(>self>, real, imag):> >'''> >The constructor for ComplexNumber class.> >Parameters:> >real (int): The real part of the complex number.> >imag (int): The imaginary part of the complex number.> >'''> >self>.real>=> real> >self>.imag>=> imag> >def> add(>self>, num):> >'''> >The function to add two Complex Numbers.> >Parameters:> >num (ComplexNumber): The complex number to be added.> >Returns:> >ComplexNumber: A complex number which contains the sum.> >'''> >re>=> self>.real>+> num.real> >im>=> self>.imag>+> num.imag> >return> ComplexNumber(re, im)> # Access the Class docstring using help()> help>(ComplexNumber)> # Access the method docstring using help()> help>(ComplexNumber.add)> |
>
>
Sortir:
Help on class ComplexNumber in module __main__: class ComplexNumber(builtins.objects) | This is a class for mathematical operations on complex numbers. | | Attributes: | real (int): The real part of complex number. | imag (int): The imaginary part of complex number. | | Methods defined here: | | __init__(self, real, imag) | The constructor for ComplexNumber class. | | Parameters: | real (int): The real part of complex number. | imag (int): The imaginary part of complex number. | | add(self, num) | The function to add two Complex Numbers. | | Parameters: | num (ComplexNumber): The complex number to be added. | | Returns: | ComplexNumber: A complex number which contains the sum. Help on method add in module __main__: add(self, num) unbound __main__.ComplexNumber method The function to add two Complex Numbers. Parameters: num (ComplexNumber): The complex number to be added. Returns: ComplexNumber: A complex number which contains the sum.>
Différence entre les commentaires Python, String et Docstrings
Chaîne : en Python, une chaîne est une séquence de caractères entourée de guillemets simples (' ) ou de guillemets doubles ( ). Les chaînes sont utilisées pour représenter des données textuelles et peuvent contenir des lettres, des chiffres, des symboles et des espaces. Ils constituent l'un des types de données fondamentaux de Python et peuvent être manipulés à l'aide de diverses méthodes de chaînes.
Vous devez tous avoir une idée sur les docstrings Python, mais vous êtes-vous déjà demandé quelle est la différence entre les commentaires Python et les docstrings ? Jetons un coup d'oeil à eux.
Ce sont des informations utiles que les développeurs fournissent pour faire comprendre au lecteur le code source. Il explique la logique ou une partie de celle-ci utilisée dans le code. Il est écrit en utilisant
#>
symboles.
Exemple:
Python3
matrice de latex
# Python program to demonstrate comments> print>(>'GFG'>)> name>=> 'Abhishek Shakya'> #demostrate String> |
>
>
Sortir:
GFG>
Alors que Python Docstrings, comme mentionné ci-dessus, fournit un moyen pratique d'associer la documentation aux modules, fonctions, classes et méthodes Python.