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

[Sandro Tosi]

Hello Mark,
thanks for your detailed email.

On Tue, Mar 29, 2011 at 23:47, Mark Ballard <markjballard at googlemail.com> wrote:
> 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 suggest to consult python-list[1] and ask there clarification about
those points.

[1] http://mail.python.org/mailman/listinfo/python-list

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

could you please log an issue on http://bugs.python.org/ explaining
(possible with concrete examples, even better with a patch) how you
would like to see that part changed?

Thanks in advance,
-- 
Sandro Tosi (aka morph, morpheus, matrixhasu)
My website: http://matrixhasu.altervista.org/
Me at Debian: http://wiki.debian.org/SandroTosi