Pokud jde o psaní čistého, dobře zdokumentovaného kódu, vývojáři Pythonu mají k dispozici tajnou zbraň – docstring. Docstrings, zkratka pro dokumentační řetězce, jsou životně důležité při zprostředkování účelu a funkčnosti Krajta funkce, moduly a třídy.
Jaké jsou docstringy v Pythonu?
Krajta dokumentační řetězce (nebo docstrings) poskytují pohodlný způsob, jak přidružit dokumentaci Moduly Pythonu , funkce, třídy a metody. Je specifikováno ve zdrojovém kódu, který se používá jako komentář k dokumentaci konkrétního segmentu kódu. Na rozdíl od konvenčních komentářů ke zdrojovému kódu by měl docstring popisovat, co funkce dělá, ne jak.
- Deklarace Docstrings : Dokumentační řetězce jsou deklarovány pomocí „trojitých jednoduchých uvozovek“ nebo trojitých dvojitých uvozovek těsně pod deklarací třídy, metody nebo funkce. Všechny funkce by měly mít docstring.
- Přístup k Docstrings : K docstrings lze přistupovat pomocí metody __doc__ objektu nebo pomocí funkce nápovědy. Níže uvedené příklady ukazují, jak deklarovat a získat přístup k docstringu.
Jak by měl vypadat docstring?
- Řádek řetězce dokumentu by měl začínat velkým písmenem a končit tečkou.
- První řádek by měl být krátký popis.
- Pokud je v řetězci dokumentace více řádků, druhý řádek by měl být prázdný a vizuálně oddělovat souhrn od zbytku popisu.
- Následující řádky by měly obsahovat jeden nebo více odstavců popisujících konvence volání objektu, vedlejší účinky atd.
Docstrings v Pythonu
Níže jsou uvedena témata, kterými se budeme v tomto článku zabývat:
- Struny s trojitými uvozovkami
- Dokumentační řetězce ve stylu Google
- Docstrings ve stylu Numpydoc
- Jednořádkové Docstrings
- Víceřádkové Docstring
- Odsazení v Docstrings
- Docstrings ve třídách
- Rozdíl mezi komentáři v Pythonu a docstrings
Struny s trojitými uvozovkami
Toto je nejběžnější formát docstring v Pythonu. Zahrnuje použití trojitých uvozovek (buď jednoduchých nebo dvojitých) k uzavření textu dokumentace. Řetězce ve třech uvozovkách mohou zahrnovat více řádků a jsou často umístěny bezprostředně pod definicí funkce, třídy nebo modulu
Příklad 1: Použití trojitých jednoduchých uvozovek
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)> |
>
markdown přeškrtnutí
>
Výstup:
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.>
Příklad 2: Použití trojitých dvojitých uvozovek
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)> |
>
>
Výstup:
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.>
Dokumentační řetězce ve stylu Google
Dokumentační řetězce ve stylu Google mají specifický formát a jsou inspirovány příručkou stylů dokumentace společnosti Google. Poskytují strukturovaný způsob, jak dokumentovat kód Pythonu, včetně parametrů, návratových hodnot a popisů.
Python3
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>))> |
>
j e s t
>Výstup
15>
Docstrings ve stylu Numpydoc
Dokumentační řetězce ve stylu Numpydoc jsou široce používány ve vědecké komunitě a komunitě pro analýzu dat, zejména pro dokumentování funkcí a tříd souvisejících s numerickými výpočty a manipulací s daty. Jedná se o rozšíření dokumentačních řetězců ve stylu Google s některými dalšími konvencemi pro dokumentaci parametrů a návratových hodnot.
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>))> |
>
>Výstup
0.5>
Jednořádkové Docstrings
Jak název napovídá, jednořádkové docstringy se vejdou do jednoho řádku. Používají se ve zřejmých případech. Závěrečné uvozovky jsou na stejném řádku jako úvodní uvozovky. To vypadá lépe pro jednovrstvé. Například:
Python3
def> power(a, b):> > 'Returns arg1 raised to power arg2.'> > >return> a>*>*>b> print>(power.__doc__)> |
>
>
java int v řetězci
Výstup:
Returns arg1 raised to power arg2.>
Víceřádkové Docstring
Víceřádkové dokumentační řetězce se skládají ze souhrnného řádku, stejně jako jednořádkový dokumentační řetězec, za nímž následuje prázdný řádek, po němž následuje propracovanější popis. Souhrnný řádek může být na stejném řádku jako úvodní uvozovky nebo na dalším řádku. Níže uvedený příklad ukazuje víceřádkový dokumentační řetězec.
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>))> |
>
int to char
>
Výstup:
8>
Odsazení v Docstrings
Celý docstring je odsazen stejně jako uvozovky v jeho prvním řádku. Nástroje pro zpracování dokumentačního řetězce odstraní stejnoměrné množství odsazení z druhého a dalších řádků dokumentačního řetězce, které se rovná minimálnímu odsazení všech neprázdných řádků po prvním řádku. Jakékoli odsazení v prvním řádku dokumentačního řetězce (tj. až do prvního nového řádku) je bezvýznamné a je odstraněno. Relativní odsazení pozdějších řádků v dokumentačním řetězci je zachováno.
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)> |
>
>
Výstup:
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 ve třídách
Vezměme si příklad, který ukáže, jak psát docstring pro třídu a metodu ‘ Pomoc' se používá pro přístup k docstringu.
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)> |
heapify třídit
>
>
Výstup:
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.>
Rozdíl mezi komentáři Pythonu, řetězci a řetězci dokumentů
Řetězec: V Pythonu je řetězec posloupností znaků uzavřených v jednoduchých uvozovkách (‘ ‘) nebo dvojitých uvozovkách ( ). Řetězce se používají k reprezentaci textových dat a mohou obsahovat písmena, čísla, symboly a mezery. Jsou jedním ze základních datových typů v Pythonu a lze s nimi manipulovat pomocí různých řetězcových metod.
Všichni jste museli mít představu o dokumentačních řetězcích Pythonu, ale přemýšleli jste někdy, jaký je rozdíl mezi komentáři Pythonu a dokumentačními řetězci? Pojďme se na ně podívat.
Jsou to užitečné informace, které vývojáři poskytují, aby čtenáři porozuměli zdrojovému kódu. Vysvětluje logiku nebo její část použitou v kódu. Je psán pomocí
#>
symboly.
Příklad:
Python3
# Python program to demonstrate comments> print>(>'GFG'>)> name>=> 'Abhishek Shakya'> #demostrate String> |
>
>
Výstup:
GFG>
Zatímco Python Docstrings, jak je uvedeno výše, poskytuje pohodlný způsob, jak přidružit dokumentaci k modulům, funkcím, třídám a metodám Pythonu.