Šajā apmācībā mēs uzzināsim par Python dokstringiem. Konkrētāk, ar piemēru palīdzību mēs uzzināsim, kā un kāpēc tiek izmantotas dokstringas.
Python instrukcijas ir virknes literāļi, kas parādās uzreiz pēc funkcijas, metodes, klases vai moduļa definīcijas. Ņemsim piemēru.
1. piemērs: Instrukcijas
def square(n): '''Takes in a number n, returns the square of n''' return n**2
Virknes burts:
'' 'Ievada skaitli n, atgriež n kvadrātu' ''
Trīskāršu pēdiņu iekšpusē ir funkcijas instrukcija , kas square()parādās uzreiz pēc tās definīcijas.
Piezīme.""" Dokumentu virkņu izveidošanai mēs varam izmantot arī trīskārtīgas pēdiņas.
Python komentāri vs Docstrings
Python komentāri
Komentāri ir apraksti, kas programmētājiem palīdz labāk izprast programmas nolūku un funkcionalitāti. Python tulks tos pilnībā ignorē.
Programmā Python mēs izmantojam jaukšanas simbolu, #lai uzrakstītu vienas rindas komentāru. Piemēram,
# Program to print "Hello World" print("Hello World")
Python komentāri, izmantojot virknes
Ja mēs nepiešķiram virknes nevienam mainīgajam, tie darbojas kā komentāri. Piemēram,
"I am a single-line comment" ''' I am a multi-line comment! ''' print("Hello World")
Piezīme: Mēs izmantojam trīskārtīgas pēdiņas daudzrindu virknēm.
Python instrukcijas
Kā minēts iepriekš, Python docstrings ir virknes, kas tiek izmantotas uzreiz pēc funkcijas, metodes, klases vai moduļa definēšanas (piemēram, 1. piemērā ). Tie tiek izmantoti mūsu koda dokumentēšanai.
Mēs varam piekļūt šīm instrukcijām, izmantojot __doc__atribūtu.
Python __doc__ atribūts
Ikreiz, kad stīgu literāļi atrodas tieši pēc funkcijas, moduļa, klases vai metodes definēšanas, tie tiek saistīti ar objektu kā to __doc__atribūtu. Vēlāk mēs varam izmantot šo atribūtu, lai izgūtu šo dokstringu.
2. piemērs: dokstringu drukāšana
def square(n): '''Takes in a number n, returns the square of n''' return n**2 print(square.__doc__)
Rezultāts
Ievada skaitli n, atgriež n kvadrātu
Šeit mūsu square()funkcijas dokumentācijai var piekļūt, izmantojot __doc__atribūtu.
Tagad aplūkosim iebūvētās funkcijas instrukcijas print():
3. piemērs: iebūvētās print () funkcijas instrukcijas
print(print.__doc__)
Rezultāts
drukāt (vērtība,…, sep = '', beigas = ' n', fails = sys.stdout, flush = nepatiesa) Pēc noklusējuma vērtības izdrukā straumē vai sys.stdout. Izvēles atslēgvārdu argumenti: fails: failam līdzīgs objekts (straume); pēc noklusējuma pašreizējā sys.stdout. sep: virkne ievietota starp vērtībām, pēc noklusējuma atstarpe. beigas: virkne pievienota pēc pēdējās vērtības, pēc noklusējuma - jauna līnija. noskalot: vai straumi izskalot ar varu.
Šeit mēs varam redzēt, ka print()funkcijas dokumentācija ir šīs funkcijas __doc__atribūts.
Vienrindas docstrings Python
Vienas rindas docstrings ir dokumenti, kas ietilpst vienā rindā.
Standarta konvencijas, lai rakstītu vienas rindas rīkus:
- Lai gan tie ir ar vienu rindu, mēs joprojām izmantojam trīskāršās pēdiņas ap šīm instrukcijām, jo vēlāk tās var viegli paplašināt.
- Noslēguma pēdiņas atrodas vienā rindā ar sākuma pēdiņām.
- Ne pirms, ne pēc dokstringa nav tukšas rindas.
- Viņiem nevajadzētu būt aprakstošiem, drīzāk viņiem jāievēro struktūra "Dariet to, atgrieziet to", kas beidzas ar periodu.
Ņemsim piemēru.
4. piemērs: Uzrakstiet funkcijas vienas rindas instrukcijas
def multiplier(a, b): """Takes in two numbers, returns their product.""" return a*b
Daudzrindu Docstrings Python
Daudzrindu docstrings sastāv no kopsavilkuma rindas tāpat kā no vienas rindas docstring, kam seko tukša rinda, kam seko detalizētāks apraksts.
PEP 257 dokuments nodrošina standarta konvencijas, lai rakstītu vairāku rindu instrukcijas dažādiem objektiem.
Daži no tiem ir uzskaitīti zemāk:
1. Instrukcijas Python moduļiem
- Python moduļu instrukcijās jāuzskaita visas pieejamās klases, funkcijas, objekti un izņēmumi, kas tiek importēti, importējot moduli.
- 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ēs varam arī ģenerēt dokumentāciju no docstringiem, izmantojot tādus rīkus kā Sphinx. Lai uzzinātu vairāk, apmeklējiet oficiālo Sfinksas dokumentāciju
