При написании и запуске программ Python вы можете застрять, и вам понадобится помощь. Возможно, вам потребуется знать значение определенных модулей, классов, функций, ключевых слов и т. Д. Хорошей новостью является то, что Python поставляется со встроенной справочной системой. Это означает, что вам не нужно искать помощи за пределами самого Python.

В этой статье вы узнаете, как пользоваться встроенной справочной системой Python.

Функция Python help ()

Эта функция помогает нам получить документацию по определенному классу, функции, переменной, модулю и т. Д. Функцию следует использовать в консоли Python для получения сведений о различных объектах Python.

Передача объекта в функцию help ()

Функция Python help() имеет следующий синтаксис:

 >>> help(object) 

В приведенном выше синтаксисе object - это имя объекта, по которому вам нужно получить справку.

Например, чтобы узнать больше о print Python, введите следующую команду в консоли 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 ()

Если вы передадите строку в качестве аргумента, строка будет рассматриваться как имя функции, модуля, ключевого слова, метода, класса или раздела документации, и будет напечатана соответствующая страница справки. Чтобы пометить его как строковый аргумент, заключите его в одинарные или двойные кавычки.

Например:

 >>> 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 как строковый аргумент, мы все же получили документацию для функции 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 определенной в math библиотеке Python. В этом случае нам сначала нужно импортировать 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» и нажмите клавишу ввода:

 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() для наших пользовательских функций и классов, определив строку документации (строку документа). В Python первая строка комментария, добавленная в тело метода, рассматривается как его строка документации. Комментарий должен быть заключен в три двойные кавычки. Например:

 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 
 """ 

Это будет рассматриваться как строка документации для функционального 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': <built-in function log>, '__builtins__': <module 'builtins' (built-in)>, '__spec__': None, '__package__': None, '__name__': '__main__', '__loader__': <class '_frozen_importlib.BuiltinImporter'>, '__file__': 'C:/Users/admin/myfile.py', 'Student': <class '__main__.Student', 'product': <function product at 0x0000000003569B70>} 

Как показано в выходных данных выше, и Student и product находятся в словаре глобальной области видимости. Теперь мы можем использовать help() чтобы получить справку по классу Student и функции product Просто запустите следующую команду в консоли 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() в REPL. Когда мы вызываем эту функцию и передаем ей объект, она возвращает страницу справки или документацию для объекта. Когда мы запускаем функцию без аргумента, открывается вспомогательная утилита, где мы можем получить справку об объектах в интерактивном режиме. Наконец, чтобы получить помощь в отношении наших пользовательских классов и функций, мы можем определить строки документации.