Quan es tracta d'escriure codi net i ben documentat, els desenvolupadors de Python tenen una arma secreta a la seva disposició: docstrings. Docstrings, abreviatura de cadenes de documentació, són vitals per transmetre el propòsit i la funcionalitat de Python funcions, mòduls i classes.
Quines són les docstrings a Python?
Python les cadenes de documentació (o cadenes de documents) proporcionen una manera còmoda d'associar la documentació amb Mòduls Python , funcions, classes i mètodes. S'especifica al codi font que s'utilitza, com un comentari, per documentar un segment específic de codi. A diferència dels comentaris del codi font convencional, la cadena de documents hauria de descriure què fa la funció, no com.
- Declaració de Docstrings : Les cadenes de documents es declaren utilitzant 'cometes simples triples' o cometes dobles triples just a sota de la declaració de classe, mètode o funció. Totes les funcions haurien de tenir una cadena de documents.
- Accés a Docstrings : Es pot accedir a les cadenes de documents mitjançant el mètode __doc__ de l'objecte o mitjançant la funció d'ajuda. Els exemples següents mostren com declarar i accedir a una cadena de documents.
Com hauria de ser una cadena documental?
- La línia de la cadena de document ha de començar amb una lletra majúscula i acabar amb un punt.
- La primera línia hauria de ser una breu descripció.
- Si hi ha més línies a la cadena de documentació, la segona línia ha d'estar en blanc, separant visualment el resum de la resta de la descripció.
- Les línies següents haurien de ser un o més paràgrafs que descriguin les convencions de trucada de l'objecte, els efectes secundaris, etc.
Docstrings en Python
A continuació es mostren els temes que tractarem en aquest article:
- Cordes de cometes triples
- Google Style Docstrings
- Cadenas documentals d'estil Numpydoc
- Docstrings d'una línia
- Docstrings multilínia
- Sagnat a Docstrings
- Docstrings a les classes
- Diferència entre comentaris de Python i docstrings
Cordes de cometes triples
Aquest és el format docstring més comú a Python. Implica utilitzar cometes triples (simples o dobles) per adjuntar el text de la documentació. Les cadenes entre cometes triples poden abastar diverses línies i sovint es col·loquen immediatament a sota de la definició de funció, classe o mòdul
Exemple 1: Ús de cometes simples triples
què és el mòdul en c++
Python 3
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)> |
>
>
Sortida:
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: Ús de cometes triples-dobles
Python 3
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)> |
>
>
Sortida:
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.>
Google Style Docstrings
Els documents d'estil de Google segueixen un format específic i s'inspiren en la guia d'estil de documentació de Google. Proporcionen una manera estructurada de documentar el codi Python, inclosos paràmetres, valors de retorn i descripcions.
Python 3
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>))> |
>
>Sortida
15>
Cadenas documentals d'estil Numpydoc
Les cadenes documentals d'estil Numpydoc s'utilitzen àmpliament a la comunitat científica i d'anàlisi de dades, especialment per documentar funcions i classes relacionades amb càlculs numèrics i manipulació de dades. És una extensió de docstrings a l'estil de Google, amb algunes convencions addicionals per documentar paràmetres i valors de retorn.
Python 3
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>))> |
>
>Sortida
0.5>
Docstrings d'una línia
Com el seu nom indica, les cadenes de documents d'una línia encaixen en una línia. S'utilitzen en casos evidents. Les cometes de tancament estan a la mateixa línia que les cometes inicials. Això sembla millor per a una sola línia. Per exemple:
Python 3
def> power(a, b):> >' '> 'Returns arg1 raised to power arg2.'> ' '> > >return> a>*>*>b> print>(power.__doc__)> |
>
>
Sortida:
Returns arg1 raised to power arg2.>
Docstrings multilínia
Les cadenes de documents de diverses línies consisteixen en una línia de resum igual que una cadena de documents d'una línia, seguida d'una línia en blanc, seguida d'una descripció més elaborada. La línia de resum pot estar a la mateixa línia que les cometes inicials o a la línia següent. L'exemple següent mostra una cadena de documents de diverses línies.
Python 3
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>))> |
>
>
Sortida:
8>
Sagnat a Docstrings
Tota la docstring està sagnada igual que les cometes de la seva primera línia. Les eines de processament de Docstring eliminaran una quantitat uniforme de sagnat de la segona i les línies posteriors de la docstring, igual al sagnat mínim de totes les línies no en blanc després de la primera línia. Qualsevol sagnat a la primera línia de la cadena documental (és a dir, fins a la primera línia nova) és insignificant i s'elimina. Es manté el sagnat relatiu de les línies posteriors a la docstring.
Python 3
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)> |
>
>
Sortida:
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 a les classes
Prenguem un exemple per mostrar com escriure docstrings per a una classe i el mètode ' ajuda' s'utilitza per accedir a la cadena de documents.
Python 3
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)> |
>
>
Sortida:
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.>
Diferència entre comentaris de Python, String i Docstrings
Cadena: a Python, una cadena és una seqüència de caràcters tancada entre cometes simples (‘ ‘) o cometes dobles ( ). Les cadenes s'utilitzen per representar dades de text i poden contenir lletres, números, símbols i espais en blanc. Són un dels tipus de dades fonamentals de Python i es poden manipular mitjançant diversos mètodes de cadena.
Tots heu de tenir una idea sobre les docstrings de Python, però us heu preguntat mai quina és la diferència entre els comentaris de Python i les docstrings? Fem-los una ullada.
Són informació útil que els desenvolupadors proporcionen per fer que el lector entengui el codi font. Explica la lògica o una part d'ella utilitzada al codi. S'escriu utilitzant
#>
símbols.
Exemple:
Python 3
# Python program to demonstrate comments> print>(>'GFG'>)> name>=> 'Abhishek Shakya'> #demostrate String> |
>
>
Sortida:
GFG>
Mentre que Python Docstrings, com s'ha esmentat anteriorment, ofereix una manera còmoda d'associar documentació amb mòduls, funcions, classes i mètodes de Python.