Python Docstrings (med exempel)

I den här handledningen lär vi oss om Python docstrings. Mer specifikt lär vi oss hur och varför docstrings används med hjälp av exempel.

Python docstrings är stränglitteralerna som visas direkt efter definitionen av en funktion, metod, klass eller modul. Låt oss ta ett exempel.

Exempel 1: Docstrings

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

Här är strängen bokstavlig:

 '' 'Tar in ett nummer n, returnerar kvadratet av n' ''

Inuti de tre citattecknen finns funktionens funktion square()som den visas direkt efter dess definition.

Obs! Vi kan också använda trippel """citat för att skapa docstrings.

Python-kommentarer mot Docstrings

Python-kommentarer

Kommentarer är beskrivningar som hjälper programmerare att bättre förstå programmets avsikt och funktionalitet. De ignoreras helt av Python-tolk.

I Python använder vi hash-symbolen för #att skriva en enradig kommentar. Till exempel,

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

Python-kommentarer med hjälp av strängar

Om vi ​​inte tilldelar strängar till någon variabel fungerar de som kommentarer. Till exempel,

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

Obs! Vi använder trippel citattecken för strängar med flera rader.

Python docstrings

Som nämnts ovan är Python docstrings strängar som används direkt efter definitionen av en funktion, metod, klass eller modul (som i exempel 1 ). De används för att dokumentera vår kod.

Vi kan komma åt dessa docstrings med __doc__attributet.

Python __doc__-attribut

När stränglitterärer finns precis efter definitionen av en funktion, modul, klass eller metod, associeras de med objektet som __doc__attribut. Vi kan senare använda detta attribut för att hämta den här doktringen.

Exempel 2: Skriva ut docstring

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

Produktion

 Tar ett nummer n, returnerar kvadraten på n

Här kan du komma åt dokumentationen för vår square()funktion med __doc__attributet.

Låt oss nu titta på docstrings för den inbyggda funktionen print():

Exempel 3: Doksträngar för den inbyggda funktionen ()

 print(print.__doc__)

Produktion

skriv ut (värde,…, sep = '', slut = ' n', fil = sys.stdout, flush = Falskt) Skriver ut värdena till en ström eller till sys.stdout som standard. Valfria argument för nyckelord: fil: ett filliknande objekt (ström); standardvärdena för nuvarande sys.stdout. sep: sträng infogad mellan värden, standard ett mellanslag. slut: sträng läggs till efter det sista värdet, standard en ny rad. spola: om du ska spola strömmen med våld.

Här kan vi se att dokumentationen för print()funktionen finns som __doc__attribut för denna funktion.

Enstaka docstrings i Python

Enstaka rader är de dokument som passar i en rad.

Standardkonventioner för att skriva enradiga docstrings:

  • Även om de är enkelfodrade, använder vi fortfarande de trefaldiga citaten runt dessa docstrings eftersom de lätt kan utvidgas senare.
  • De avslutande offerten är på samma rad som de inledande offerten.
  • Det finns ingen tom rad varken före eller efter doktringen.
  • De ska inte vara beskrivande, utan de måste följa strukturen "Gör detta, returnera den" som slutar med en period.

Låt oss ta ett exempel.

Exempel 4: Skriv dokumentlinjer med en rad för 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 av en sammanfattningsrad precis som en en-line docstring, följt av en tom rad följt av en mer detaljerad beskrivning.

PEP 257-dokumentet tillhandahåller standardkonventionerna för att skriva flerlinjiga docstrings för olika objekt.

Några har listats nedan:

1. Docstrings för Python-moduler

  • Dokstrings för Python-moduler bör lista alla tillgängliga klasser, funktioner, objekt och undantag som importeras när modulen importeras.
  • 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 också generera dokumentation från docstrings med hjälp av verktyg som Sphinx. För att lära dig mer, besök officiell sfinxdokumentation

Intressanta artiklar...