Python 3.1.1's open has no signature in the docstring so the
documentation for this builtin function is unfortunately very confusing
(IMO is missing the most important part).

>>> help(open)

open(...)
    Open file and return a stream.  Raise IOError upon failure.
    
    ...

----

This must be a regression from the C port of the io module.

I'm keeping my eyes open for more issues like this. Python must be more
friendly to newcomers, but I have seen tendencies of confusing
documentation in Python 3.

Proposed docstring patch.

Looks good to me (module indentation).

Make that "modulo."

Indentation is not easy on this part.
The list of arguments overflow the 79 chars limit.
With the proposed patch, the generated output is something like:


open(file, mode='r', buffering=None, encoding=None,
           errors=None, newline=None, closefd=True) -> file object

Open file and return a stream.  Raise IOError upon failure.

...


Is it wrong?

According to PEP257:
«Multi-line docstrings consist of a summary line just like a one-line
docstring, followed by a blank line, followed by a more elaborate
description.»

Maybe this second patch is more conventional?

Actually the docstring of _pyio.open Python function should not change.

The patch is smaller.

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.

Ulrik,

I agree that most builtins have the signature on first lines.
I will not apply this part of the PEP257.

But it seems that the "[...]" syntax is not enforced for all builtins.
See "help(print)", "help(sorted)" and "help(__import__)" examples:

>>> print(print.__doc__)
print(value, ..., sep=' ', end='\n', file=sys.stdout)

Prints the values to a stream, or to sys.stdout by default.
Optional keyword arguments:
file: a file-like object (stream); defaults to the current sys.stdout.
sep:  string inserted between values, default a space.
end:  string appended after the last value, default a newline.

>>> print(sorted.__doc__)
sorted(iterable, key=None, reverse=False) --> new sorted list

>>> print(__import__.__doc__)
__import__(name, globals={}, locals={}, fromlist=[], level=-1) -> module

Import a module.  The globals are only used to determine the context;
they are not modified...



Patch is updated.

Or I suggest something more verbose...


>>> print(open.__doc__)
open(filename) -> file object for reading in text mode

open(filename, mode=binary[, buffering]) -> file object in binary mode
open(filename[, mode=text][, buffering][,encoding][,errors][,newline])
                                         -> file object in text mode

open(file_descriptor[, ...][, closefd]) -> file object

Open file and return a stream.  Raise IOError upon failure.

filename is either a text or byte string giving the name (and the path
if the file isn't in the current working directory) of the file to
be opened.

file_descriptor is an integer file descriptor of the file to be
wrapped. The file descriptor is closed when the returned I/O object is
closed, unless closefd is set to False.)

mode is an optional string that specifies the mode in which the file
is opened...

(patch attached: explicit signature)

I vote +1 for something more explicit.
« Explicit is better than implicit. »

>>> help(open)
Help on built-in function open in module io:

open(...)
    open(file_name_or_path) -> file object for reading in text mode
    open(file_name_or_path, mode=binary_mode[, buffering]) -> file objec
    open(file_name_or_path[, mode=text_mode[, buffering[, encoding
                          [, errors[, newline]]]]]) -> file object
    open(file_descriptor[, ...[, closefd]]) -> file object
    
    Open file and return a stream.  Raise IOError upon failure.
    
    file_name_or_path is either a text or byte string giving the name
    (and the path if the file isn't in the current working directory)
    of the file to be opened.
    
    file_descriptor is an integer file descriptor of the file to be
    wrapped. The file descriptor is closed when the returned I/O object
    is closed, unless closefd is set to False.)
    
    mode is an optional string that specifies the mode in which the file
    is opened...

Georg, I'm a bit lost in the different suggestions. Your take? Do you
have any preference? Or should we simply copy the docstring from _pyio's
open() function?

Added signature from msg95885 in r77009.