Python Docstrings (s príkladmi)

V tomto tutoriále sa dozvieme o docstrings Pythonu. Konkrétnejšie sa dozvieme, ako a prečo sa dokumenty docring používajú, pomocou príkladov.

Dokumentačné reťazce Pythonu sú reťazcové literály, ktoré sa objavia hneď po definovaní funkcie, metódy, triedy alebo modulu. Zoberme si príklad.

Príklad 1: Docstrings

 def square(n): '''Takes in a number n, returns the square of n''' return n**2

Reťazcový literál:

 '' 'Prijme číslo n, vráti štvorček n' ''

V trojitých úvodzovkách je dokumentačný reťazec funkcie, square()ktorý sa zobrazuje hneď po jej definovaní.

Poznámka: Na """vytvorenie docstrings môžeme použiť aj trojité ponuky.

Komentáre Pythonu proti Docstrings

Komentáre Pythonu

Komentáre sú popisy, ktoré pomáhajú programátorom lepšie pochopiť zámer a funkčnosť programu. Sú interpretom Pythonu úplne ignorovaní.

V Pythone používame hash symbol #na napísanie jednoriadkového komentára. Napríklad,

 # Program to print "Hello World" print("Hello World")

Poznámky v jazyku Python pomocou reťazcov

Ak nepriradíme reťazce k žiadnej premennej, fungujú ako komentáre. Napríklad,

 "I am a single-line comment" ''' I am a multi-line comment! ''' print("Hello World")

Poznámka: Pre viacriadkové reťazce používame trojité úvodzovky.

Python docstrings

Ako už bolo spomenuté vyššie, dokumentačné reťazce Python sú reťazce používané hneď po definovaní funkcie, metódy, triedy alebo modulu (ako v príklade 1 ). Používajú sa na zdokumentovanie nášho kódu.

K týmto dokumentom môžeme získať prístup pomocou __doc__atribútu.

Atribút Python __doc__

Kedykoľvek sú reťazcové literály bezprostredne po definovaní funkcie, modulu, triedy alebo metódy, sú spojené s objektom ako ich __doc__atribút. Tento atribút môžeme neskôr použiť na získanie tohto dokumentačného reťazca.

Príklad 2: Tlač dokumentu

 def square(n): '''Takes in a number n, returns the square of n''' return n**2 print(square.__doc__)

Výkon

 Prijme číslo n, vráti druhú mocninu n

Tu square()je možné pomocou __doc__atribútu získať prístup k dokumentácii k našej funkcii .

Teraz sa pozrime na docstrings pre vstavanú funkciu print():

Príklad 3: Docstrings pre vstavanú funkciu print ()

 print(print.__doc__)

Výkon

print (value,…, sep = '', end = ' n', file = sys.stdout, flush = False) Vytlačí hodnoty do streamu alebo štandardne do sys.stdout. Nepovinné argumenty kľúčového slova: file: objekt podobný súboru (stream); predvolené nastavenie na aktuálny sys.stdout. sep: reťazec vložený medzi hodnoty, predvolená medzera. koniec: reťazec pripojený za poslednou hodnotou, predvolený nový riadok. splachovanie: či násilím spláchnuť prúd.

Tu vidíme, že dokumentácia print()funkcie je prítomná ako __doc__atribút tejto funkcie.

Jednoriadkové dokumenty v jazyku Python

Jednoriadkové dokumentačné reťazce sú dokumenty, ktoré sa zmestia do jedného riadku.

Štandardné konvencie na písanie jednoriadkových dokumentov:

  • Aj keď sú jednoradové, stále používame trojité úvodzovky okolo týchto dokumentov, pretože je možné ich neskôr ľahko rozšíriť.
  • Záverečné úvodzovky sú na rovnakom riadku ako úvodné úvodzovky.
  • Pred dokumentom alebo za ním nie je prázdny riadok.
  • Nemali by byť popisné, skôr sa musia riadiť štruktúrou „Urob to, vráť túto“ končiac bodkou.

Zoberme si príklad.

Príklad 4: Napíšte jednoriadkové dokumentačné reťazce pre funkciu

 def multiplier(a, b): """Takes in two numbers, returns their product.""" return a*b

Viacriadkové dokumenty v jazyku Python

Viacriadkové dokumentačné reťazce pozostávajú zo súhrnného riadku rovnako ako jednoriadkový dokumentový reťazec, za ktorým nasleduje prázdny riadok a za ktorým nasleduje podrobnejší popis.

Dokument PEP 257 poskytuje štandardné konvencie na písanie viacriadkových dokumentov pre rôzne objekty.

Niektoré sú uvedené nižšie:

1. Docstrings pre moduly Python

  • V dokumentácii pre moduly Python by mali byť uvedené všetky dostupné triedy, funkcie, objekty a výnimky, ktoré sa importujú pri importe modulu.
  • They should also have a one-line summary for each item.

They are written at the beginning of the Python file.

Let's look at the docstrings for the builtin module in Python called pickle.

Example 4: Docstrings of Python module

 import pickle print(pickle.__doc__)

Output

 Create portable serialized representations of Python objects. See module copyreg for a mechanism for registering custom picklers. See module pickletools source for extensive comments. Classes: Pickler Unpickler Functions: dump(object, file) dumps(object) -> string load(file) -> object loads(string) -> object Misc variables: __version__ format_version compatible_formats

Here, we can see that the docstring written at the beginning of the pickle.py module file can be accessed as its docstring.

2. Docstrings for Python Functions

  • The docstring for a function or method should summarize its behavior and document its arguments and return values.
  • It should also list all the exceptions that can be raised and other optional arguments.

Example 5: Docstrings for Python functions

 def add_binary(a, b): ''' Returns the sum of two decimal numbers in binary digits. Parameters: a (int): A decimal integer b (int): Another decimal integer Returns: binary_sum (str): Binary string of the sum of a and b ''' binary_sum = bin(a+b)(2:) return binary_sum print(add_binary.__doc__)

Output

 Returns the sum of two decimal numbers in binary digits. Parameters: a (int): A decimal integer b (int): Another decimal integer Returns: binary_sum (str): Binary string of the sum of a and b

As you can see, we have included a short description of what the function does, the parameter it takes in and the value it returns. The string literal is embedded to the function add_binary as its __doc__ attribute.

3. Docstrings for Python Classes

  • The docstrings for classes should summarize its behavior and list the public methods and instance variables.
  • The subclasses, constructors, and methods should each have their own docstrings.

Example 6: Docstrings for Python class

Suppose we have a Person.py file with the following code:

 class Person: """ A class to represent a person.… Attributes ---------- name : str first name of the person surname : str family name of the person age : int age of the person Methods ------- info(additional=""): Prints the person's name and age. """ def __init__(self, name, surname, age): """ Constructs all the necessary attributes for the person object. Parameters ---------- name : str first name of the person surname : str family name of the person age : int age of the person """ self.name = name self.surname = surname self.age = age def info(self, additional=""): """ Prints the person's name and age. If the argument 'additional' is passed, then it is appended after the main info. Parameters ---------- additional : str, optional More info to be displayed (default is None) Returns ------- None """ print(f'My name is (self.name) (self.surname). I am (self.age) years old.' + additional)

Here, we can use the following code to access only the docstrings of the Person class:

 print(Person.__doc__)

Output

 A class to represent a person.… Attributes ---------- name : str first name of the person surname : str family name of the person age : int age of the person Methods ------- info(additional=""): Prints the person's name and age

Using the help() Function for Docstrings

We can also use the help() function to read the docstrings associated with various objects.

Example 7: Read Docstrings with the help() function

We can use the help() function on the class Person in Example 6 as:

 help(Person)

Output

 Help on class Person in module __main__: class Person(builtins.object) | Person(name, surname, age) | | A class to represent a person. | |… | | Attributes | ---------- | name : str | first name of the person | surname : str | family name of the person | age : int | age of the person | | Methods | ------- | info(additional=""): | Prints the person's name and age. | | Methods defined here: | | __init__(self, name, surname, age) | Constructs all the necessary attributes for the person object. | | Parameters | ---------- | name : str | first name of the person | surname : str | family name of the person | age : int | age of the person | | info(self, additional='') | Prints the person's name and age. | | If the argument 'additional' is passed, then it is appended after the main info. | | Parameters | ---------- | additional : str, optional | More info to be displayed (default is None) | | Returns | ------- | None | | ---------------------------------------------------------------------- | Data descriptors defined here: | | __dict__ | dictionary for instance variables (if defined) | | __weakref__ | list of weak references to the object (if defined)

Here, we can see that the help() function retrieves the docstrings of the Person class along with the methods associated with that class.

4. Docstrings for Python Scripts

  • The docstrings for Python script should document the script's functions and command-line syntax as a usable message.
  • It should serve as a quick reference to all the functions and arguments.

5. Docstrings for Python Packages

The docstrings for a Python package is written in the package's __init__.py file.

  • It should contain all the available modules and sub-packages exported by the package.

Docstring Formats

We can write docstring in many formats like the reStructured text (reST) format, Google format or the NumPy documentation format. To learn more, visit Popular Docstring Formats

Môžeme tiež generovať dokumentáciu z docstrings pomocou nástrojov ako Sphinx. Ak sa chcete dozvedieť viac, navštívte oficiálnu dokumentáciu Sfingy

Zaujímavé články...