Exemple de docstring Python
Alors que les commentaires sont utilisés pour les programmes, les déclarations et les expressions, qui sont généralement brèves, les docstrings sont excellents pour comprendre le fonctionnement de la partie plus large du script comme l'utilisation générale de n'importe quel module, classe ou fonction. Ils sont une description d'une ligne de code ou de déclaration produite par un programmeur qui est généralement pour eux-mêmes pour comprendre ce qu'il fait. Il est crucial de documenter correctement votre code si vous souhaitez rédiger des programmes avec un code clair et une bonne documentation. Les docstrings sont fournis, employant les «Triple Single Quotes» ou «Triple Double Quotes» juste après la fonction, la classe ou la définition de la méthode.
Exemple 1: Programme de Python Docstring triple citations simples
Soit la méthode __doc__ de l'objet, soit la fonction d'aide peut être utilisée pour obtenir les docstrings. La déclaration et l'utilisation d'un docstring avec les triples citations simples sont indiquées dans les exemples suivants:
Commencez par définir une fonction dans Python. Nous créons une fonction comme my_func (). Dans le corps du my_func, nous avons en tant que docstring enroulé autour des triples citations simples. Ensuite, à la fin de la fonction, nous exécutons explicitement l'instruction de retour qui renvoie la valeur aucune. La fonction d'impression emmène my_func avec l'objet _doc_ qui affichera le docstring. De plus, nous avons une fonction d'aide Python qui est utilisée pour imprimer la documentation de la fonction my_func.
Lorsque ce programme particulier est débogué et exécuté, il génère les résultats suivants dans l'écran de la console de Spyder:
Exemple 2: Programme de Python Docstring Triple Double Quotes
Le code suivant déploie la déclaration et utilisation docstring avec les triples doubles::
Ici, nous donnons un nom de fonction my_func2. À l'intérieur du corps du my_func2, nous déclarons un docstring avec la citation triple-double. Ensuite, nous appelons l'objet _doc_ du Python pour imprimer le docstring spécifié et la documentation de la fonction my_func2 avec la fonction d'aide.
Les résultats générés à partir des codes susmentionnés sont les suivants. Cette sortie est générée par l'exécution du code apposé précédent dans Spyder:
Exemple 3: Programme de docstring en ligne Python
Les docstrings en une ligne sont exactement ce que leur nom suggère: une ligne. Ils sont employés dans des situations flagrantes. Les dernières citations sont situées sur une ligne similaire à celles initiales. Pour les doublures, cela semble plus attrayant.
Ici, nous construisons une fonction «Add» qui prend deux arguments: x et y. Ensuite, nous déclarons la docstring d'une ligne à l'intérieur du corps de la définition de la fonction «Ajouter». L'instruction de retour renvoie la valeur de l'ajout des deux valeurs. L'instruction d'impression est invoquée pour afficher le docstring à l'intérieur de la fonction ADD en utilisant l'objet _doc_.
Les résultats de la docstring en ligne sont présentés dans l'écran de la console Spyder suivante. Cette sortie est générée par l'exécution du code apposé ci-dessus dans Spyder:
Exemple 4: Programme d'un docstring multi-ligne Python
Semblable aux docstrings d'une ligne, les docstrings multi-lignes commencent par une ligne de résumé et se terminent par une ligne vide avant de décrire quelque chose plus en détail. La ligne de résumé peut apparaître sur une ligne similaire à celle des citations de début ou sur une autre ligne. Un docstring multiline est démontré dans le cas suivant:
Dans cet exemple particulier, nous avons la définition de la fonction qui reçoit un nom en tant que python_function. Cette fonction prend une valeur d'argument x. Le corps de fonction est déclaré avec la chaîne multi-lignes qui est la description de la valeur de l'argument et du type de données int. Après cela, la commande de retour est définie. Le docstring multiline s'affiche en appelant l'objet _doc_ à l'intérieur de la fonction d'impression.
Les multi-lignes du docstring sont imprimées sur le terminal de Spyder comme suit:
Exemple 5: Programme de l'indentation doctring python
Les citations à sa ligne initiale sont en retrait du même montant que le reste du docstring. Chaque indentation de la première ligne du docstring (avec la première nouvelle ligne) n'est pas nécessaire et devrait être éliminée. Par la suite, les lignes du docstring gardent leur indentation relative. Comme illustration sur la façon de créer les docstrings pour une classe et ses méthodes, regardons un exemple. L'accès au docstring passe par l'aide:
Nous définissons une classe avec la classe de mots clés et nommez cette classe comme my_python_example. À l'intérieur de la classe my_python_example, nous déclarons le docstring qui est entouré par les triples doubles-quotes. Ensuite, nous créons le carré de fonction qui a l'entrée x et la fonction est également déclarée avec le docstring. Ensuite, nous créons une autre fonction avec le nom, Cube. Il prend également une entrée n. Cette fonction est créée pour le cube du numéro. Cette déclaration s'explique par la Déclaration doctring. Après cela, nous avons une fonction d'aide Python pour exécuter la documentation de la classe my_python_program et de la fonction carrée.
À partir du programme Python mentionné précédemment, la sortie suivante répertoriée est obtenue. Cette sortie est générée par l'exécution du code précédemment apposé dans Spyder:
Conclusion
L'objectif principal de ce cours est de vous familiariser avec les docstrings en passant par les idées fondamentales. Cependant, parce que les docstrings sont un sujet si large, il est possible que certaines idées aient été ignorées. Pour obtenir la documentation d'une fonction, utilisez la fonction d'aide (). Mettez une chaîne, soit une chaîne à une seule ligne, soit une chaîne multi-lignes, dans la première ligne de la fonction pour ajouter la documentation.