[docs] Suggested improvement for Python Tutorial part 7.2 - 'Reading and writing files'

[Mark Ballard]

Hello

May I, a mere beginner,  be so bold as to suggest a modification of your
excellent Python Tutorial?

I think certain modifications of section 7.2 (
http://docs.python.org/tutorial/inputoutput.html) would be of great
assistance to beginners.

First of all, the order in which the different file operations are presented
could be changed for greater comprehension. Section 7.2 begins the
beginners' introduction to file objects (after a quick introduction to
opening/creating files) by giving a rather sizable description of read
functions, with examples. Since the beginner at this stage hasn't learned
the first thing about writing to files, she is unlikely to have any test
files on which to perform the given read functions. This section on reading
files is therefore redundant until the beginner has got to the section
further on that describes how to write files, after which she must return to
the start of the section to do the read samples and effectively read the
section backwards. It would be more helpful to have the write tutorial
before the read tutorial.

In addition to this confusion of ordering, I had some trouble following the
given read and write examples.

Please refer to this example transcript of my attempt to follow the
instructions in section 7.2:

* STEP 1 - I open a file for reading and writing and write to the file

>>> f = open('/tmp/workfile', 'r+')
>>> print f
<open file '/tmp/workfile', mode 'r+' at 0xb76a31d8>
>>> f.read()
''
>>> f.write('this is first line of file\n')

* STEP 2 - I attempt to read what I've written, but without success

>>> f.readline()
''
>>> f.readlines()
[]

* STEP 3 - Bemused, I try writing and reading some more

>>> f.write('this is a test')
>>> f.readlines()
[]

* BREAKOUT - Unable to find any explanation in 7.2 I go for help elsewhere
                        After some time, I find it in the Python Tutor mail
list
                        (here:
http://mail.python.org/pipermail/tutor/2003-July/024154.html)

* STEP 4 - Using f.close() I successfully read what I've written
                 But only one of my previously written lines is there

>>> f.close()
>>> f = open('/tmp/workfile', 'r+')
>>> f.readlines()
['this is first line of file\n']

* STEP 5 - Bemused, I try writing another line
                 And use the knowledge gleaned from the Python Tutor Mail
list to reset the file pointer

>>> f.write('this is second line\n')
>>> f.readlines()
[]
>>> f.seek(0)
>>> f.readlines()
['this is first line of file\n']

* STEP 6 - But where are the other lines I've written?

>>> f.readlines()
[]

* STEP 7 - Bemused, I write yet another line to the file, reset the pointer
and read it back

>>> f.write('this is what where?\n')
>>> f.seek(0)
>>> f.readlines()
['this is first line of file\n', 'this is what where?\n']
>>>

For what to me is an inexplicable reason, my last attempt at writing to this
file seemed to be successful: it read back. But all my previous attempts to
write a second line have been lost in the ether. Now I'm sure I'll work this
out eventually. But perhaps the tutorial could clarify some of these points.

I would like to suggest that one way to improve 7.2 would be to include at
the beginning of the section, after a simple introduction of write and read
with basic one line examples, a description of the file pointer and why its
important in reading back what one has written. It may then use multiple
line writes and reads to demonstrate how these differ. And perhaps then some
word on these phantom writes?

Kind regards

Mark.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20110329/c4ee17d5/attachment-0001.html>