Python help built in

Using Python’s built-in help system

Python has a built-in help system which you can activate using the help function:

Welcome to Python 3.7'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.7/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". . 

In this week’s Python blog post, you will learn

• how to use the help system to learn about unfamiliar code, and
• how to make your own code work with the help system.

When do I use the help system?

Python has great online documentation which covers the same topics as the help system, so when do I use the help system instead of the online documentation?

When I want to learn about something that is difficult to Google, like 3j

Help on complex object: class complex(object) | complex(real=0, imag=0) | | Create a complex number from a real part and an | optional imaginary part. | | . 

The power operator ****************** The power operator binds more tightly than unary operators on its left; it binds less tightly than unary operators on its right. . 

import urllib.request result = urllib.request.urlopen("http://example.com") help(result) 

Help on HTTPResponse in module http.client object: class HTTPResponse(io.BufferedIOBase) | HTTPResponse(sock, debuglevel=0, method=None, url=None) | | . | | Methods defined here: | | . | | getcode(self) | Return the HTTP status code that was sent with the | response, or None if the URL is not an HTTP URL. | | getheader(self, name, default=None) | Returns the value of the header matching *name*. | . | | . 

Using the help system on unfamiliar code

Here is a short story about using the help system to understand my friend’s code.

I’m working on a programming challenge with my friend Mia 👩🏻 . The challenge is to design a function that returns the sum of the first n Fibonacci numbers. I’m having trouble with this, so I ask Mia how she solved the problem. She shows me her code:

import itertools def fibonacci(): a, b = 1, 1 while True: yield a a, b = b, a + b def sum_fib(n): return sum(itertools.islice(fibonacci(), n)) sum_fib(100) 

I tell her that there are 3 things I don’t understand:

Mia laughs and tells me to figure it out for myself, so I boot up the Python interpreter and start the interactive help system:

Welcome to Python 3.7'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.7/tutorial/. . 

The "yield" statement ********************* . Yield expressions and statements are only used when defining a *generator* function, and are only used in the body of the generator function. Using yield in a function definition is sufficient to cause that definition to create a generator function instead of a normal function. . 

What does a, b = b, a + b do? Searching = doesn’t help:

No Python documentation found for '='. 

I check which topics the help system covers:

Here is a list of available topics. Enter any topic name to get more help. ASSERTION DELETION LOOPING ASSIGNMENT DICTIONARIES MAPPINGMETHODS ATTRIBUTEMETHODS DICTIONARYLITERALS MAPPINGS . 

I read more about assignment:

Assignment statements ********************* . An assignment statement evaluates the expression list (remember that this can be a single expression or a comma-separated list, the latter yielding a tuple) and assigns the single resulting object to each of the target lists, from left to right. . The object must be an iterable with the same number of items as there are targets in the target list, and the items are assigned, from left to right, to the corresponding targets . 

I learn that multiple assignment

(This is an easy way to swap names: x, y = y, x .)

What does itertools.islice do?

Help on class islice in itertools: itertools.islice = class islice(builtins.object) | islice(iterable, stop) --> islice object | islice(iterable, start, stop[, step]) --> islice object | | . | | Works like a slice() on a list but returns an iterator. | | . 

For Mia’s code, itertools.islice takes the first n elements generated by the fibonacci() generator function.

I understand how Mia’s code works now, so I explain it back to her. She tells me «good job» 🤷🏻‍♀️ and returns to her computer, solving the next programming challenge.

Making my own code available to the help system

Here is a short story about making my code work with the help system, in order to share my code with Mia 👩🏻 .

I wrote a function that creates a random binary tree and I want to share this with Mia. She wrote some algorithms that process binary trees and she wants to test them out on randomly generated trees instead of handwritten cases.

from collections import namedtuple import random # Represents a node in a binary tree. # # None is used to represent absence of a branch, so a # leaf node looks like Tree(x, None, None). Tree = namedtuple("Tree", ["value", "left", "right"]) def random_tree(max_depth=1): # Generate a random binary tree of depth at most # max_depth. # # Each node has a value between 10 and 99. Each node # (excluding nodes at the maximum depth) has an 80% # chance of having a left child and an 80% chance of # having a right child. if max_depth == 0: return value = random.randint(10, 99) left = right = None if random.random() < 0.8: left = random_tree(max_depth-1) if random.random() < 0.8: right = random_tree(max_depth-1) return Tree(value, left, right) 

