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."

Do you think the docstrings and error messages should be improved as well as the docs?

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.

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."

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?

> 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.

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.

> > 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?

Yes, that would be great. It is better than my initial suggestion.

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