Python Docstrings (med eksempler)

I denne vejledning lærer vi om Python docstrings. Mere specifikt vil vi lære, hvordan og hvorfor docstrings bruges ved hjælp af eksempler.

Python docstrings er strenglitteralerne, der vises lige efter definitionen af ​​en funktion, metode, klasse eller modul. Lad os tage et eksempel.

Eksempel 1: Docstrings

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

Her er strengen bogstavelig:

 '' Tager et tal n, returnerer kvadratet af n '' '

Inde i de tredobbelte anførselstegn er funktionens doktring , square()som den vises lige efter dens definition.

Bemærk: Vi kan også bruge tredobbelte """tilbud til at oprette docstrings.

Python-kommentarer vs Docstrings

Python-kommentarer

Kommentarer er beskrivelser, der hjælper programmører bedre med at forstå programmets hensigt og funktionalitet. De ignoreres fuldstændigt af Python-tolken.

I Python bruger vi hash-symbolet #til at skrive en kommentar med en linje. For eksempel,

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

Python-kommentarer ved hjælp af strenge

Hvis vi ikke tildeler strenge til nogen variabel, fungerer de som kommentarer. For eksempel,

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

Bemærk: Vi bruger tredobbelt anførselstegn til streng med flere linjer.

Python docstrings

Som nævnt ovenfor er Python docstrings strenge, der bruges lige efter definitionen af ​​en funktion, metode, klasse eller modul (som i eksempel 1 ). De bruges til at dokumentere vores kode.

Vi kan få adgang til disse dokstrings ved hjælp af __doc__attributten.

Python __doc__-attribut

Når strenglitteraler er til stede lige efter definitionen af ​​en funktion, modul, klasse eller metode, er de knyttet til objektet som deres __doc__attribut. Vi kan senere bruge denne attribut til at hente denne dokstring.

Eksempel 2: Udskrivning af dokstring

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

Produktion

 Optager et tal n, returnerer kvadratet af n

Her square()kan du få adgang til dokumentationen for vores funktion ved hjælp af __doc__attributten.

Lad os nu se på dokstrings til den indbyggede funktion print():

Eksempel 3: Docstrings til den indbyggede funktion ()

 print(print.__doc__)

Produktion

print (værdi,…, sep = '', slut = ' n', fil = sys.stdout, flush = Falsk) Udskriver værdierne til en stream eller til sys.stdout som standard. Valgfri søgeordsargumenter: fil: et fillignende objekt (stream); er som standard det aktuelle sys.stdout. sep: streng indsat mellem værdier, standard et mellemrum. slut: streng tilføjet efter den sidste værdi, standard en ny linje. skyl: om strømmen skal tømmes med magt.

Her kan vi se, at dokumentationen af print()funktionen er til stede som __doc__attribut for denne funktion.

Single-line docstrings i Python

Docstrings med en linje er de dokumenter, der passer i en linje.

Standardkonventioner til at skrive enkeltlinjedoktrings:

  • Selvom de er enkeltforede, bruger vi stadig de tredobbelte citater omkring disse dokstrings, da de let kan udvides senere.
  • De afsluttende tilbud er på samme linje som åbningstilbudene.
  • Der er ingen blank linje hverken før eller efter dokstringen.
  • De skal ikke være beskrivende, men snarere skal de følge "Gør dette, returner den" struktur, der slutter med en periode.

Lad os tage et eksempel.

Eksempel 4: Skriv dokumentlinjer med en linje til en funktion

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

Multi-line Docstrings i Python

Multi-line docstrings består af en resumélinie ligesom en line-docstring efterfulgt af en tom linje efterfulgt af en mere detaljeret beskrivelse.

PEP 257-dokumentet indeholder standardkonventionerne til at skrive doktrings med flere linjer til forskellige objekter.

Nogle er nævnt nedenfor:

1. Docstrings til Python-moduler

  • Dokstringene til Python-moduler skal liste alle tilgængelige klasser, funktioner, objekter og undtagelser, der importeres, når modulet importeres.
  • 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

Vi kan også generere dokumentation fra dokstrings ved hjælp af værktøjer som Sphinx. For at lære mere, besøg officiel Sphinx-dokumentation

Interessante artikler...