How to specify custom tool-tip descriptions for Python functions in IDLE

Question

As soon as I type print( in IDLE 3.4.1, a tool-tip comes up:

print(value, ..., sep=' ', end='\n', file=sys.stdout, flush=False)

Clearly this was custom-set in the definition of the print function, or somewhere else. However, if I make a function

def func1(*args):
    ...

or

def func2(*args):
    "func(arg, ...) -> do things"
    ...

or even

def func3(*args: 'arg, ...') -> 'do things':
    ...

my tool-tips read:

(*args)

and

(*args)
func(arg, ...) -> do things

and

(*args: 'arg, ...') -> 'do things'

Of course, I want the tool-tip to read func(arg, ...) -> do things .

Is setting a custom tool-tip/documentation string a built-in feature? If not, then how can I accomplish this?

Answer 1

Idle developer here. Tooltips include the actual function signature, if one is available, and the first line of the docstring (or more, up to 5 or the first blank). Before 3.4, the actual signature of builtins was not available. So the workaround was to include the (supposed) signature in the docstring. However, builtins are now being converted to provide actual signatures, and when they are, the workaround is not needed and the pseudosignature is removed from the docstring. In other words, the form you want was an obsolete workaround that is going away. Sorry.

The PEP8 standard is that docstrings should start with one summary line (followed by a blank before anything more) that says what the function does. For a real function, somethings like "Return a wish-fulfilling star." For side-effect methods, start with something else, like "Re-arrange the deck furniture." So putting the signature in the docstring of func2 is 'wrong', and was never needed for python-coded functions.