[Python-Dev] [Python-checkins] r45850 - inpython/trunk:Doc/lib/libfuncs.tex Lib/test/test_subprocess.pyMisc/NEWSObjects/fileobject.c Python/bltinmodule.c

[Fredrik Lundh]

Tim Peters wrote:

>>>> SF #1479181: split open() and file() from being aliases for each other.
>
>>> Umm ... why?
>
> [/F]
>> so that introspection tools can support GvR's pronouncement that "open"
>> should be used to open files, and "file" should be used as a type representing
>> standard (current stdio-based) file handles.
>
> Maybe some of the intended changes are missing?  The post-patch
> docstrings don't draw this distinction, and I'm lost about what else
> introspection tools could be looking at to make the distinction
> (special-casing the names?  but they could have done that before):
>
> """
>>>> print open.__doc__
> open(name[, mode[, buffering]]) -> file object
>
> Open a file using the file() type, returns a file object.
>
>>>> print file.__doc__
> file(name[, mode[, buffering]]) -> file object
>
> Open a file.  The mode can be 'r', 'w' or 'a' for reading (default),
> writing or appending.  The file will be created if it doesn't exist
> when opened for writing or appending; it will be truncated when
> opened for writing.  Add a 'b' to the mode for binary files.
> Add a '+' to the mode to allow simultaneous reading and writing.
> If the buffering argument is given, 0 means unbuffered, 1 means line
> buffered, and larger numbers specify the buffer size.
> Add a 'U' to mode to open the file for input with universal newline
> support.  Any line ending in the input file will be seen as a '\n'
> in Python.  Also, a file so opened gains the attribute 'newlines';
> the value for this attribute is one of None (no newline read yet),
> '\r', '\n', '\r\n' or a tuple containing all the newline types seen.
>
> 'U' cannot be combined with 'w' or '+' mode.
>
>>>>
> """
>
> In Python 2.4, the docstrings were of course the same (the current
> trunk's file.__doc__ except for a line at the end).  Since all useful
> info about how to open a file has been purged from open()'s docstring,
> if you've got the intent right, looks like the implementation got it
> backwards ;-)

agreed.  imho, the detailed description should be moved to open, and the file
docstring should refer to open for a full description of how the arguments are
used.

and the open docstring could say something like "returns a file object.  in the
current version, this is always an instance of the file() type."

unless I'm missing something here, of course.

(I was asked to review this patch, but those mails arrived around 2 am, so I
didn't see them until now...)

</F>