python 3, subclassing TextIOWrapper.

[Gabriel Genellina]

En Sun, 22 Mar 2009 21:03:38 -0300, Scott David Daniels  
<Scott.Daniels at acm.org> escribió:
> Gabriel Genellina wrote:
>> En Sun, 22 Mar 2009 19:12:13 -0300, Benjamin Peterson  
>> <benjamin at python.org> escribió:
>>> Gabriel Genellina <gagsl-py2 <at> yahoo.com.ar> writes:
>>>> The undocumented behavior is relying on the open() builtin to return a
>>>> BufferedReader for a binary file.
>>>
>>> I don't see the problem. open() will return some BufferedIOBase  
>>> implmentor, and
>>> that's all that TextIOWrapper needs.

>> How do you know? AFAIK, the return value of open() is completely  
>> undocumented:
>> http://docs.python.org/3.0/library/functions.html#open
>> And if you open the  file in text mode, the return value isn't a  
>> BufferedIOBase.
>
> OK, it is documented, but not so clearly.  I went first to the io
> module, rather than the open function documentation, and looked at
> what io.TextIOWrapper should get ast its first arg:
> [...]
>      The type of file object returned by the open() function depends on
>      the mode. When open() is used to open a file in a text mode ('w',
>      'r', 'wt', 'rt', etc.), it returns a TextIOWrapper. When used to
>      open a file in a binary mode, the returned class varies: in read
>      binary mode, it returns a BufferedReader; in write binary and append
>      binary modes, it returns a BufferedWriter, and in read/write mode,
>      it returns a BufferedRandom.
>
> Aha! it is documented.  If you have some good ideas on how to make
> this more obvious, I'm sure we'd be happy to "fix" the documentation.

Ah, yes. Hmm, so the same description appears in three places: the open()  
docstring, the docs for the builtin functions, and the docs for the io  
module. And all three are different :(
Perhaps open.__doc__ == documentation for io.open, and documentation for  
builtin.open should just tell the basic things and refer to io.open for  
details...

-- 
Gabriel Genellina