The problem is that my comments don't show up when I ask the help system about Tree and random_tree :

Help on class Tree in module __main__: class Tree(builtins.tuple) | Tree(value, left, right) | | Tree(value, left, right) | | Method resolution order: | Tree | builtins.tuple | . 

Help on function random_tree in module __main__: random_tree(max_depth=1) 

I want Mia to be able to use the help system to learn about the code I wrote, so I turn the comments into docstrings (PEP 257). Docstrings are strings that are attached to objects with the __doc__ attribute. Unlike comments, docstrings aren't thrown away by the Python Interpreter; they are kept around and used by the help system. I add a docstring to random_tree as the first statement in the function:

def random_tree(max_depth=1): """Generate a random binary tree of depth at most max_depth. Each node has a value between 10 and 99. Each node (excluding nodes at the maximum depth) has an 80% chance of having a left child and an 80% chance of having a right child. """ if max_depth == 0: return value = random.randint(10, 99) left = right = None if random.random() < 0.8: left = random_tree(max_depth-1) if random.random() < 0.8: right = random_tree(max_depth-1) return Tree(value, left, right) 

(PEP 257 recommends using triple double quotes """ for docstrings.)

Now the help system includes my comments for random_tree :

Help on function random_tree in module __main__: random_tree(max_depth=1) Generate a random binary tree of depth at most max_depth. Each node has a value between 10 and 99. Each node (excluding nodes at the maximum depth) has an 80% chance of having a left child and an 80% chance of having a right child. 

I add a docstring to Tree by directly assigning __doc__ :

Tree = namedtuple("Tree", ["value", "left", "right"]) Tree.__doc__ = """Represents a node in a binary tree. None is used to represent absence of a branch, so a leaf node looks like Tree(x, None, None). """ 

Now the help system includes my comments for Tree :

Help on class Tree in module __main__: class Tree(builtins.tuple) | Tree(value, left, right) | | Represents a node in a binary tree. | | None is used to represent absence of a branch, so a | leaf node looks like Tree(x, None, None). | | Method resolution order: | . 

I share my code with Mia and she's able to figure out how it works and how to use it without needing to ask me. I tell Mia "good job" 🤷🏼‍♂️ and get back to solving the next programming challenge.

In conclusion.

Python has a built-in help system that can help you understand other people's code, as well as allow you to document your code for other people. It covers the same content as Python's online documentation but can be more useful when you want to learn about something that's hard to Google or when you want to learn about the results of a function without needing to pore over API documentation.

Python's docstring allow any kind of plain text comments to be written, but Python has special support for the reStructuredText format. My challenge to you is:

Read through PEP 287, "reStructuredText Docstring Format", to learn about using reStructuredText in docstrings. Then, document a Python function using reStructuredText. (Pick a function from the standard library or use the random_tree function that I shared with Mia.)

If you enjoyed this week's post, share it with your friends and stay tuned for next week's post. See you then!

Copyright © 2021 John Lekberg

Источник

Функция help() в Python: вызов справки

Когда вам нужна помощь в написании программы, использовании модулей, а также для вызова справки рекомендуется использовать функцию help() в Python.

Что такое help() в Python?

help() в Python — это встроенный метод, который используется для интерактивного использования. Функция help() используется для получения документации по указанному модулю, классу, функции, переменным и т.д.

Синтаксис

В справочной консоли мы можем указать имена модулей, классов и функций, чтобы получить их документацию.

Теперь перейдите в терминал или консоль CMD и введите следующую команду.

На данный момент версия Python3 является последней, поэтому введите python3, и вы увидите то, что показано ниже.

Теперь введите функцию help().

Теперь мы можем проверить следующие встроенные функции и модули.

Допустим, мы вводим коллекции, а затем получаем следующий вывод в консоли.

Параметры

Метод help() принимает максимум один параметр.

object передается в help()

Введите следующую команду.

Строка передается в качестве аргумента

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

Если вы хотите выйти из справочной консоли, введите команду quit.

Определение help() для пользовательского класса и функций

Мы можем определить вывод функции help() для наших пользовательских классов и функций, указав docstring (строку документации).

По умолчанию в качестве строки документации используется первая строка комментария в теле метода. Его окружают три двойных кавычки.

Допустим, у нас есть файл python help_examples.py со следующим кодом.

Источник