[Python-checkins] cpython (3.3): #16273: Fix tutorial discussion of seek/tell (opaque text-mode values).

[r.david.murray]

http://hg.python.org/cpython/rev/81bc2d64c006
changeset:   84919:81bc2d64c006
branch:      3.3
parent:      84917:0e1f0faacb0d
user:        R David Murray <rdmurray at bitdance.com>
date:        Tue Jul 30 15:51:57 2013 -0400
summary:
  #16273: Fix tutorial discussion of seek/tell (opaque text-mode values).

Patch by Sijin Joseph.

files:
  Doc/tutorial/inputoutput.rst |  13 +++++++++----
  1 files changed, 9 insertions(+), 4 deletions(-)


diff --git a/Doc/tutorial/inputoutput.rst b/Doc/tutorial/inputoutput.rst
--- a/Doc/tutorial/inputoutput.rst
+++ b/Doc/tutorial/inputoutput.rst
@@ -322,9 +322,11 @@
    >>> f.write(s)
    18
 
-``f.tell()`` returns an integer giving the file object's current position in the
-file, measured in bytes from the beginning of the file.  To change the file
-object's position, use ``f.seek(offset, from_what)``.  The position is computed
+``f.tell()`` returns an integer giving the file object's current position in the file
+represented as number of bytes from the beginning of the file when in `binary mode` and
+an opaque number when in `text mode`.
+
+To change the file object's position, use ``f.seek(offset, from_what)``.  The position is computed
 from adding *offset* to a reference point; the reference point is selected by
 the *from_what* argument.  A *from_what* value of 0 measures from the beginning
 of the file, 1 uses the current file position, and 2 uses the end of the file as
@@ -345,7 +347,10 @@
 
 In text files (those opened without a ``b`` in the mode string), only seeks
 relative to the beginning of the file are allowed (the exception being seeking
-to the very file end with ``seek(0, 2)``).
+to the very file end with ``seek(0, 2)``) and the only valid *offset* values are
+those returned from the ``f.tell()``, or zero. Any other *offset* value produces
+undefined behaviour.
+
 
 When you're done with a file, call ``f.close()`` to close it and free up any
 system resources taken up by the open file.  After calling ``f.close()``,

-- 
Repository URL: http://hg.python.org/cpython