Все мы периодически нуждаемся в помощи или подсказке. Но не всегда рядом есть люди, которые могли бы подсказать. К счастью, Python предлагает решение и для таких безвыходных ситуаций. При написании кода на Python нам может понадобиться узнать значение определенных ключевых слов, классов, модулей, функций и т. д. В этой статье мы расскажем о функции help() в Python.
Хотите скачать книги по Python в 2 клика? Тогда вам в наш телеграм канал PythonBooks
Что такое функция help() в Python?
Функция help() выводит документацию, созданную для определенного токена языка Python. Под токеном подразумеваются ключевые слова, название классов, модулей Python, функций и так далее. Данную функцию мы можем использовать как в консоли, так и в самом коде наших программ.
Синтаксис функции help() имеет следующий вид:
help(object)
Здесь object — это параметр, который функция help() принимает для предоставления документации об этом конкретном ключевом слове Python либо классе, модуле или функции.
Два способа использования функции help() в Python
Во-первых, функцию help() можно запускать непосредственно из консоли Python.
>>> help(['1', '2', '3'])
или:
>>> help(print)
Во-вторых, данную функцию можно использовать прямо в коде. Но в этом случае help() следует обернуть в функцию print(). Без этого документация не будет отображаться.
print(help(['1', '2', '3']))
или:
a = help(['1', '2', '3']) print(a)
Результат:
Help on list object: class list(object) | list(iterable=(), /) | | Built-in mutable sequence. | | If no argument is given, the constructor creates a new empty list. | The argument must be an iterable if specified. | | Methods defined here: | | __add__(self, value, /) | Return self+value. | | __contains__(self, key, /) | Return key in self. | | __delitem__(self, key, /) | Delete self[key]. | | __eq__(self, value, /) | Return self==value. | | __ge__(self, value, /) | Return self>=value. | | __getattribute__(self, name, /) | Return getattr(self, name). | | __getitem__(...) | x.__getitem__(y) <==> x[y] | | __gt__(self, value, /) | Return self>value. | | __iadd__(self, value, /) | Implement self+=value. | | __imul__(self, value, /) | Implement self*=value. | | __init__(self, /, *args, **kwargs) | Initialize self. See help(type(self)) for accurate signature. | | __iter__(self, /) | Implement iter(self). | | __le__(self, value, /) | Return self<=value. | | __len__(self, /) | Return len(self). | | __lt__(self, value, /) | Return self<value. | | __mul__(self, value, /) | Return self*value. | | __ne__(self, value, /) | Return self!=value. | | __repr__(self, /) | Return repr(self). | | __reversed__(self, /) | Return a reverse iterator over the list. | | __rmul__(self, value, /) | Return value*self. | | __setitem__(self, key, value, /) | Set self[key] to value. | | __sizeof__(self, /) | Return the size of the list in memory, in bytes. | | append(self, object, /) | Append object to the end of the list. | | clear(self, /) | Remove all items from list. | | copy(self, /) | Return a shallow copy of the list. | | count(self, value, /) | Return number of occurrences of value. | | extend(self, iterable, /) | Extend list by appending elements from the iterable. | | index(self, value, start=0, stop=9223372036854775807, /) | Return first index of value. | | Raises ValueError if the value is not present. | | insert(self, index, object, /) | Insert object before index. | | pop(self, index=-1, /) | Remove and return item at index (default last). | | Raises IndexError if list is empty or index is out of range. | | remove(self, value, /) | Remove first occurrence of value. | | Raises ValueError if the value is not present. | | reverse(self, /) | Reverse *IN PLACE*. | | sort(self, /, *, key=None, reverse=False) | Sort the list in ascending order and return None. | | The sort is in-place (i.e. the list itself is modified) and stable (i.e. the | order of two equal elements is maintained). | | If a key function is given, apply it once to each list item and sort them, | ascending or descending, according to their function values. | | The reverse flag can be set to sort in descending order. | | ---------------------------------------------------------------------- | Class methods defined here: | | __class_getitem__(...) from builtins.type | See PEP 585 | | ---------------------------------------------------------------------- | Static methods defined here: | | __new__(*args, **kwargs) from builtins.type | Create and return a new object. See help(type) for accurate signature. | | ---------------------------------------------------------------------- | Data and other attributes defined here: | | __hash__ = None None
Передача строкового аргумента в функцию help()
При передачи строки в функцию help() в качестве параметра она преобразуется в допустимое имя токена Python. Это может быть ключевое слово, модуль, функция, метод, класс или раздел документации. Затем наша функция отобразит связанную с именем строки справочную документацию. Строку в Python допустимо обозначать одинарными или двойными кавычками.
Например:
>>> help('for')
>>> help("def")
Результат:
The "for" statement
*******************
The "for" statement is used to iterate over the elements of a sequence
(such as a string, tuple or list) or other iterable object:
for_stmt ::= "for" target_list "in" expression_list ":" suite
["else" ":" suite]
The expression list is evaluated once; it should yield an iterable
object. An iterator is created for the result of the
"expression_list". The suite is then executed once for each item
provided by the iterator, in the order returned by the iterator. Each
item in turn is assigned to the target list using the standard rules
for assignments (see Assignment statements), and then the suite is
executed. When the items are exhausted (which is immediately when the
sequence is empty or an iterator raises a "StopIteration" exception),
the suite in the "else" clause, if present, is executed, and the loop
terminates.
A "break" statement executed in the first suite terminates the loop
without executing the "else" clause’s suite. A "continue" statement
executed in the first suite skips the rest of the suite and continues
with the next item, or with the "else" clause if there is no next
item.
The for-loop makes assignments to the variables in the target list.
This overwrites all previous assignments to those variables including
those made in the suite of the for-loop:
for i in range(10):
print(i)
i = 5 # this will not affect the for-loop
# because i will be overwritten with the next
# index in the range
Names in the target list are not deleted when the loop is finished,
but if the sequence is empty, they will not have been assigned to at
all by the loop. Hint: the built-in function "range()" returns an
iterator of integers suitable to emulate the effect of Pascal’s "for i
:= a to b do"; e.g., "list(range(3))" returns the list "[0, 1, 2]".
Note:
There is a subtlety when the sequence is being modified by the loop
(this can only occur for mutable sequences, e.g. lists). An
internal counter is used to keep track of which item is used next,
and this is incremented on each iteration. When this counter has
reached the length of the sequence the loop terminates. This means
that if the suite deletes the current (or a previous) item from the
sequence, the next item will be skipped (since it gets the index of
the current item which has already been treated). Likewise, if the
suite inserts an item in the sequence before the current item, the
current item will be treated again the next time through the loop.
This can lead to nasty bugs that can be avoided by making a
temporary copy using a slice of the whole sequence, e.g.,
for x in a[:]:
if x < 0: a.remove(x)
Related help topics: break, continue, while
Использование функции help() с библиотеками Python
Бывают ситуации, когда для корректной работы функции help() требуется сначала импортировать библиотеку, чтобы использовать ее документацию по конкретным методам или функциям данного модуля. Например, данный вызов приведет к ошибке:
print(help(math.log))
В такой ситуации программистам необходимо использовать оператор импорта и включить имя библиотеки в программу. После этого функция help() будет работать нормально, так как библиотека содержит документацию , которая вызывается данной функцией.
import math print(help(math.log))
Результат:
Help on built-in function log in module math:
log(...)
log(x, [base=math.e])
Return the logarithm of x to the given base.
If the base not specified, returns the natural logarithm (base e) of x.
None
Функция help() без аргументов
Функцию help() также можно использовать, не передавая в нее никаких аргументов.
Например:
print(help())
Результат:
Welcome to Python 3.9's help utility! If this is your first time using Python, you should definitely check out the tutorial on the Internet at https://docs.python.org/3.9/tutorial/. Enter the name of any module, keyword, or topic to get help on writing Python programs and using Python modules. To quit this help utility and return to the interpreter, just type "quit". To get a list of available modules, keywords, symbols, or topics, type "modules", "keywords", "symbols", or "topics". Each module also comes with a one-line summary of what it does; to list the modules whose name or summary contain a given string such as "spam", type "modules spam". help>
Теперь в данном разделе вы можете ввести любые нужные ключевые слова, классы, модули, функции и т. д., и будет выведена документация, связанная с этим словом. Например, введем ключевое слово for:
help> for
The "for" statement
*******************
The "for" statement is used to iterate over the elements of a sequence
(such as a string, tuple or list) or other iterable object:
for_stmt ::= "for" target_list "in" expression_list ":" suite
["else" ":" suite]
The expression list is evaluated once; it should yield an iterable
object. An iterator is created for the result of the
"expression_list". The suite is then executed once for each item
provided by the iterator, in the order returned by the iterator. Each
item in turn is assigned to the target list using the standard rules
for assignments (see Assignment statements), and then the suite is
executed. When the items are exhausted (which is immediately when the
sequence is empty or an iterator raises a "StopIteration" exception),
the suite in the "else" clause, if present, is executed, and the loop
terminates.
A "break" statement executed in the first suite terminates the loop
without executing the "else" clause’s suite. A "continue" statement
executed in the first suite skips the rest of the suite and continues
with the next item, or with the "else" clause if there is no next
item.
The for-loop makes assignments to the variables in the target list.
This overwrites all previous assignments to those variables including
those made in the suite of the for-loop:
for i in range(10):
print(i)
i = 5 # this will not affect the for-loop
# because i will be overwritten with the next
# index in the range
Names in the target list are not deleted when the loop is finished,
but if the sequence is empty, they will not have been assigned to at
all by the loop. Hint: the built-in function "range()" returns an
iterator of integers suitable to emulate the effect of Pascal’s "for i
:= a to b do"; e.g., "list(range(3))" returns the list "[0, 1, 2]".
Note:
There is a subtlety when the sequence is being modified by the loop
(this can only occur for mutable sequences, e.g. lists). An
internal counter is used to keep track of which item is used next,
and this is incremented on each iteration. When this counter has
reached the length of the sequence the loop terminates. This means
that if the suite deletes the current (or a previous) item from the
sequence, the next item will be skipped (since it gets the index of
the current item which has already been treated). Likewise, if the
suite inserts an item in the sequence before the current item, the
current item will be treated again the next time through the loop.
This can lead to nasty bugs that can be avoided by making a
temporary copy using a slice of the whole sequence, e.g.,
for x in a[:]:
if x < 0: a.remove(x)
Related help topics: break, continue, while
help>
Создание пользовательской документации при определении функций
Программисты также могут делать документацию для собственных функций. Для этого необходимо создать так называемую строку документации. Она задается при помощи тройных кавычек (т.е. трех пар одинарных или двойных кавычек) сразу после названия функции, метода или класса.
Такая строка будет восприниматься интерпретатором как документация к данной функции или классу.
Например:
def addi(a, b, c):
"""
This function adds three given integers, g, h, and i
:1st param: integer
:2nd param : integer
:3rd param : integer
:returns: integer
"""
return a + b + c
print(help(addi))
Результат:
Help on function addi in module __main__:
addi(a, b, c)
This function adds three given integers, g, h, and i
:1st param: integer
:2nd param : integer
:3rd param : integer
:returns: integer
None
От редакции Pythonist: о строках документации подробнее читайте в статье «Docstrings: документирование кода в Python».
Заключение
Теперь вы познакомились с функцией help() и всегда сможете получить необходимую информацию по всем ключевым словам, функциям и классам языка Python. При помощи данной функции можно легко получить доступ к любой документации Python. Не забывайте использовать ее чаще!
Перевод статьи «Python’s help() Function».
