Repository navigation
newline vs. newlines in io module #53141
Description
| BPO | 8895 |
|---|---|
| Nosy | @merwok, @bitdancer, @vadmium |
| Files |
Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.
Show more details
GitHub fields:
assignee = None
closed_at = <Date 2010-06-04.11:49:40.879>
created_at = <Date 2010-06-04.09:05:56.918>
labels = ['type-bug', 'invalid', 'docs']
title = 'newline vs. newlines in io module'
updated_at = <Date 2015-02-24.23:32:58.877>
user = 'https://bugs.python.org/jmfauth'bugs.python.org fields:
activity = <Date 2015-02-24.23:32:58.877>
actor = 'martin.panter'
assignee = 'docs@python'
closed = True
closed_date = <Date 2010-06-04.11:49:40.879>
closer = 'r.david.murray'
components = ['Documentation']
creation = <Date 2010-06-04.09:05:56.918>
creator = 'jmfauth'
dependencies = []
files = ['17553']
hgrepos = []
issue_num = 8895
keywords = []
message_count = 7.0
messages = ['107017', '107026', '107028', '107051', '107054', '107083', '107085']
nosy_count = 5.0
nosy_names = ['eric.araujo', 'jmfauth', 'r.david.murray', 'docs@python', 'martin.panter']
pr_nums = []
priority = 'normal'
resolution = 'not a bug'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue8895'
versions = ['Python 2.7']
Activity
jmfauth commentedon Jun 4, 2010
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.
merwok commentedon Jun 4, 2010
Thanks for the report. Could you check the docs for 3.1 and 3.x trunk (py3k) too?
[-]newline arg/attribute in the module io[/-][+]newline vs. newlines in io module[/+]bitdancer commentedon Jun 4, 2010
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.
jmfauth commentedon Jun 4, 2010
2010/6/4 R. David Murray <report@bugs.python.org>
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.
merwok commentedon Jun 4, 2010
Could you think of a way to improve the docs on that point?
jmfauth commentedon Jun 4, 2010
2010/6/4 Éric Araujo <report@bugs.python.org>
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.
bitdancer commentedon Jun 4, 2010
This is off topic for this issue, but what you just reported makes no sense to me. TextIOWrapper calls the encoder corresponding to the specified encoding in its write method.
That said, it is true that the IO docs are currently a class reference and not a user reference, and this should be fixed. There may even already be an open issue for this.