Документирование кода в python

Самый простой способ документирования программного кода — использование комментариев. Для этого используется знак #. Весь текст до конца строки, следующий за этим знаком, игнорируется.
Кроме этого существуют другие способы документирования программного кода.В коде программы на Python можно использовать строки, которые автоматически помещаются в атрибут __doc__ объекта и становятся доступны сразу после импортирования модуля. Например, файл example.py содержит код


"""
Description of the module
"""

def func1():
    """
    Decription of the function func1() 
    """
    pass
 
def hello():
    "Function hello print string 'Hello, World!'"
    print 'Hello, World'


Импортируем этот модуль

$ python
>>> import example
>>> print example.__doc__

Description of the module
 
>>> print example.func1.__doc__

Decription of the function func1() 
        
>>> print example.hello.__doc__
Function hello print string 'Hello, World!'
>>>


Для упрощения отображения документации удобное использовать встроенную функцию help.

$ python
>>> import example
>>> help(example)
Help on module example:
 
NAME
    example - Description of the module
 
FILE
    .../example.py
 
FUNCTIONS
    func1()
        Decription of the function func1()
 
    hello()
        Function hello print string 'Hello, World!'
 
(END)


Для прекращения работы встроенной функции help необходимо нажать клавишу q.
Для получения списка атрибутов объекта можно использовать функцию dir().

>>> dir(math)
['__doc__', '__file__', '__name__', 'acos', 'asin', 'atan', 'atan2', 
'ceil', 'cos', 'cosh', 'degrees', 'e', 'exp', 'fabs', 'floor', 
'fmod', 'frexp', 'hypot', 'ldexp', 'log', 'log10', 'modf', 'pi', 
'pow', 'radians', 'sin', 'sinh', 'sqrt', 'tan', 'tanh']
>>> dir([])
['__add__', '__class__', '__contains__', '__delattr__', '__delitem__', 
'__delslice__', '__doc__', '__eq__', '__ge__', '__getattribute__', 
'__getitem__', '__getslice__', '__gt__', '__hash__', '__iadd__', 
'__imul__', '__init__', '__iter__', '__le__', '__len__', '__lt__', 
'__mul__', '__ne__', '__new__', '__reduce__', '__reduce_ex__', '__repr__', 
'__reversed__', '__rmul__', '__setattr__', '__setitem__', '__setslice__', 
'__str__', 'append', 'count', 'extend', 'index', 'insert', 'pop', 
'remove', 'reverse', 'sort']


Список атрибутов модуля хранится в виде словаря. Для получения этого списка можно использовать атрибут __dict__.

>>> math.__dict__.keys()
['pow', 'cosh', 'ldexp', 'hypot', 'tan', 'asin', 'log', 'fabs', 'floor', 
'sqrt', 'frexp', 'degrees', 'pi', 'log10', '__doc__', 'fmod', 'atan', 
'__file__', 'ceil', 'sinh', '__name__', 'cos', 'e', 'tanh', 'radians', 
'sin', 'atan2', 'modf', 'exp', 'acos']
>>>

  • avatar
  • 0

0 комментариев

Только зарегистрированные и авторизованные пользователи могут оставлять комментарии.