Getting Help 寻求帮助

You saw the abs function in the previous tutorial, but what if you’ve forgotten what it does?
你在前面的教程中看到了 abs 函数，但如果你忘记了它的作用怎么办？

The help() function is possibly the most important Python function you can learn. If you can remember how to use help(), you hold the key to understanding most other function.
help()函数可能是你可以学习的最重要的 Python 函数。如果你能记住如何使用 help()，你就掌握了理解大多数其他函数的关键。

Here is an example:
下面是一个例子。

1
help(round)
1
2
3
4
5
6
7
8
Help on built-in function round in module builtins:

round(...)
    round(number[, ndigits]) -> number

    Round a number to a given precision in decimal digits (default 0 digits).
    This returns an int when called with one argument, otherwise the
    same type as the number. ndigits may be negative.

help() displays two things:

  1. the header of that function round(number[, ndigits]). In this case, this tells us that round() takes an argument we can describe as number. Additionally, we can optionally give a separate argument which could be described as ndigits.
    函数 round(number[, ndigits])的头。在这种情况下，这告诉我们 round()取一个参数，我们可以用 number 来描述。此外，我们可以选择给出一个单独的参数，可以描述为 ndigits。
  2. A brief English description of what the function does.
    简单的英文描述一下这个函数的作用。

Defining Functions

Builtin functions are great, but we can only get so far with them before we need to start defining our own functions. Below is a simple example.
内置函数是很好的，但在我们需要开始定义自己的函数之前，我们只能在这些函数上走得很远。下面是一个简单的例子.Builtin 函数很好，但在我们需要开始定义自己的函数之前，我们只能通过它们走得很远。下面是一个简单的例子。

1
2
3
4
5
def least_difference(a, b, c):
    diff1 = abs(a - b)
    diff2 = abs(b - c)
    diff3 = abs(a - c)
    return min(diff1, diff2, diff3)

Docstring

1
2
3
4
5
6
7
8
9
10
11
def least_difference(a, b, c):
    """Return the smallest difference between any two numbers
    among a, b and c.

    >>> least_difference(1, 5, -5)
    4
    """
    diff1 = abs(a - b)
    diff2 = abs(b - c)
    diff3 = abs(a - c)
    return min(diff1, diff2, diff3)

The docstring is a triple-quoted string (which may span multiple lines) that comes immediately after the header of a function. When we call help() on a function, it shows the docstring.
docstring 是一个三引号的字符串（可以跨越多行），紧接在函数的头后面。当我们在一个函数上调用 help() 时，它会显示 docstring。

1
help(least_difference)
1
2
3
4
5
6
7
8
Help on function least_difference in module __main__:

least_difference(a, b, c)
    Return the smallest difference between any two numbers
    among a, b and c.

    >>> least_difference(1, 5, -5)
    4

Functions that don’t return 不返回的函数

What would happen if we didn’t include the return keyword in our function?
如果我们的函数中不包含返回关键字，会有什么后果呢？

1
2
3
4
5
6
7
8
9
10
11
12
13
14
def least_difference(a, b, c):
    """Return the smallest difference between any two numbers
    among a, b and c.
    """
    diff1 = abs(a - b)
    diff2 = abs(b - c)
    diff3 = abs(a - c)
    min(diff1, diff2, diff3)

print(
    least_difference(1, 10, 100),
    least_difference(1, 10, 10),
    least_difference(5, 6, 7),
)

None None None

Python allows us to define such functions. The result of calling them is the special value None. (This is similar to the concept of “null” in other languages.)
Python 允许我们定义这样的函数。调用它们的结果是特殊值 None。(这类似于其他语言中的 “null “的概念)。

Functions Applied to Functions

Here’s something that’s powerful, though it can feel very abstract at first. You can supply functions as arguments to other functions. Some example may make this clearer:
这里有一个很强大的东西，虽然一开始会觉得很抽象。你可以将函数作为参数提供给其他函数。一些例子可能会让你更清楚。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
def mult_by_five(x):
    return 5 * x

def call(fn, arg):
    """Call fn on arg"""
    return fn(arg)

def squared_call(fn, arg):
    """Call fn on the result of calling fn on arg"""
    return fn(fn(arg))

print(
    call(mult_by_five, 1),
    squared_call(mult_by_five, 1),
    sep='\n', # '\n' is the newline character - it starts a new line
)

5
25

Exercise

1.

Complete the body of the following function according to its docstring.

HINT: Python has a built-in function round.

1
2
3
4
5
6
7
8
9
10
11
12
13
def round_to_two_places(num):
    """Return the given number rounded to two decimal places.

    >>> round_to_two_places(3.14159)
    3.14
    """
    # Replace this body with your own code.
    # ("pass" is a keyword that does literally nothing. We used it as a placeholder
    # because after we begin a code block, Python requires at least one line of code)
    pass

# Check your answer
q1.check()

2.

The help for round says that ndigits (the second argument) may be negative.
What do you think will happen when it is? Try some examples in the following cell?

Can you think of a case where this would be useful?

1
# Put your test code here

3.

In a previous programming problem, the candy-sharing friends Alice, Bob and Carol tried to split candies evenly. For the sake of their friendship, any candies left over would be smashed. For example, if they collectively bring home 91 candies, they’ll take 30 each and smash 1.

Below is a simple function that will calculate the number of candies to smash for any number of total candies.

Modify it so that it optionally takes a second argument representing the number of friends the candies are being split between. If no second argument is provided, it should assume 3 friends, as before.

Update the docstring to reflect this new behaviour.

1
2
3
4
5
6
7
8
9
10
11
def to_smash(total_candies):
    """Return the number of leftover candies that must be smashed after distributing
    the given number of candies evenly between 3 friends.

    >>> to_smash(91)
    1
    """
    return total_candies % 3

# Check your answer
q3.check()

References

Functions and Getting Help | Kaggle