Строки документации исходного кода на Python. Урок 9

Методическая разработка урока
Элективный курс: Введение в объектно-ориентированное программирование на Python
Уровень: Программирование для начинающих
Версия интерпретатора python: 3.-.-

__doc__ - строки документации

На прошлом уроке мы рассмотрели случай импорта программного кода одного файла в другой. Таким образом, например, один программист может использовать разработки другого. К тому же, существует множество стандартных модулей и библиотек, входящих в установочный пакет интерпретатора python, а также огромное количество модулей сторонних разработчиков. Понятно, что чтобы использовать чужую разработку надо знать, что она делает. Для этого вовсе необязательно анализировать исходный код, поскольку есть инструменты для его документирования, которыми приличные программисты должны регулярно пользоваться. Когда кому-то потребуется узнать, что делает тот или иной скрипт, достаточно будет выполнить специальную команду, которая выдаст описание модуля.

Документировать исходный код на языке программирования Python можно по разному. Иногда бывает достаточно простых комментариев. Еще один способ — это создание строк документации. Они представляют собой текст, заключенный в кавычки (тройные, тройные одинарные, обычные). Такой текст может располагаться после заголовков классов, функций (методов), а также в начале файла (модуля). Пример:

""" Строка документации в начале файла.
     А это ее продолжение с новой строки. """
class … :
     ''' Это строка документирования класса. 
          Причем она заключена в тройные одинарные кавычки...
          или одинарные тройные 0_о '''
     .....
     .....
     def … :
          """ Это документирование модуля.
               Пишите коменты на инглише. """

Для получения доступа к такой документации предусмотрена специальный метод __doc__. Когда интерпретатор Python обрабатывает исходный код класса или функции и обнаруживает там строки документирования, то делает их значением атрибута __doc__ данного объекта.

Чтобы посмотреть как это выглядит, рассмотрим реальный пример. В языке программирования Python строки, списки, числа являются по-сути такими же классами как и пользовательские (создаваемые для специализированного проекта). Данные классы автоматически загружаются (интерпретируются), когда запускается программа-интерпретатор python, поэтому не требуется дополнительный импорт модулей, содержащих их описание. Однако сути это не меняет, и получить доступ к их строкам документации можно также как и к пользовательскому классу (функции, модулю), а именно имяОбъекта.__doc__. Пример:

>>> print (str.__doc__)
str(string[, encoding[, errors]]) -> str
 
Create a new string object from the given encoded string.
encoding defaults to the current default string encoding.
errors can be 'strict', 'replace' or 'ignore' and defaults to 'strict'.

Таким образом, мы получили данные о классе str (описывает атрибуты строк). Однако мы не получили никаких сведений о методах данного класса. Да и вообще: какие методы есть у строк? Тут может помочь встроенная функция dir, которая выводит список переменных (атрибутов) переданного ей аргумента.

>>> dir(str)
['__add__', '__class__', '__contains__', '__delattr__', '__doc__', '__eq__', '__format__', '__ge__', '__getattribute__', '__getitem__', '__getnewargs__', '__gt__', '__hash__', '__init__', '__iter__', '__le__', '__len__', '__lt__', '__mod__', '__mul__', '__ne__', '__new__', '__reduce__', '__reduce_ex__', '__repr__', '__rmod__', '__rmul__', '__setattr__', '__sizeof__', '__str__', '__subclasshook__', '_formatter_field_name_split', '_formatter_parser', 'capitalize', 'center', 'count', 'encode', 'endswith', 'expandtabs', 'find', 'format', 'index', 'isalnum', 'isalpha', 'isdecimal', 'isdigit', 'isidentifier', 'islower', 'isnumeric', 'isprintable', 'isspace', 'istitle', 'isupper', 'join', 'ljust', 'lower', 'lstrip', 'maketrans', 'partition', 'replace', 'rfind', 'rindex', 'rjust', 'rpartition', 'rsplit', 'rstrip', 'split', 'splitlines', 'startswith', 'strip', 'swapcase', 'title', 'translate', 'upper', 'zfill']

Допустим, нас интересует функция метод find, но мы точно не знаем, делает ли он то, что нам нужно. Выяснить это можно так:

>>> print (str.find.__doc__)
S.find(sub[, start[, end]]) -> int
 
Return the lowest index in S where substring sub is found, such that sub is contained within s[start:end]. Optional arguments start and end are interpreted as in slice notation.
 
Return -1 on failure. 

Становятся известны следующие подробности. Оказывается функция find класса str просто возвращает первый индекс подстроки переданной ей в качестве аргумента, если та встречается в строке. По желанию можно указать откуда и докуда искать в исходной строке. Не в тему, но чтобы было понятно:

>>> a = "hello new worlds" # создаем строку
>>> a.find("new") # ищем индекс первого элемента подстроки
6
>>> a.find("l",7) # ищем индекс символа, начиная с 8-го элемента
13

Форматирование строк документирования

Обратите внимание, когда мы вызывали метод __doc__ для объектов, то использовали встроенную функцию print. Зачем? Ведь в интерактивном режиме вывод работает и без print. Однако если при вызове метода __doc__ не использовать функцию print, то вывод не отформатируется, а будет выглядеть как в исходном коде:

>>> str.__doc__
"str(string[, encoding[, errors]]) -> str\n\nCreate a new string object from the given encoded string.\nencoding defaults to the current default string encoding.\nerrors can be 'strict', 'replace' or 'ignore' and defaults to 'strict'."

Обратите внимание на сочетание символов \n. Оно обозначает переход на новую строку. Вообще оформление строк документации должно соответствовать определенному стандарту.

Функция help

Еще более интересный способ получить информацию о модуле или его частях — это использование встроенной функции help. Она выводит текстовый отчет о переданном ей в качестве аргумента объекте. Этот отчет включает не только строки документации, но и структуру запрошенной части кода. т.е. применив функцию help по отношению к объектам мы получим еще и информацию о внутренних функциях и классах.

Практическая работа

  1. Напишите строки документации к программе, созданной на 7 уроке (вычисление площади оклеивания) . Поместите следующую информацию:
    • Модуль. Для чего предназначена данная программа.
    • Классы. Для чего предназначены, какие аргументы передаются методу __init__.
    • Методы (кроме __init__). Назначение, описание входных и выходных данных.
  2. Используя метод __doc__, вызовите в интерактивном режиме строки документации для различных объектов модуля. Предварительно необходимо импортировать модуль (чтобы импортировать его без проблем, поместите файл в каталог установки python).
  3. Примените функцию help для данного модуля. Например, если имя модуля rooms, то вызов справки по нему будет выглядеть так: help (rooms).

Пример документированного исходного кода

"It is the program for definition of quantity of wall-paper"
 
class Win_Door:
     """
Class Win_Door calculates the area of a rectangular.
Method __init__ accepts two parameters: length and width.
     """
     def __init__(self,x,y):
          self.square = x * y
 
class Room:
     """
Class Room is intended for definition of the pasted over area of a room.
Method __init__ accepts three arguments (length, width and height).
     """
     def __init__(self,x,y,z):
          self.square = 2 * z * (x + y)
     def win_door(self, d,e, f,g, m=1,n=1):
          """
The first pair parameters - the sizes of a window,
the second pair - the sizes of a door,
the fifth and sixth parameters - quantity of windows and doors accordingly
          """
          self.window = Win_Door(d,e)
          self.door = Win_Door(f,g)
          self.numb_w = m
          self.numb_d = n
     def wallpapers(self):
          """
This method calculates the pasted over area
          """
          self.wallpapers = self.square - \
               self.window.square * self.numb_w \
               - self.door.square * self.numb_d
     def printer(self):
          """
Displays the information
          """
          print ("Площадь стен комнаты равна "\
          ,str(self.square)," кв.м")
          print ("Оклеиваемая площадь равна: ", \
               str(self.wallpapers), " кв.м")

как поместить файл в каталог

как поместить файл в каталог установки python?
как импортировать модуль?

1.Python x.y/lib , где икс и

1.Python x.y/lib , где икс и игрек - версия твоего питона. Может находится в Programm files
2.приехали. Почитай главу про импорт еще раз.

Чтобы было по-русски, нужно

Чтобы было по-русски, нужно сохранять файлы в кодировке UTF-8, help вообще клевая функция ))