Автор оригинала: Nicholas Samuel.
Справочная система Python
При написании и запуске программ на Python вы можете застрять и нуждаться в помощи. Возможно, вам потребуется знать значение определенных модулей, классов, функций, ключевых слов и т. Д. Хорошей новостью является то, что Python поставляется со встроенной справочной системой. Это означает, что вам не нужно искать помощи за пределами самого Python.
В этой статье вы узнаете, как использовать встроенную справочную систему Python.
Функция Python help()
Эта функция помогает нам получить документацию по определенному классу, функции, переменной, модулю и т. Д. Эта функция должна использоваться на консоли Python для получения подробной информации о различных объектах Python.
Передача объекта в функцию help()
Функция Python help() имеет следующий синтаксис:
>>> help(object)
В приведенном выше синтаксисе параметр object – это имя объекта, о котором вам нужно получить справку.
Например, чтобы узнать больше о функции Python print , введите следующую команду в консоли Python:
>>> help(print)
Выход:
Help on built-in function print in module builtins:
print(...)
print(value, ..., sep=' ', end='\n', file=sys.stdout, flush=False)
Prints the values to a stream, or to sys.stdout by default.
Optional keyword arguments:
file: a file-like object (stream); defaults to the current sys.stdout.
sep: string inserted between values, default a space.
end: string appended after the last value, default a newline.
flush: whether to forcibly flush the stream.
Чтобы получить справку для класса dict , введите в консоли Python следующее:
>>> help(dict)
Выход:
Help on class dict in module builtins:
class dict(object)
| dict() -> new empty dictionary
| dict(mapping) -> new dictionary initialized from a mapping object's
| (key, value) pairs
| dict(iterable) -> new dictionary initialized as if via:
| d = {}
| for k, v in iterable:
| d[k] = v
| dict(**kwargs) -> new dictionary initialized with the name=value pairs
| in the keyword argument list. For example: dict(one=1, two=2)
|
| Methods defined here:
|
| __contains__(self, key, /)
| True if D has a key k, else False.
|
| __delitem__(self, key, /)
| Delete self[key].
|
| __eq__(self, value, /)
| Return self==value.
|
| __ge__(self, value, /)
| Return self>=value.
|
...
Вы также можете передать фактический объект списка в функцию help() :
>>> help(['a', 'b', 'c'])
Выход:
Help on list object: class list(object) | list() -> new empty list | list(iterable) -> new list initialized from iterable's items | | 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). ...
Мы видим, что при передаче объекта в функцию help() печатается его документация или страница справки. В следующем разделе вы узнаете о передаче строковых аргументов функции help () .
Передача строкового аргумента в помощь()
Если вы передадите строку в качестве аргумента, она будет рассматриваться как имя функции, модуля, ключевого слова, метода, класса или раздела документации, и будет напечатана соответствующая страница справки. Чтобы пометить его как строковый аргумент, заключите его в одинарные или двойные кавычки.
Например:
>>> help('print')
Выход:
Help on built-in function print in module builtins:
print(...)
print(value, ..., sep=' ', end='\n', file=sys.stdout, flush=False)
Prints the values to a stream, or to sys.stdout by default.
Optional keyword arguments:
file: a file-like object (stream); defaults to the current sys.stdout.
sep: string inserted between values, default a space.
end: string appended after the last value, default a newline.
flush: whether to forcibly flush the stream.
Хотя мы передали ‘print’ в качестве строкового аргумента, у нас все еще есть документация для функции Python print . Вот еще один пример:
>>> help('def')
Выход:
Function definitions
********************
A function definition defines a user-defined function object (see
section *The standard type hierarchy*):
funcdef ::= [decorators] "def" funcname "(" [parameter_list] ")" ["->" expression] ":" suite
decorators ::= decorator+
decorator ::= "@" dotted_name ["(" [parameter_list [","]] ")"] NEWLINE
dotted_name ::= identifier ("." identifier)*
parameter_list ::= (defparameter ",")*
| "*" [parameter] ("," defparameter)* ["," "**" parameter]
| "**" parameter
| defparameter [","] )
parameter ::= identifier [":" expression]
defparameter ::= parameter ["=" expression]
funcname ::= identifier
A function definition is an executable statement. Its execution binds
the function name in the current local namespace to a function object
(a wrapper around the executable code for the function). This
...
Здесь мы передали “def” в качестве строкового аргумента функции help () , и она вернула документацию для определения функций.
Если соответствующий объект, метод, функция, класс или модуль не найдены, вы будете уведомлены. Например:
>>> help('qwerty')
Выход:
No Python documentation found for 'qwerty'. Use help() to get the interactive help utility. Use help(str) for help on the str class.
Мы уведомлены, что для нашей строки не было найдено никакой документации.
Иногда нам может понадобиться помощь по поводу определенной функции, определенной в определенной библиотеке Python. Это требует, чтобы мы сначала импортировали библиотеку. Хороший пример-это когда нам нужно получить документацию для функции log , определенной в библиотеке Python math . В этом случае нам сначала нужно импортировать библиотеку math , а затем вызвать функцию help () , как показано ниже:
>>> from math import log >>> help(log)
Выход:
Help on built-in function log in module math:
log(...)
log(x[, base])
Return the logarithm of x to the given base.
If the base not specified, returns the natural logarithm (base e) of x.
Использование help() без аргумента
Функция help() может использоваться без аргумента. Если вы запустите функцию без аргумента, то на консоли интерпретатора будет запущена интерактивная утилита справки Python. Вам просто нужно ввести следующую команду на консоли Python:
>>> help()
Это вернет утилиту справки Python, в которой вы можете ввести имя объекта, о котором вам нужно получить справку. Например:
help> print
Выход:
Help on built-in function print in module builtins:
print(...)
print(value, ..., sep=' ', end='\n', file=sys.stdout, flush=False)
Prints the values to a stream, or to sys.stdout by default.
Optional keyword arguments:
file: a file-like object (stream); defaults to the current sys.stdout.
sep: string inserted between values, default a space.
end: string appended after the last value, default a newline.
flush: whether to forcibly flush the stream.
Чтобы вернуться к предыдущему приглашению, просто нажмите “q”.
Вот еще один пример:
help> return
Выход:
The "return" statement ********************** return_stmt ::= "return" [expression_list] "return" may only occur syntactically nested in a function definition, not within a nested class definition. If an expression list is present, it is evaluated, else "None" is substituted. "return" leaves the current function call with the expression list (or "None") as return value. When "return" passes control out of a "try" statement with a "finally" clause, that "finally" clause is executed before really leaving the function. In a generator function, the "return" statement indicates that the generator is done and will cause "StopIteration" to be raised. The returned value (if any) is used as an argument to construct "StopIteration" and becomes the "StopIteration.value" attribute. Related help topics: FUNCTIONS
Чтобы выйти из утилиты справки и вернуться в консоль Python, просто введите “quit” и нажмите клавишу enter:
help> quit
Выход:
You are now leaving help and returning to the Python interpreter.
If you want to ask for help on a particular object directly from the
interpreter, you can type "help(object)". Executing "help('string')"
has the same effect as typing a particular string at the help> prompt.
>>>
В следующем разделе мы обсудим, как определить help() для наших пользовательских объектов.
Определение справочных документов для пользовательских функций и классов
Мы можем определить выходные данные функции help() для наших пользовательских функций и классов, определив docstring (строку документа). В Python первая строка комментария, добавленная в тело метода, рассматривается как его docstring. Комментарий должен быть окружен тремя двойными кавычками. Например:
def product(a, b):
"""
This function multiplies two given integers, a and b
:param x: integer
:param y: integer
:returns: integer
"""
return a * b
В приведенном выше примере мы определили функцию с именем product . Эта функция умножает два целочисленных значения, a и b переданные ей в качестве аргументов/параметров. См. комментарий, заключенный в три двойные кавычки:
"""
This function multiplies two given integers, a and b
:param x: integer
:param y: integer
:returns: integer
"""
Это будет рассматриваться как docstring для функции product .
Теперь создайте новый файл и дайте ему имя “myfile.py”. Добавьте в файл следующий код:
def product(a, b):
"""
This function multiplies two given integers, a and b
:param x: integer
:param y: integer
:returns: integer
"""
return a * b
class Student:
"""
Student class in Python. It will store student details
"""
admission = 0
name = ''
def __init__(self, adm, n):
"""
A constructor of the student object
:param adm: a positive integer,
:param n: a string
"""
self.admission = adm
self.name = n
В приведенном выше примере строка документа была определена для функции, класса и методов.
Теперь нам нужно продемонстрировать, как мы можем получить вышеприведенную строку документа в качестве справочной документации на нашей консоли Python.
Во-первых, нам нужно выполнить скрипт на консоли, чтобы загрузить как функцию, так и определение класса в среду Python. Для этого мы можем использовать метод Python exec () . Выполните следующую команду на консоли Python:
>>> exec(open("myfile.py").read())
В качестве альтернативы, если вы написали код в Python IDLE, вам просто нужно его запустить.
Теперь мы можем подтвердить, были ли обнаружены модули функций и классов, выполнив команду globals() на консоли Python:
>>> globals()
В моем случае я получаю следующий вывод:
{'__doc__': None, 'log': , '__builtins__': , '__spec__': None, '__package__': None, '__name__': '__main__', '__loader__': , '__file__': 'C:/Users/admin/myfile.py', 'Student': }
Как показано в приведенном выше выводе, и Student , и product находятся в глобальном словаре scope. Теперь мы можем использовать функцию help () , чтобы получить справку для Student class и product function. Просто выполните следующую команду на консоли Python:
>>> help('myfile')
Выход:
Help on module myfile:
NAME
myfile
CLASSES
builtins.object
Student
class Student(builtins.object)
| Student class in Python. It will store student details
|
| Methods defined here:
|
| __init__(self, adm, n)
| A constructor of the student object
| :param adm: a positive integer,
| :param n: a string
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables (if defined)
|
| __weakref__
| list of weak references to the object (if defined)
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| admission = 0
|
| name = ''
FUNCTIONS
product(a, b)
This function multiplies two given integers, a and b
:param x: integer
:param y: integer
:returns: integer
FILE
c:\users\admin\myfile.py
Давайте проверим справочную документацию для функции product :
>>> help('myfile.product')
Выход:
Help on function product in myfile:
myfile.product = product(a, b)
This function multiplies two given integers, a and b
:param x: integer
:param y: integer
:returns: integer
Теперь давайте обратимся к справочной документации для класса Student :
>>> help('myfile.Student')
Выход:
Help on class Student in myfile: myfile.Student = class Student(builtins.object) | Student class in Python. It will store student details | | Methods defined here: | | __init__(self, adm, n) | A constructor of the student object | :param adm: a positive integer, | :param n: a string | | ---------------------------------------------------------------------- | Data descriptors defined here: | | __dict__ | dictionary for instance variables (if defined) | | __weakref__ | list of weak references to the object (if defined) | | ---------------------------------------------------------------------- | Data and other attributes defined here: | | admission = 0 | | name = ''
В выходных данных мы видим документацию, которую мы написали для класса Student .
Вывод
Python поставляется со встроенной системой, из которой мы можем получить помощь в отношении модулей, классов, функций и ключевых слов. Эта утилита справки может быть доступна с помощью функции Python help() в ОТВЕТЕ. Когда мы вызываем эту функцию и передаем ей объект, она возвращает страницу справки или документацию для объекта. Когда мы запускаем функцию без аргумента, открывается утилита справки, где мы можем получить справку об объектах в интерактивном режиме. Наконец, чтобы получить помощь в отношении наших пользовательских классов и функций, мы можем определить строки документов.