Python Docstrings (s příklady)

V tomto kurzu se dozvíme o pythonových řetězcích. Konkrétněji se pomocí příkladů dozvíme, jak a proč se používají docstrings.

Python docstrings jsou řetězcové literály, které se objevují hned po definici funkce, metody, třídy nebo modulu. Vezměme si příklad.

Příklad 1: Docstrings

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

Zde je doslovný řetězec:

 '' 'Přijme číslo n, vrátí druhou mocninu n' ''

Uvnitř trojitých uvozovek je dokumentační řetězec funkce, square()jak se objevuje hned po její definici.

Poznámka: Můžeme také použít trojité """nabídky k vytvoření dokumentů.

Komentáře Pythonu vs Docstrings

Komentáře Pythonu

Komentáře jsou popisy, které pomáhají programátorům lépe porozumět záměru a funkčnosti programu. Překladač Pythonu je zcela ignoruje.

V Pythonu používáme hash symbol #k napsání jednořádkového komentáře. Například,

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

Komentáře Pythonu pomocí řetězců

Pokud žádné proměnné nepřiřadíme řetězce, budou fungovat jako komentáře. Například,

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

Poznámka: U víceřádkových řetězců používáme trojité uvozovky.

Python docstrings

Jak již bylo zmíněno výše, pythonové docstrings jsou řetězce používané hned po definici funkce, metody, třídy nebo modulu (jako v příkladu 1 ). Používají se k dokumentaci našeho kódu.

K těmto dokumentům můžeme přistupovat pomocí __doc__atributu.

Atribut Python __doc__

Kdykoli jsou řetězcové literály k dispozici hned po definici funkce, modulu, třídy nebo metody, jsou přidruženy k objektu jako jejich __doc__atribut. Tento atribut můžeme později použít k načtení tohoto dokumentu.

Příklad 2: Tisk dokumentu

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

Výstup

 Přijme číslo n, vrátí druhou mocninu n

Zde lze k dokumentaci naší square()funkce přistupovat pomocí __doc__atributu.

Nyní se podívejme na docstrings pro vestavěnou funkci print():

Příklad 3: Docstrings pro vestavěnou funkci print ()

 print(print.__doc__)

Výstup

print (value,…, sep = '', end = ' n', file = sys.stdout, flush = False) Ve výchozím nastavení vytiskne hodnoty do proudu nebo do sys.stdout. Nepovinné argumenty klíčových slov: file: objekt podobný souboru (stream); výchozí nastavení aktuálního sys.stdout. sep: řetězec vložený mezi hodnoty, výchozí mezera. konec: řetězec připojený za poslední hodnotou, výchozí nový řádek. flush: zda násilně propláchnout proud.

Zde vidíme, že dokumentace print()funkce je přítomna jako __doc__atribut této funkce.

Jednořádkové dokumenty v Pythonu

Jednořádkové dokumenty jsou dokumenty, které se vejdou do jednoho řádku.

Standardní konvence pro psaní jednořádkových dokumentů:

  • I když jsou jednořádkové, stále používáme trojité uvozovky kolem těchto dokumentů, protože je lze později snadno rozšířit.
  • The closing quotes are on the same line as the opening quotes.
  • There's no blank line either before or after the docstring.
  • They should not be descriptive, rather they must follow "Do this, return that" structure ending with a period.

Let's take an example.

Example 4: Write single-line docstrings for a function

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

Multi-line Docstrings in Python

Multi-line docstrings consist of a summary line just like a one-line docstring, followed by a blank line, followed by a more elaborate description.

The PEP 257 document provides the standard conventions to write multi-line docstrings for various objects.

Some have been listed below:

1. Docstrings for Python Modules

  • The docstrings for Python Modules should list all the available classes, functions, objects and exceptions that are imported when the module is imported.
  • 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 také generovat dokumentaci z docstrings pomocí nástrojů, jako je Sphinx. Další informace najdete v oficiální dokumentaci Sphinx

Zajímavé články...