[Python-3000-checkins] r65595 - python/branches/py3k/Doc/tutorial/inputoutput.rst

[georg.brandl]

Author: georg.brandl
Date: Fri Aug  8 09:04:38 2008
New Revision: 65595

Log:
#3524: fix up some old-style IO descriptions.


Modified:
   python/branches/py3k/Doc/tutorial/inputoutput.rst

Modified: python/branches/py3k/Doc/tutorial/inputoutput.rst
==============================================================================
--- python/branches/py3k/Doc/tutorial/inputoutput.rst	(original)
+++ python/branches/py3k/Doc/tutorial/inputoutput.rst	Fri Aug  8 09:04:38 2008
@@ -228,6 +228,9 @@
 ::
 
    >>> f = open('/tmp/workfile', 'w')
+
+.. XXX str(f) is <io.TextIOWrapper object at 0x82e8dc4>
+
    >>> print(f)
    <open file '/tmp/workfile', mode 'w' at 80a0960>
 
@@ -240,19 +243,18 @@
 writing. The *mode* argument is optional; ``'r'`` will be assumed if it's
 omitted.
 
-On Windows and the Macintosh, ``'b'`` appended to the mode opens the file in
-binary mode, so there are also modes like ``'rb'``, ``'wb'``, and ``'r+b'``.
-Windows makes a distinction between text and binary files; the end-of-line
-characters in text files are automatically altered slightly when data is read or
-written.  This behind-the-scenes modification to file data is fine for ASCII
-text files, but it'll corrupt binary data like that in :file:`JPEG` or
-:file:`EXE` files.  Be very careful to use binary mode when reading and writing
-such files.  On Unix, it doesn't hurt to append a ``'b'`` to the mode, so
-you can use it platform-independently for all binary files.
-
-This behind-the-scenes modification to file data is fine for text files, but
-will corrupt binary data like that in :file:`JPEG` or :file:`EXE` files.  Be
-very careful to use binary mode when reading and writing such files.
+Normally, files are opened in :dfn:`text mode`, that means, you read and write
+strings from and to the file, which are encoded in a specific encoding (the
+default being UTF-8).  ``'b'`` appended to the mode opens the file in
+:dfn:`binary mode`: now the data is read and written in the form of bytes
+objects.  This mode should be used for all files that don't contain text.
+
+In text mode, the default is to convert platform-specific line endings (``\n``
+on Unix, ``\r\n`` on Windows) to just ``\n`` on reading and ``\n`` back to
+platform-specific line endings on writing.  This behind-the-scenes modification
+to file data is fine for text files, but will corrupt binary data like that in
+:file:`JPEG` or :file:`EXE` files.  Be very careful to use binary mode when
+reading and writing such files.
 
 
 .. _tut-filemethods:
@@ -264,12 +266,12 @@
 ``f`` has already been created.
 
 To read a file's contents, call ``f.read(size)``, which reads some quantity of
-data and returns it as a string.  *size* is an optional numeric argument.  When
-*size* is omitted or negative, the entire contents of the file will be read and
-returned; it's your problem if the file is twice as large as your machine's
-memory. Otherwise, at most *size* bytes are read and returned.  If the end of
-the file has been reached, ``f.read()`` will return an empty string (``""``).
-::
+data and returns it as a string or bytes object.  *size* is an optional numeric
+argument.  When *size* is omitted or negative, the entire contents of the file
+will be read and returned; it's your problem if the file is twice as large as
+your machine's memory. Otherwise, at most *size* bytes are read and returned.
+If the end of the file has been reached, ``f.read()`` will return an empty
+string (``''``).  ::
 
    >>> f.read()
    'This is the entire file.\n'
@@ -281,7 +283,7 @@
 file if the file doesn't end in a newline.  This makes the return value
 unambiguous; if ``f.readline()`` returns an empty string, the end of the file
 has been reached, while a blank line is represented by ``'\n'``, a string
-containing only a single newline.   ::
+containing only a single newline.  ::
 
    >>> f.readline()
    'This is the first line of the file.\n'
@@ -304,8 +306,8 @@
 memory efficient, fast, and leads to simpler code::
 
    >>> for line in f:
-           print(line, end='')
-
+   ...     print(line, end='')
+   ...
    This is the first line of the file.
    Second line of the file
 
@@ -314,9 +316,10 @@
 should not be mixed.
 
 ``f.write(string)`` writes the contents of *string* to the file, returning
-``None``.   ::
+the number of characters written. ::
 
    >>> f.write('This is a test\n')
+   15
 
 To write something other than a string, it needs to be converted to a string
 first::
@@ -324,6 +327,7 @@
    >>> value = ('the answer', 42)
    >>> s = str(value)
    >>> 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
@@ -334,15 +338,22 @@
 the reference point.  *from_what* can be omitted and defaults to 0, using the
 beginning of the file as the reference point. ::
 
-   >>> f = open('/tmp/workfile', 'r+')
-   >>> f.write('0123456789abcdef')
+   >>> f = open('/tmp/workfile', 'rb+')
+   >>> f.write(b'0123456789abcdef')
+   16
    >>> f.seek(5)     # Go to the 6th byte in the file
+   5
    >>> f.read(1)        
-   '5'
+   b'5'
    >>> f.seek(-3, 2) # Go to the 3rd byte before the end
+   13
    >>> f.read(1)
-   'd'
+   b'd'
 
+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)``).
+   
 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()``,
 attempts to use the file object will automatically fail. ::