Help: примеры (PYTHON)

Простые примеры использования

Пример запуска интерактивной справки:

>>> help()

Добро пожаловать в службу помощи Python 3.11!...Введите имя любого модуля, ключевого слова или темы для получения справки.

Пример получения справки по встроенной функции:

>>> help(len)

Help on built-in function len in module builtins:
len(obj, /)
    Return the number of items in a container.

Пример получения справки по ключевому слову:

>>> help('if')

The "if" statement
******************
The "if" statement is used for conditional execution:...

Пример получения справки по модулю:

>>> import math
>>> help(math)

Help on module math:
NAME
    math
MODULE REFERENCE...

Похожие средства в Python

1. Функция dir(): Возвращает список допустимых атрибутов для объекта. Полезна для исследования структуры модуля или объекта. В отличие от help(), она не предоставляет подробных описаний, а только имена.

>>> dir(str)
['__add__', '__class__', ..., 'upper', 'zfill']

2. Свойство __doc__: Содержит строку документации (docstring) объекта. Это позволяет получить справку в виде строки для дальнейшей программной обработки, а не только для вывода.

>>> print(len.__doc__)
Return the number of items in a container.

3. Модуль pydoc: Предоставляет те же возможности, что и help(), но из командной строки операционной системы (например, python -m pydoc math) или для генерации HTML-документации. Функция help() фактически является интерфейсом к этому модулю.

Аналоги функции в других языках

JavaScript: Прямого аналога в стандартной библиотеке нет. Интерактивная документация обычно доступна через инструменты разработчика в браузере или IDE. Для Node.js можно использовать комментарии JSDoc.

Java: Интерактивной помощи нет. Документация (Javadoc) генерируется из комментариев в исходном коде и просматривается как отдельный HTML-сайт.

PHP: Функция phpinfo() выводит информацию о конфигурации, а для документации по функциям используется команда в оболочке: php --rf 'function_name'.

$ php --rf 'strlen'

Function [ <internal:standard> function strlen ] {
  - Parameters [1] {
    Parameter #0 [ <required> $string ]
  }
}

C#: В среде разработки Visual Studio используется IntelliSense - контекстные подсказки при наборе кода. Через командную строку можно использовать утилиту dotnet tool для работы с документацией.

SQL: В различных СУБД существуют свои команды, например, в PostgreSQL - \h для справки по командам и \? для справки по метакомандам в оболочке psql.

Go: Команда go doc в терминале позволяет получить документацию по пакетам и символам.

go doc fmt.Println

package fmt // import "fmt"
func Println(a ...any) (n int, err error)
    Println formats using the default formats for its operands and writes to
    standard output.

Lua: Прямого аналога нет. Документация обычно поставляется в виде текстовых файлов или доступна через сторонние инструменты.

Kotlin: В IDE IntelliJ IDEA используется встроенная система документации при наведении курсора. Отдельной интерактивной функции в языке нет.

Типичные ошибки и особенности

1. Попытка получить справку для объекта без документации. В этом случае вывод может быть минимальным или содержать только автоматически сгенерированную информацию.

>>> x = 5
>>> help(x)

Help on int object:
class int(object)
 |  int([x]) -> integer...
(Выводится общая справка по классу int, а не по конкретному числу 5).

2. Ошибка при указании несуществующего имени. В интерактивном режиме система предложит попробовать снова. При вызове с аргументом-строкой, которая не является именем существующего объекта, будет выведено соответствующее сообщение.

>>> help('несуществующий_модуль')

No Python documentation found for 'несуществующий_модуль'.

3. Ожидание, что help() вернёт строку. Функция всегда возвращает None и только выводит текст. Для программного использования документации нужен атрибут __doc__ или модуль pydoc.

>>> result = help(len)
>>> print(result)

None

Изменения в последних версиях

В Python 3.10 были улучшения в представлении информации для некоторых встроенных функций и классов, но сама функция help() не претерпела значительных синтаксических изменений. Основные обновления касаются модуля pydoc, который стоит за её работой: улучшена обработка декораторов, добавлена поддержка новых возможностей языка. В Python 3.11 и 3.12 продолжается развитие механизмов генерации документации для повышения её читабельности и полноты.

Расширенные примеры использования

Пример получения справки по собственному классу с документирующей строкой:

class MyClass:
    """Это демонстрационный класс.

    Он не выполняет полезной работы,
    только показывает работу help().
    """
    def method(self):
        """Этот метод также имеет документацию."""
        pass

help(MyClass)

Help on class MyClass in module __main__:
class MyClass(builtins.object)
 |  Это демонстрационный класс.
 |
 |  Он не выполняет полезной работы,
 |  только показывает работу help().
 |
 |  Methods defined here:
 |
 |  method(self)
 |      Этот метод также имеет документацию.

Пример исследования цепочки наследования через help():

class Parent:
    pass
class Child(Parent):
    pass

help(Child)

Help on class Child in module __main__:
class Child(Parent)
 |  Method resolution order:
 |      Child
 |      Parent
 |      builtins.object
 |  ...

Использование help() для просмотра документации по конкретному методу строки:

help(str.upper)

Help on method_descriptor:
upper(self, /)
    Return a copy of the string converted to uppercase.

Получение справки по теме, например, по операторам:

>>> help('SLICING')

Slicing
*******
A slicing selects a range of items in a sequence object (e.g., a string, tuple or list)...