classification
Title: Strengthen 2.7 io types warning
Type: Stage: needs patch
Components: Documentation Versions:
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: benjamin.peterson, docs@python, eli.bendersky, eric.araujo, pitrou, python-dev, stutzbach, terry.reedy
Priority: normal Keywords: easy

Created on 2011-06-28 19:22 by terry.reedy, last changed 2011-07-22 11:41 by eli.bendersky. This issue is now closed.

Messages (10)
msg139374 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2011-06-28 19:22
Trying 3.2 code with 2.7, I got this (greatly simplified):

from __future__ import print_function
from io import StringIO
print('hello world', file=StringIO())
Traceback...
TypeError: string argument expected, got 'str'
(StringIO.StringIO works fine, of course.)

This was initially confusing. Suggestion: after

"Note Since this module has been designed primarily for Python 3.x, you have to be aware that all uses of “bytes” in this document refer to the str type (of which bytes is an alias), and all uses of “text” refer to the unicode type. "
add
'String' in exception messages may also mean the unicode type."
msg140138 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-07-11 16:05
Do you think the docstrings and error messages should be improved as well as the docs?
msg140171 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2011-07-12 02:34
My original suggestion is a minimal change suggestion. I do not have much opinion on what the maximum change 'should' be.

It would obviously be nice from a user viewpoint if the error message were backported to say "unicode argument expected, got 'str'". Then the note change might not be needed. But I do not know if the particular message is an accident or part of a policy of not fully backporting the code (to aid future patching?), or whether there are other messages that would need the same treatment.

The module docstring shown by help(io) does not have the terminology note to be augmented.
msg140173 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2011-07-12 04:55
In my opinion, it's the error messages and docstrings that should be changed, not the documentation. This module was introduced in 2.6 and moves on to 2.7, and there's no reason to have it throw confusing errors for the sake of easier back-patching from 3.x

However, when I run this example on 2.6, I get:

   TypeError: can't write str to text stream

Which (arguably) makes sense, since the docs explicitly say that "Text I/O classes work with unicode data."
msg140482 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2011-07-16 09:04
The difference between 2.6 and 2.7 stems from the rewrite of the IO library in C that was made for 2.7

The error Terry sees gets thrown here (in Modules/_io/stringio.c):

    if (!PyUnicode_Check(obj)) {
        PyErr_Format(PyExc_TypeError, "string argument expected, got '%s'",
                     Py_TYPE(obj)->tp_name);
        return NULL;
    }

Therefore, I propose to change this error message to:

"unicode argument expected, got '%s'"

as Terry suggested.

Adding Antoine, Benjamin and Daniel (listed as experts on IO) to nosy.

Is there an objection to making this change in the error message?
msg140492 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2011-07-16 10:43
> The error Terry sees gets thrown here (in Modules/_io/stringio.c):
> 
>     if (!PyUnicode_Check(obj)) {
>         PyErr_Format(PyExc_TypeError, "string argument expected, got '%s'",
>                      Py_TYPE(obj)->tp_name);
>         return NULL;
>     }
> 
> Therefore, I propose to change this error message to:
> 
> "unicode argument expected, got '%s'"
> 
> as Terry suggested.
> 
> Adding Antoine, Benjamin and Daniel (listed as experts on IO) to nosy.
> 
> Is there an objection to making this change in the error message?

No, the proposal is right.
msg140603 - (view) Author: Daniel Stutzbach (stutzbach) (Python committer) Date: 2011-07-18 16:52
On Sat, Jul 16, 2011 at 2:04 AM, Eli Bendersky <report@bugs.python.org>wrote:

> Therefore, I propose to change this error message to:
>  "unicode argument expected, got '%s'"
>  as Terry suggested.
>

Sounds good to me.
msg140649 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2011-07-19 03:53
> > Therefore, I propose to change this error message to:
> >  "unicode argument expected, got '%s'"
> >  as Terry suggested.
> >
>
> Sounds good to me.
>

Terry, what are your thoughts?
Can I commit the fix?
msg140650 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2011-07-19 06:00
Yes, that would be great. It is better than my initial suggestion.
msg140871 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2011-07-22 11:40
New changeset 0752215f9f91 by Eli Bendersky in branch '2.7':
Issue #12434: make StringIO.write error message consistent with Python 2.7 nomenclature
http://hg.python.org/cpython/rev/0752215f9f91
History
Date User Action Args
2011-07-22 11:41:20eli.benderskysetstatus: open -> closed
resolution: fixed
versions: - Python 2.7
2011-07-22 11:40:06python-devsetnosy: + python-dev
messages: + msg140871
2011-07-19 06:00:56terry.reedysetmessages: + msg140650
2011-07-19 05:11:20eli.benderskysetfiles: - unnamed
2011-07-19 05:11:16eli.benderskysetfiles: - unnamed
2011-07-19 03:53:48eli.benderskysetfiles: + unnamed

messages: + msg140649
2011-07-18 16:52:58stutzbachsetfiles: + unnamed

messages: + msg140603
2011-07-16 10:43:32pitrousetmessages: + msg140492
2011-07-16 09:04:03eli.benderskysetnosy: + pitrou, benjamin.peterson, stutzbach
messages: + msg140482
2011-07-12 04:55:15eli.benderskysetnosy: + eli.bendersky
messages: + msg140173
2011-07-12 02:34:54terry.reedysetmessages: + msg140171
2011-07-11 16:05:28eric.araujosetnosy: + eric.araujo
messages: + msg140138
2011-06-28 19:22:57terry.reedycreate