Коли справа доходить до написання чистого, добре задокументованого коду, розробники Python мають у своєму розпорядженні секретну зброю – рядки документації. Рядки документації, скорочення від рядків документації, життєво важливі для передачі мети та функціональності Python функції, модулі та класи.
Що таке рядки документів у Python?
Python рядки документації (або рядки документації) забезпечують зручний спосіб асоціювання документації з Модулі Python , функції, класи та методи. Це вказано у вихідному коді, який використовується, як коментар, для документування певного сегмента коду. На відміну від звичайних коментарів до вихідного коду, рядок документації має описувати, що функція робить, а не як.
- Оголошення Docstrings : Рядки документації оголошуються за допомогою «потрійних одинарних лапок» або потрійних подвійних лапок безпосередньо під оголошенням класу, методу або функції. Усі функції повинні мати рядок документації.
- Доступ до Docstrings : Доступ до рядків документів можна отримати за допомогою методу __doc__ об’єкта або за допомогою функції довідки. Наведені нижче приклади демонструють, як оголосити рядок документації та отримати доступ до неї.
Як має виглядати рядок документації?
- Рядок документа повинен починатися з великої літери і закінчуватися крапкою.
- Перший рядок має бути коротким описом.
- Якщо в рядку документації є більше рядків, другий рядок має бути порожнім, візуально відокремлюючи резюме від решти опису.
- Наступні рядки мають бути одним або декількома абзацами з описом умов виклику об’єкта, побічних ефектів тощо.
Документаційні рядки в Python
Нижче наведено теми, які ми розглянемо в цій статті:
- Рядки в потрійних лапках
- Google Style Docstrings
- Рядки документів у стилі Numpydoc
- Однорядкові рядки документів
- Багаторядкові рядки документів
- Відступи в Docstrings
- Рядки документів у класах
- Різниця між коментарями Python і рядками документації
Рядки в потрійних лапках
Це найпоширеніший формат рядка документів у Python. Він передбачає використання потрійних лапок (одинарних або подвійних) для укладення тексту документації. Рядки в потрійних лапках можуть займати кілька рядків і часто розміщуються безпосередньо під визначенням функції, класу або модуля
приклад 1: Використання потрійних одинарних лапок
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)> |
>
>
Вихід:
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.>
приклад 2: Використання потрійних-дабл лапок
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)> |
>
>
Вихід:
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
Документаційні рядки в стилі Google відповідають певному формату та натхненні посібником зі стилю документації Google. Вони забезпечують структурований спосіб документування коду Python, включаючи параметри, значення, що повертаються, і описи.
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>))> |
>
>
едіт мак гіршВихід
15>
Рядки документів у стилі Numpydoc
Документаційні рядки у стилі Numpydoc широко використовуються в науковому співтоваристві та спільноті аналізу даних, зокрема для документування функцій і класів, пов’язаних із чисельними обчисленнями та маніпулюванням даними. Це розширення рядків документів у стилі Google з деякими додатковими угодами для документування параметрів і значень, що повертаються.
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>))> |
обхід бінарного дерева поштою
>
>Вихід
0.5>
Однорядкові рядки документів
Як випливає з назви, однорядкові рядки документів поміщаються в один рядок. Вони використовуються в очевидних випадках. Закриваючі лапки знаходяться в одному рядку з початковими. Це виглядає краще для однорядкових. Наприклад:
Python3
def> power(a, b):> >' '> 'Returns arg1 raised to power arg2.'> ' '> > >return> a>*>*>b> print>(power.__doc__)> |
>
>
Вихід:
Returns arg1 raised to power arg2.>
Багаторядкові рядки документів
Багаторядкові рядки документації складаються з підсумкового рядка, як і однорядковий рядок документації, за яким іде порожній рядок, після якого йде детальніший опис. Підсумковий рядок може бути в одному рядку з початковими лапками або в наступному рядку. У прикладі нижче показано багаторядковий рядок документації.
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>))> |
>
>
Вихід:
8>
Відступи в Docstrings
Весь рядок документа має такий самий відступ, як і лапки в його першому рядку. Інструменти обробки рядка документації знімуть рівномірний відступ із другого та подальших рядків рядка документації, що дорівнює мінімальному відступу всіх непорожніх рядків після першого рядка. Будь-який відступ у першому рядку рядка документації (тобто до першого нового рядка) є незначним і видаляється. Відносний відступ наступних рядків у рядку документації зберігається.
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)> |
>
>
Вихід:
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.>
Рядки документів у класах
Розглянемо приклад, щоб показати, як написати рядки документації для класу та методу ‘ допомогти' використовується для доступу до рядка документації.
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)> |
>
>
Вихід:
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.>
Різниця між коментарями Python, String і Docstrings
Рядок: у Python рядок — це послідовність символів, укладених в одинарні лапки (‘ ‘) або подвійні лапки ( ). Рядки використовуються для представлення текстових даних і можуть містити літери, цифри, символи та пробіли. Вони є одним із основних типів даних у Python, і ними можна маніпулювати за допомогою різних методів рядків.
Ви, напевно, маєте уявлення про рядки документів Python, але чи замислювалися ви коли-небудь про різницю між коментарями Python і рядками документів? Давайте подивимося на них.
java int у рядку
Це корисна інформація, яку розробники надають, щоб читач міг зрозуміти вихідний код. Він пояснює логіку або її частину, яка використовується в коді. Він написаний за допомогою
#>
символи.
приклад:
Python3
# Python program to demonstrate comments> print>(>'GFG'>)> name>=> 'Abhishek Shakya'> #demostrate String> |
>
>
Вихід:
GFG>
У той час як Python Docstrings, як згадувалося вище, забезпечує зручний спосіб зв’язування документації з модулями, функціями, класами та методами Python.