How can I create my own “hint” when calling a func

问题:

I know my question might be confusing, it's hard to ask something you don't know what it is exactly (I'm going to call it 'hint'), so my apologies for that. Having that said, here it is what I mean (the text in the white box):

My questions are:

• How can I make my own hint (and customize it) text when calling a function?
• What is it exactly?
• What does the text in this example mean?

回答1:

IDLE calls the popup a 'calltip'. For a module defined in python code with a def statement, it shows the signature on the first line and the first line of the doc string on the second. They are intended to work correctly for any type of callable invoked with parentheses.

If you type '(' the box pops up unless you are typing fast. After it closes, to bring it back, you position the cursor between '(' and ')' and either select Edit on the top menu and 'Show call tip', or type the shortcut key shown on the menu. For more, see the doc.

回答2:

You are in fact correct about the textbox being called hint, so no quotation needed. What you are seeing is a type hint. It is supported by the typing module inside Python. Refer to the example below:

def add(a: int, b: int) -> int:
    return a + b

Then when you try to call the function you will see a textbox very similar to the one you showed. I encourage you to read the typing module page if you want to learn more about it.

That said, in most cases you will not be needing that type hint because doc strings ("""info about my function""") are usually sought after more.

回答3:

For future reference:

• How can I make my own hint [...] when calling a function?

First, there are 2 types of 'hints' as I called them:

4.7.6. Documentation Strings:
Here are some conventions about the content and formatting of documentation strings.

The first line should always be a short, concise summary of the object’s purpose. [...] This line should begin with a capital letter and end with a period.

If there are more lines in the documentation string, the second line should be blank, visually separating the summary from the rest of the description. The following lines should be one or more paragraphs describing the object’s calling conventions, its side effects, etc. [...]

Here is an example of a multi-line docstring:

>>> def my_function():
...     """Do nothing, but document it.
...
...     No, really, it doesn't do anything.
...     """
...     pass
...
>>> print(my_function.__doc__)
Do nothing, but document it.

    No, really, it doesn't do anything.

And the one introduced in Python 3.0:

4.7.7. Function Annotations: Function annotations are completely optional metadata information about the types used by user-defined functions (see PEP 3107 and PEP 484 for more information).

Annotations are stored in the annotations attribute of the function as a dictionary and have no effect on any other part of the function. Parameter annotations are defined by a colon after the parameter name, followed by an expression evaluating to the value of the annotation. Return annotations are defined by a literal ->, followed by an expression, between the parameter list and the colon denoting the end of the def statement. The following example has a positional argument, a keyword argument, and the return value annotated:

>>> def f(ham: str, eggs: str = 'eggs') -> str:
...     print("Annotations:", f.__annotations__)
...     print("Arguments:", ham, eggs)
...     return ham + ' and ' + eggs
...
>>> f('spam')
Annotations: {'ham': <class 'str'>, 'return': <class 'str'>, 'eggs': <class 'str'>}
Arguments: spam eggs
'spam and eggs'

---

• What is it exactly?

With what is written above and what Terry Jan Reedy answered:

IDLE calls the popup a 'calltip'. For a module defined in python code with a def statement, it shows the signature on the first line and the first line of the doc string on the second. They are intended to work correctly for any type of callable invoked with parentheses.

If you type '(' the box pops up unless you are typing fast. After it closes, to bring it back, you position the cursor between '(' and ')' and either select Edit on the top menu and 'Show call tip', or type the shortcut key shown on the menu. For more, see the doc.

---

• What does the text in this example mean?

Sadly, because I'm not working on with what I was at the moment and I never had the need to understand it, I have not found what the syntax for each calltip is.