[issue7417] open builtin has no signature in docstring

[Ulrik Sverdrup]

Ulrik Sverdrup <ulrik.sverdrup at gmail.com> added the comment:

import builtins; help(builtins)

Looking around, the new suggestion is absolutely unconventional. The
signature must be on the first line. One builtin function even uses two
lines; min:

        min(iterable[, key=func]) -> value
        min(a, b, c, ...[, key=func]) -> value
        
        With a single iterable argument, return its smallest item.
        With two or more arguments, return the smallest argument.

I would ack a two-line signature at the start of the docstring, however
I will also suggest an alternative:

Aligning open's signature description with the builtins module, this is
the style that is most common:

open(file[, mode[, buffering[, encoding[, errors[, newline[,
closefd]]]]]]) -> file object

perhaps even an abbreviation is allowed at the end?

open(file[, mode[, buffering[, encoding[, errors[, newline[,
closefd]..]) -> file object

However that open has so many kwargs should almost be a bug in itself.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue7417>
_______________________________________