In diesem Tutorial lernen wir Python-Dokumentzeichenfolgen kennen. Im Einzelnen erfahren wir anhand von Beispielen, wie und warum Docstrings verwendet werden.
Python-Dokumentzeichenfolgen sind die Zeichenfolgenliterale, die direkt nach der Definition einer Funktion, Methode, Klasse oder eines Moduls angezeigt werden. Nehmen wir ein Beispiel.
Beispiel 1: Docstrings
def square(n): '''Takes in a number n, returns the square of n''' return n**2
Hier das String-Literal:
'' 'Nimmt eine Zahl n auf und gibt das Quadrat von n' '' zurück.
Innerhalb der dreifachen Anführungszeichen befindet sich die Dokumentzeichenfolge der Funktion, square()wie sie direkt nach ihrer Definition angezeigt wird.
Hinweis: Wir können auch dreifache """Anführungszeichen verwenden, um Dokumentzeichenfolgen zu erstellen.
Python-Kommentare gegen Docstrings
Python-Kommentare
Kommentare sind Beschreibungen, die Programmierern helfen, die Absicht und Funktionalität des Programms besser zu verstehen. Sie werden vom Python-Interpreter vollständig ignoriert.
In Python verwenden wir das Hash-Symbol #, um einen einzeiligen Kommentar zu schreiben. Beispielsweise,
# Program to print "Hello World" print("Hello World")
Python-Kommentare mit Strings
Wenn wir keiner Variablen Zeichenfolgen zuweisen, dienen sie als Kommentare. Beispielsweise,
"I am a single-line comment" ''' I am a multi-line comment! ''' print("Hello World")
Hinweis: Wir verwenden dreifache Anführungszeichen für mehrzeilige Zeichenfolgen.
Python-Dokumentzeichenfolgen
Wie oben erwähnt, sind Python-Dokumentzeichenfolgen Zeichenfolgen, die direkt nach der Definition einer Funktion, Methode, Klasse oder eines Moduls verwendet werden (wie in Beispiel 1 ). Sie werden verwendet, um unseren Code zu dokumentieren.
Wir können über das __doc__Attribut auf diese Dokumentzeichenfolgen zugreifen .
Python __doc__ Attribut
Wenn Zeichenfolgenliterale unmittelbar nach der Definition einer Funktion, eines Moduls, einer Klasse oder einer Methode vorhanden sind, werden sie dem Objekt als __doc__Attribut zugeordnet. Wir können dieses Attribut später verwenden, um diese Dokumentzeichenfolge abzurufen.
Beispiel 2: Dokumentstring drucken
def square(n): '''Takes in a number n, returns the square of n''' return n**2 print(square.__doc__)
Ausgabe
Nimmt eine Zahl n auf und gibt das Quadrat von n zurück
Hier square()kann über das __doc__Attribut auf die Dokumentation unserer Funktion zugegriffen werden .
Schauen wir uns nun die Dokumentzeichenfolgen für die integrierte Funktion an print():
Beispiel 3: Docstrings für die integrierte Funktion print ()
print(print.__doc__)
Ausgabe
print (Wert,…, sep = '', end = ' n', file = sys.stdout, flush = False) Druckt die Werte standardmäßig in einen Stream oder in sys.stdout. Optionale Schlüsselwortargumente: Datei: ein dateiähnliches Objekt (Stream); Standardmäßig wird die aktuelle sys.stdout verwendet. sep: Zeichenfolge zwischen Werten eingefügt, standardmäßig ein Leerzeichen. end: Zeichenfolge, die nach dem letzten Wert angehängt wird, standardmäßig eine neue Zeile. Flush: Gibt an, ob der Stream zwangsweise gespült werden soll.
Hier können wir sehen, dass die Dokumentation der print()Funktion als __doc__Attribut dieser Funktion vorhanden ist.
Einzeilige Dokumentzeichenfolgen in Python
Einzeilige Dokumentzeichenfolgen sind die Dokumente, die in eine Zeile passen.
Standardkonventionen zum Schreiben einzeiliger Dokumentzeichenfolgen:
- Obwohl sie einzeilig sind, verwenden wir immer noch die dreifachen Anführungszeichen um diese Dokumentzeichenfolgen, da sie später leicht erweitert werden können.
- Die Schlusszitate befinden sich in derselben Zeile wie die Eröffnungszitate.
- Es gibt weder vor noch nach der Dokumentzeichenfolge eine Leerzeile.
- Sie sollten nicht beschreibend sein, sondern müssen der Struktur "Tun Sie dies, geben Sie das zurück" folgen, die mit einem Punkt endet.
Nehmen wir ein Beispiel.
Beispiel 4: Schreiben Sie einzeilige Dokumentzeichenfolgen für eine Funktion
def multiplier(a, b): """Takes in two numbers, returns their product.""" return a*b
Mehrzeilige Docstrings in Python
Mehrzeilige Dokumentzeichenfolgen bestehen aus einer Zusammenfassungszeile wie eine einzeilige Dokumentzeichenfolge, gefolgt von einer Leerzeile und einer ausführlicheren Beschreibung.
Das PEP 257-Dokument enthält die Standardkonventionen zum Schreiben mehrzeiliger Dokumentzeichenfolgen für verschiedene Objekte.
Einige wurden unten aufgeführt:
1. Docstrings für Python-Module
- Die Dokumentzeichenfolgen für Python-Module sollten alle verfügbaren Klassen, Funktionen, Objekte und Ausnahmen auflisten, die beim Import des Moduls importiert werden.
- Sie sollten auch eine einzeilige Zusammenfassung für jeden Artikel haben.
Sie werden am Anfang der Python-Datei geschrieben.
Schauen wir uns die Docstrings für das eingebaute Modul in Python an pickle.
Beispiel 4: Docstrings des Python-Moduls
import pickle print(pickle.__doc__)
Ausgabe
Erstellen Sie tragbare serialisierte Darstellungen von Python-Objekten. Unter Modul copyreg finden Sie einen Mechanismus zum Registrieren von benutzerdefinierten Picklern. Ausführliche Kommentare finden Sie in der Quelle für Modul-Pickletools. Klassen: Pickler Unpickler Funktionen: dump (Objekt, Datei) dumps (Objekt) -> Laden von Zeichenfolgen (Datei) -> Laden von Objekten (Zeichenfolge) -> Objekt Verschiedene Variablen: __version__ format_version compatible_formats
Hier können wir sehen, dass auf die am Anfang der Datei pickle.py geschriebene Dokumentzeichenfolge als Dokumentzeichenfolge zugegriffen werden kann.
2. Docstrings für Python-Funktionen
- 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
Wir können auch Dokumentation aus Dokumentzeichenfolgen mit Tools wie Sphinx generieren. Weitere Informationen finden Sie in der offiziellen Sphinx-Dokumentation
