File write examples are inadequate

[kandrew]

BPO	621057
Nosy	@freddrake, @rhettinger

^{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 = 'https://github.com/freddrake'
closed_at = <Date 2004-11-02.18:28:23.000>
created_at = <Date 2002-10-09.22:39:34.000>
labels = ['docs']
title = 'File write examples are inadequate'
updated_at = <Date 2004-11-02.18:28:23.000>
user = 'https://bugs.python.org/kandrew'

bugs.python.org fields:

activity = <Date 2004-11-02.18:28:23.000>
actor = 'fdrake'
assignee = 'fdrake'
closed = True
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2002-10-09.22:39:34.000>
creator = 'kandrew'
dependencies = []
files = []
hgrepos = []
issue_num = 621057
keywords = []
message_count = 10.0
messages = ['12695', '12696', '12697', '12698', '12699', '12700', '12701', '12702', '12703', '12704']
nosy_count = 4.0
nosy_names = ['fdrake', 'mcherm', 'rhettinger', 'kandrew']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = None
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue621057'
versions = []

[kandrew]

The examples provided for writing to files in
section 7.2 of the documentation are overly simple
showing only writing of a static string. Reading
through 7.1 (although not actually discussing file
I/O) helps a little as the % operator is mentioned
but the "...C sprintf()-style format string..."
specifiers which are valid aren't cross referenced
(and the 'Library Reference' is a largish search
area). I had to find out experimentally that %f isn't
valid although %d is. To date, I haven't been able
to experimentally findout how to print a list or
tuple.

trying:
file.write('"%s"', str(relatedMeasurements))

results in:
TypeError: read-only buffer, tuple

The addition of examples printing a list or tuple
would be extremely helpful. Similarly, examples of
using file.write() to produce print type output
would be very illuminating.

[rhettinger]

Logged In: YES
user_id=80475

Here are a few thoughts:

The % formatting operator is fully documented in 2.2.6.2
of the library reference. I think the tutorial should be kept
at an introductory level and the details left in the reference.
OTOH, I agree that 2.2.6.2 is hard to find.

%f is a valid format: '%f' % 3.14

There are several oddities in the file.write error in your
post. First, the double quotes inside the single quotes
(perhaps this is intentional). Second, the comma should
have been the % formatting operator. Third, since 'file' is
the name of a type, it is normally a good idea to pick
another name like 'infil' or 'outfil'.

The post doesn't include enough information to be able to
reproduce the error. We need to know the value of
relatedMeasurements and have a line showing how the file
was opened.

To debug the example, it would help to separate the
concerns of file writing from the string formatting. Get the
program to successfully format and print a string. Only
then, add a line to write it out to a file.

[kandrew]

Logged In: YES
user_id=577467

The comment that the example is incomplete is well
founded. Therefore I attach a standalone example of
the problem I ran into:

>>> peakPres = {'Unknown':0}
>>> peakPres['meas1'] = 0
>>> peakPres['meas1'] = peakPres['meas1']+1
>>> print peakPres
{'meas1': 1, 'Unknown': 0}
>>> for pres in peakPres.keys():
... 	print pres, peakPres[pres]
... 
meas1 1
Unknown 0
>>> file.open('test1.dat', 'w')
Traceback (innermost last):
  File "<interactive input>", line 1, in ?
NameError: file
>>> file = open('test1.dat', 'w')
>>> for pres in peakPres.keys():
... 	file.write('%s: %s, ', pres, peakPres[pres])
... 
Traceback (innermost last):
  File "<interactive input>", line 2, in ?
TypeError: read-only buffer, tuple
>>> 

Note that the call to print works while the call to
file.write does not. The reason is that the print
statement makes a call to __str__.

Thus, and file.write() do not have the same relationship
as C++ stream classes ostream and ofstream or C's
printf and fprintf. (As implied by rhettinger and the
current contents of the tutorial.)

Hence, my request that the tutorial's examples of file
output be expanded to the non-trival level of writing
list and dictionary members. Cross referenceing the
legal format specifiers (in the language reference) from
the tutorial examples would also be extremely helpful.

[kandrew]

Logged In: YES
user_id=577467

The comment that the example is incomplete is well
founded. Therefore I attach a standalone example of
the problem I ran into:

>>> peakPres = {'Unknown':0}
>>> peakPres['meas1'] = 0
>>> peakPres['meas1'] = peakPres['meas1']+1
>>> print peakPres
{'meas1': 1, 'Unknown': 0}
>>> for pres in peakPres.keys():
... 	print pres, peakPres[pres]
... 
meas1 1
Unknown 0
>>> file.open('test1.dat', 'w')
Traceback (innermost last):
  File "<interactive input>", line 1, in ?
NameError: file
>>> file = open('test1.dat', 'w')
>>> for pres in peakPres.keys():
... 	file.write('%s: %s, ', pres, peakPres[pres])
... 
Traceback (innermost last):
  File "<interactive input>", line 2, in ?
TypeError: read-only buffer, tuple
>>> 

Note that the call to print works while the call to
file.write does not. The reason is that the print
statement makes a call to __str__.

Thus, and file.write() do not have the same relationship
as C++ stream classes ostream and ofstream or C's
printf and fprintf. (As implied by rhettinger and the
current contents of the tutorial.)

Hence, my request that the tutorial's examples of file
output be expanded to the non-trival level of writing
list and dictionary members. Cross referenceing the
legal format specifiers (in the language reference) from
the tutorial examples would also be extremely helpful.

[rhettinger]

Logged In: YES
user_id=80475

When coded with the proper syntax, the example runs fine:

>>> peakPres = {'meas1': 1, 'Unknown': 0}
>>> f = open('test1', 'w')
>>> for pres in peakPres:
        f.write('%s: %s, ' % (pres, peakPres[pres]))

	
>>> f.close()
>>> open('test1').read()
'Unknown: 0, meas1: 1, '

To debug your code, please do the following:
-- don't use variable names like file, list, etc
-- use the % formatting operator instead of a comma
-- build a correctly formatting string before worrying
about writing it to a file
-- the % operator takes a single tuple argument so the
values must be wrapped in parentheses:
formatstring % (val1, val2, val3)

Note, the tutorial and library reference are stand-alone
documents and do not cross reference with each other.

Recommend that you withdraw the bug report.

[freddrake]

Logged In: YES
user_id=3066

Raymond: I asked Andrew to file this bug report after he
first sent a note to the python-docs address; I do think
there's room for improvement in the docs. i'd hoped to get
to this before now, but still intend to do so.

[kandrew]

Logged In: YES
user_id=577467

I appear to have failed to clearly state the point of this
bug report. It has nothing to do with debugging a
specific piece of code and everything to do with the
difficulty in finding the required information for an
experienced developer to write code to perform a
standard task. The changes suggested to correct this
issue as, in fact, quite simple.

Examining tutorial section 7.2:

http://www.python.org/doc/current/tut/node9.html#SE
CTION009200000000000000000

The examples provided show only static strings.

Example 1:

>> f.write('This is a test\n')

Example 2:

>> f.write('0123456789abcdef')

Including even one example with a variable of any type
would be a large step forward and this is the primary
point of this bug report.

I.e. consider including the following example:

Printing a variable:
>>> a = 123.456
>>> f.write( '%d' % (a))

and: Printing a tuple:
>>> b = ('This', 'is', 9876.654, 'not a string')
>>> f.write(str(b))

or printing the tuple without the brackets:
>>> for element in b
...    f.write('%s ' % str(element))

I believe this to be an essential point to be made and
addressed because every (IMI EVERY) other example of
generating output in the tutorial that I have seen uses
the print() function. If you examine the language
reference, it is quite apparent that print() accepts
a 'expression' which is a much more flexible construct
then the 'string' accepted by file.write(). It's obvious
that you are aware of the difference between the two
functions yet you appear to be insisting that there's no
need to provide anything more then the most trivial of
examples when discussing the more restrictive of
them. This bug report was raised specifically because
of the difficulty encountered by a non-guru in
determining what is required to make that more
restrictive function work.

No sir, I will not withdraw the bug report at this time as
it has not yet been addressed and the core issue here is
not debugging a piece of code.

[rhettinger]

Logged In: YES
user_id=80475

That's cool.
I'll leave this one for Fred.
Hopefully, 2.2.6.2 can be made easier to find.

[mcherm]

Logged In: YES
user_id=99874

I took a close look at this, and considered adding text like
you describe to the tutorial. However, looking at it
carefully, I think it's probably best to leave the tutorial
as it is (and close this bug). Here's my reasoning:

(1) the write() method of files takes strings. If you need
to output some structured variable, first convert it into a
string somehow, then pass that to write(). Your complaint
(if I understand correctly) was that as a beginner you came
to this and assumed that the write() method of files might
work rather like the print statement -- with special
processing allowing one to pass in other types and have them
automatically converted. You propose including one example
in the tutorial to demonstrate the correct way of doing it.

(2) The current tutorial is simple and clear. It has just
one one-line example of how to use write() (passing it a
string). This is easy to follow, and doesn't cause anyone to
confuse converting to a string with writing to a file.
*Unnecessarily* complicating this would be unwise.

(3) So the question is whether debunking your error is
"necessary" (well, whether it's worth making that part of
the tutorial more complex. I would say no, because I think
your error is uncommon. (Not to say that it didn't have
*you* fooled for a time, just that it wouldn't fool *lots*
of first-time users.) The example demonstrates how to print
a string. The truth is that strings are all that you can
print. The section on files doesn't help much for the person
who needs to learn how to convert a more complex data
structure to a string, but then I wouldn't expect it to --
that section is supposed to be about files. The other
information is in section 7.1 *immediately preceeding* the
section on files. I figure most readers will at least be
skimming the tutorial in order, and will already know how to
convert their data structures by the time they get to
section 7.2.

kandrew, please feel free to correct me if I've missed an
important point you had to make, but barring a
misunderstanding, I propose closing this bug.
-- Michael Chermside

[freddrake]

Logged In: YES
user_id=3066

There's another option, which I've just implemented: Add an
example explaining that the value needs to be converted to a
string first. I think this deals with the initial issue and
avoids introducing or maintaining confusion. It's also
really quick to show, which makes it appropriate for the
tutorial.

Doc/tut/tut.tex revisions 1.257, 1.196.8.24