- Документирование кода в Python
- Docstring
- Документация для классов
- Документация для пакетов
- Документация для модулей
- Форматы Docstring
- Вывод документации на экран — help() и __doc__
- Pydoc
- Вывод текста документации
- Поиск по документации
- HTTP сервер с документацией
- Запись документации в файл
- Автодокументирование кода
- Функция help() в Python: вызов справки
- Что такое help() в Python?
- Синтаксис
- Параметры
- object передается в help()
- Строка передается в качестве аргумента
- Определение help() для пользовательского класса и функций
- Python help() function
- Python help() function
- Defining help() for custom class and functions
- Summary
Документирование кода в Python
Документирование кода — неотъемлемая часть разработки на Python. Порой документации в коде может быть больше, чем самого кода. Она помогает понять, что делает функция или класс, какие аргументы принимает и что возвращает.
Когда документация и код находятся в разных местах, сопровождать их становиться довольно тяжело. Поэтому на практике документация находится непосредственно рядом с кодом.
Docstring
Docstring — это строковый литерал, который расположен сразу за объявлением модуля, функции, класса или метода. О том, какие существуют соглашения в документировании Python кода описано в документации PEP257 .
Документация для классов
Документация класса создается для самого класса, а также для его методов.
class Speaker: «»»Это docstring класса Speaker»»» def say_something(self): «»»Это docstring метода»»» print(«something»)
После строки документации нужно оставлять пустую строку
Документация для класса может содержать следующую информацию:
- краткое описание класса (+ его поведение);
- описание атрибутов класса;
- описание публичных методов;
- все, что связано с интерфейсом для подклассов.
Для методов класса документация может содержать:
- краткое описание метода (+ его поведение);
- описание аргументов метода;
- побочные эффекты (если таковые возникают при выполнении метода);
- исключения.
Ниже — пример с более подробной документацией класса:
class TextSplitter: «»»Класс TextSplitter используется для разбивки текста на слова Основное применение — парсинг логов на отдельные элементы по указанному разделителю. Note: Возможны проблемы с кодировкой в Windows Attributes ———- file_path : str полный путь до текстового файла lines : list список строк исходного файла Methods ——- load() Читает файл и сохраняет его в виде списка строк в lines get_splitted(split_symbol=» «) Разделяет строки списка по указанному разделителю и возвращает результат в виде списка «»» def __init__(self, file_path: str): self.file_path = file_path.strip() self.lines = [] def load(self) -> None: «»»Метод для загрузки файла в список строк lines Raises —— Exception Если файл пустой вызовется исключение «»» with open(self.file_path, encoding=»utf-8″) as f: for line in f: self.lines.append(line.rstrip(‘\n’)) if len(self.lines) == 0: raise Exception(f»file is empty») def get_splitted(self, split_symbol: str = » «) -> list: «»»Разбивает текстовые строки lines, преобразуя строку в список слов по разделителю Если аргумент split_symbol не задан, в качестве разделителя используется пробел Parameters ———- split_symbol : str, optional разделитель «»» split_list = [] for str_line in self.lines: split_list.append(str_line.split(split_symbol)) return split_list
Документация для пакетов
Документация пакета размещается в файле __init__.py в верхней части файла (начиная с 1-й строки). В ней может быть указано:
- описание пакета;
- список модулей и пакетов, экспортируемых этим модулем;
- автор;
- контактные данные;
- лицензия.
Документация для модулей
Документация модулей аналогична документации классов. Вместо класса и методов в данном случае документируется модуль со всеми его функциями. Размещается в верхней части файла (начиная с 1-й строки).
Форматы Docstring
Строки документации могут иметь различное форматирование. В примере выше мы использовали стиль NumPy. Существуют и другие форматы:
Вывод документации на экран — help() и __doc__
Строки документации доступны:
Выведем документацию с помощью функции help()
>>> import my_module >>> help(my_module) Help on module test: NAME test — Это docstring модуля, он однострочный. FILE /var/www/test.py CLASSES MyClass class MyClass | Это docstring класса. | | Methods defined here: | | my_method(self) | Это docstring метода FUNCTIONS my_function(a) Это многострочный docstring для функции my_function. В многострочном docstring первое предложение кратко описывает работу функции.
Также можно выводить документацию отдельного объекта:
>>> import my_module >>> my_module.__doc__ >>> my_module.my_function.__doc__ >>> my_module.MyClass.__doc__ >>> my_module.MyClass.my_method.__doc__
Pydoc
Для более удобной работы с документацией, в Python существует встроенная библиотека pydoc.
Pydoc автоматически генерирует документацию из Python модулей. Информацию по доступным командам модуля pydoc можно получить набрав в терминале:
Разберем подробнее, что умеет pydoc.
Вывод текста документации
pydoc — покажет текст документации указанного модуля, пакета, функции, класса и т.д. Если содержит «\», Python будет искать документацию по указанному пути.
Для примера, посмотрим документацию встроенного модуля math:
python -m pydoc math Help on built-in module math: NAME math DESCRIPTION This module provides access to the mathematical functions defined by the C standard. FUNCTIONS acos(x, /) Return the arc cosine (measured in radians) of x. acosh(x, /) Return the inverse hyperbolic cosine of x. .
В консоль выведется название модуля, его описание и описание всех функций в модуле.
Поиск по документации
pydoc -k — найдет ключевое слово в документации всех доступных модулей.
Допустим, нам нужно распаковать gzip файл. Поищем слово » gzip «:
python -m pydoc -k gzip _compression — Internal classes used by the gzip, lzma and bz2 modules gzip — Functions that read and write gzipped files. test.test_gzip — Test script for the gzip module.
В списке мы видим модуль gzip . Теперь можно посмотреть его документацию:
python -m pydoc gzip Help on module gzip: NAME gzip — Functions that read and write gzipped files. DESCRIPTION The user of the file doesn’t have to worry about the compression, but random access is not allowed.
По описанию, данный модуль решит нашу задачу.
HTTP сервер с документацией
Для удобства просмотра документации, pydoc позволяет одной командой создать HTTP-сервер:
python -m pydoc -p 331 Server ready at http://localhost:331/ Server commands: [b]rowser, [q]uit server>
Теперь можно перейти в браузер и зайти на http://localhost:331/
Для остановки сервера введите » q » и нажмите » Enter «:
Также HTTP-сервер доступен через python -m pydoc -b – эта команда создаст сервер на свободном порту, откроет браузер и перейдет на нужную страницу.
Запись документации в файл
python -m pydoc -w sqlite3 — запишем файл с документацией по модулю sqlite3 в html файл.
Автодокументирование кода
Для того чтобы облегчить написание документации и улучшить ее в целом, существуют различные Python-пакеты. Один из них — pyment .
Pyment работает следующим образом:
- Анализирует один или несколько скриптов.
- Получает существующие строки документации.
- Генерирует отформатированные строки документации со всеми параметрами, значениями по умолчанию и т.д.
- Далее вы можете применить сгенерированные строки к своим файлам.
Этот инструмент особенно полезен когда код плохо задокументирован, или когда документация вовсе отсутствует. Также pyment будет полезен в команде разработчиков для форматирования документации в едином стиле.
pyment myfile.py # для файла pyment -w myfile.py # для файла + запись в файл pyment my/folder/ # для всех файлов в папке
Для большинства IDE также существуют плагины, помогающие документировать код:
В PyCharm существует встроенный функционал добавления документации к коду. Для этого нужно:
- Переместить курсор под объявление функции.
- Написать тройные кавычки «»» и нажмите » Enter» .
Функция help() в Python: вызов справки
Когда вам нужна помощь в написании программы, использовании модулей, а также для вызова справки рекомендуется использовать функцию help() в Python.
Что такое help() в Python?
help() в Python — это встроенный метод, который используется для интерактивного использования. Функция help() используется для получения документации по указанному модулю, классу, функции, переменным и т.д.
Синтаксис
В справочной консоли мы можем указать имена модулей, классов и функций, чтобы получить их документацию.
Теперь перейдите в терминал или консоль CMD и введите следующую команду.
На данный момент версия Python3 является последней, поэтому введите python3, и вы увидите то, что показано ниже.
Теперь введите функцию help().
Теперь мы можем проверить следующие встроенные функции и модули.
Допустим, мы вводим коллекции, а затем получаем следующий вывод в консоли.
Параметры
Метод help() принимает максимум один параметр.
object передается в help()
Введите следующую команду.
Строка передается в качестве аргумента
Если строка передается в качестве аргумента, данная строка ищется как имя модуля, функции, класса, метода, ключевого слова или раздела документации, и печатается страница справки.
Если вы хотите выйти из справочной консоли, введите команду quit.
Определение help() для пользовательского класса и функций
Мы можем определить вывод функции help() для наших пользовательских классов и функций, указав docstring (строку документации).
По умолчанию в качестве строки документации используется первая строка комментария в теле метода. Его окружают три двойных кавычки.
Допустим, у нас есть файл python help_examples.py со следующим кодом.
Python help() function
While we believe that this content benefits our community, we have not yet thoroughly reviewed it. If you have any suggestions for improvements, please let us know by clicking the “report an issue“ button at the bottom of the tutorial.
Python help() function is used to get the documentation of specified module, class, function, variables etc. This method is generally used with python interpreter console to get details about python objects.
Python help() function
If no argument is given, the interactive help system starts on the interpreter console. In python help console, we can specify module, class, function names to get their help documentation. Some of them are:
help> True help> collections help> builtins help> modules help> keywords help> symbols help> topics help> LOOPING
If you want to get out of help console, type quit . We can also get the help documentation directly from the python console by passing a parameter to help() function.
>>> help('collections') >>> help(print) >>> help(globals)
>>> help('builtins.globals') Help on built-in function globals in builtins: builtins.globals = globals() Return the dictionary containing the current scope's global variables. NOTE: Updates to this dictionary *will* affect name lookups in the current global scope and vice-versa.
Defining help() for custom class and functions
We can define help() function output for our custom classes and functions by defining docstring (documentation string). By default, the first comment string in the body of a method is used as its docstring. It’s surrounded by three double quotes. Let’s say we have a python file python_help_examples.py with following code.
def add(x, y): """ This function adds the given integer arguments :param x: integer :param y: integer :return: integer """ return x + y class Employee: """ Employee class, mapped to "employee" table in Database """ name = '' def __init__(self, i, n): """ Employee object constructor :param i: integer, must be positive :param n: string """ self.id = i self.name = n
Notice that we have defined docstring for function, class and its methods. You should follow some format for documentation, I have generated some part of them automatically using PyCharm IDE. NumPy docstring guide is a good place to get some idea around proper way of help documentation. Let’s see how to get this docstring as help documentation in python console. First of all, we will have to execute this script in the console to load our function and class definition. We can do this using exec() command.
>>> exec(open("python_help_examples.py").read())
>>> globals() , '__spec__': None, '__annotations__': <>, '__builtins__': , '__warningregistry__': , 'add': , 'Employee': >
Notice that ‘Employee’ and ‘add’ are present in the global scope dictionary. Now we can get the help documentation using help() function. Let’s look at some of the examples.
>>> help('python_help_examples.add') Help on function add in python_help_examples: python_help_examples.add = add(x, y) This function adds the given integer arguments :param x: integer :param y: integer :return: integer (END)
>>> help('python_help_examples.Employee')
>>> help('python_help_examples.Employee.__init__') Help on function __init__ in python_help_examples.Employee: python_help_examples.Employee.__init__ = __init__(self, i, n) Employee object constructor :param i: integer, must be positive :param n: string (END)
Summary
Python help() function is very helpful to get the details about modules, classes, and functions. It’s always best practice to define docstring for the custom classes and functions to explain their usage. You can checkout complete python script and more Python examples from our GitHub Repository. Reference: Official Documentation
Thanks for learning with the DigitalOcean Community. Check out our offerings for compute, storage, networking, and managed databases. Learn more about us