[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

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

f.readline()

'This is the first line of the file.\n'
@@ -304,8 +306,8 @@
- 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

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. ::