Issue 8895: newline vs. newlines in io module (original) (raw)
I was confused about the newline argument/attribute in the misc. classes of the io module until I realize there is a spelling issue between the docs and the real implementation. (Py 2.6.5, Py2.7b2). Py 3.x not tested.
sys.version 2.7b2 (r27b2:81019, May 9 2010, 11:33:14) [MSC v.1500 32 bit (Intel)] sio = io.StringIO(u'abc') sio.encoding, type(sio.encoding) (None, <type 'NoneType'>) sio.errors, type(sio.errors) (None, <type 'NoneType'>) sio.newline, type(sio.newline) Traceback (most recent call last): File "", line 1, in AttributeError: '_io.StringIO' object has no attribute 'newline' sio.newlines, type(sio.newlines) (None, <type 'NoneType'>)
tio = io.TextIOWrapper(io.BytesIO()) tio.buffer, type(tio.buffer) (<_io.BytesIO object at 0x02E6E600>, <type '_io.BytesIO'>) tio.encoding, type(tio.encoding) ('cp1252', <type 'str'>) tio.errors, type(tio.errors) ('strict', <type 'str'>) tio.line_buffering, type(tio.line_buffering) (False, <type 'bool'>) tio.newline, type(tio.newline) Traceback (most recent call last): File "", line 1, in AttributeError: '_io.TextIOWrapper' object has no attribute 'newline' tio.newlines, type(tio.newlines) (None, <type 'NoneType'>)
sys.version 2.6.5 (r265:79096, Mar 19 2010, 21:48:26) [MSC v.1500 32 bit (Intel)] import io tio = io.TextIOWrapper(io.BytesIO()) tio.encoding, type(tio.encoding) ('cp1252', <type 'str'>) tio.line_buffering, type(tio.line_buffering) (False, <type 'bool'>) tio.errors, type(tio.errors) (u'strict', <type 'unicode'>) tio.newline, type(tio.newline) Traceback (most recent call last): File "", line 1, in AttributeError: 'TextIOWrapper' object has no attribute 'newline' tio.newlines, type(tio.newlines) (None, <type 'NoneType'>) [e for e in dir(tio) if 'new' in e] ['new', 'newlines']
2010/6/4 R. David Murray <report@bugs.python.org>
R. David Murray <rdmurray@bitdance.com> added the comment:
This is as documented:
http://docs.python.org/dev/3.0/library/io.html#io.TextIOBase.newlines
The keyword argument is named 'newline', the attribute is named 'newlines'. The attribute does not record what was passed to the newline argument, rather it records what newlines have been actually encountered.
Ok, I see. I read, reread the doc prior posting, and, in my mind, it is not obvious to understand this subtle difference from the doc. Sorry for the noise. Regards.
2010/6/4 Éric Araujo <report@bugs.python.org>
Éric Araujo <merwok@netwok.org> added the comment:
Could you think of a way to improve the docs on that point?
Quick and dirty answer.
I have ~10 years experience with Python and it seems to me the io module is technically excellent.
However, I have found it is not so obvious to understand the usage of all these arguments, errors, encoding, line_buffering, ... in the class constructors and methods like io.open().
The doc describes what these arguments are, their states, but not too much how to use them.
As an exemple, I read some time ago on the c.l.p mailing list, somebody complaining about the "encoding" argument of the class TextIOWrapper. He defined an "encoding='utf-8'" in the ctor and did not understand why his "text" was not automagically encoded. Answer: the encoding arg is only a kind of information and does not do anything.
BTW, it was only when I read that post, I understand a little bit more.
Regards.