Питхон доцстрингс (са примерима)

У овом упутству ћемо научити о Питхон документима. Конкретније, научићемо како и зашто се доцстрингс користе уз помоћ примера.

Питхон доцстрингс су низ литерала који се појављују одмах након дефиниције функције, методе, класе или модула. Узмимо пример.

Пример 1: Доктринси

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

Овде је дословни низ:

 '' 'Узима број н, враћа квадрат од н' ''

Унутар троструких наводника налази се документни низ функције square()онако како се појављује одмах након њене дефиниције.

Напомена: Такође можемо користити троструке """цитате за креирање доцстрингс-а.

Питхон Цомментс вс Доцстрингс

Питхон коментари

Коментари су описи који помажу програмерима да боље разумеју намеру и функционалност програма. Они су потпуно игнорисани од стране тумача Питхон.

У Питхону користимо хеш симбол #да напишемо једноредни коментар. На пример,

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

Питхон коментарише помоћу стрингова

Ако не доделимо низове било којој променљивој, они ће деловати као коментари. На пример,

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

Напомена: Користимо троструке наводнике за вишередне низове.

Питхон доцстрингс

Као што је горе поменуто, Питхон доцстрингс су низови који се користе одмах након дефиниције функције, методе, класе или модула (као у примеру 1 ). Користе се за документовање нашег кода.

Овим документима можемо приступити помоћу __doc__атрибута.

Питхон __доц__ атрибут

Кад год су стринг литерали присутни непосредно након дефиниције функције, модула, класе или методе, они су повезани са објектом као својим __doc__атрибутом. Касније можемо да користимо овај атрибут за преузимање ове доцстринг-а.

Пример 2: Штампање доцстринг-а

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

Оутпут

 Узима број н, враћа квадрат од н

Овде се документацији наше square()функције може приступити помоћу __doc__атрибута.

Сада, погледајмо доцстрингс за уграђену функцију print():

Пример 3: Доктринси за уграђену функцију принт ()

 print(print.__doc__)

Оутпут

принт (валуе,…, сеп = '', енд = ' н', филе = сис.стдоут, флусх = Фалсе) Штампа вредности у ток или по подразумеваном сис.стдоут. Необавезни аргументи кључних речи: датотека: објект сличан датотеци (ток); подразумевано је тренутни сис.стдоут. сеп: низ уметнут између вредности, подразумевано размак. крај: низ додан после последње вредности, подразумевано нови ред. испирање: да ли насилно испрати поток.

Овде можемо видети да је документација print()функције присутна као __doc__атрибут ове функције.

Једноредни доцстрингс у Питхону

Једноредни документи су документи који стану у један ред.

Стандардне конвенције за писање једноредних доцстрингс:

  • Иако су једнослојни, и даље користимо троструке цитате око ових докумената, јер се касније могу лако проширити.
  • Завршни цитати налазе се у истој линији као и почетни цитати.
  • Не постоји празан ред ни пре ни после доцстринга.
  • Не би смели бити описни, већ морају следити структуру „Уради ово, врати оно“ која се завршава тачком.

Узмимо пример.

Пример 4: Напишите функцију доцстрингс у једном реду

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

Вишередни доцстрингс у Питхону

Низови докумената са више редова састоје се од сажетог реда, баш као и низ редака у једном реду, празан редом, након чега следи детаљнији опис.

Документ ПЕП 257 пружа стандардне конвенције за писање вишередних докумената за различите објекте.

Неки су наведени у наставку:

1. Документација за Питхон модуле

  • Доцстрингс за Питхон модуле требају навести све доступне класе, функције, објекте и изузетке који се увозе приликом увоза модула.
  • 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

Такође можемо генерисати документацију из доцстрингс-а користећи алате као што је Спхинк. Да бисте сазнали више, посетите званичну документацију о Сфинги

Занимљиви Чланци...