bpo-6519: Improve Python Input Output Tutorial (GH-2143) (GH-2145)
Move up the discussion about 'with' keyword, so it appears earlier in the document.
(cherry picked from commit bd4e9e0ca96dabf33605d9b1fd1e0562ece8ae18)
diff --git a/Doc/tutorial/inputoutput.rst b/Doc/tutorial/inputoutput.rst
index 92f439c..74d7bad 100644
--- a/Doc/tutorial/inputoutput.rst
+++ b/Doc/tutorial/inputoutput.rst
@@ -262,6 +262,35 @@
:file:`JPEG` or :file:`EXE` files. Be very careful to use binary mode when
reading and writing such files.
+It is good practice to use the :keyword:`with` keyword when dealing
+with file objects. The advantage is that the file is properly closed
+after its suite finishes, even if an exception is raised at some
+point. Using :keyword:`with` is also much shorter than writing
+equivalent :keyword:`try`\ -\ :keyword:`finally` blocks::
+
+ >>> with open('workfile') as f:
+ ... read_data = f.read()
+ >>> f.closed
+ True
+
+If you're not using the :keyword:`with` keyword, then you should call
+``f.close()`` to close the file and immediately free up any system
+resources used by it. If you don't explicitly close a file, Python's
+garbage collector will eventually destroy the object and close the
+open file for you, but the file may stay open for a while. Another
+risk is that different Python implementations will do this clean-up at
+different times.
+
+After a file object is closed, either by a :keyword:`with` statement
+or by calling ``f.close()``, attempts to use the file object will
+automatically fail. ::
+
+ >>> f.close()
+ >>> f.read()
+ Traceback (most recent call last):
+ File "<stdin>", line 1, in <module>
+ ValueError: I/O operation on closed file
+
.. _tut-filemethods:
@@ -354,27 +383,6 @@
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()``,
-attempts to use the file object will automatically fail. ::
-
- >>> f.close()
- >>> f.read()
- Traceback (most recent call last):
- File "<stdin>", line 1, in <module>
- ValueError: I/O operation on closed file
-
-It is good practice to use the :keyword:`with` keyword when dealing with file
-objects. This has the advantage that the file is properly closed after its
-suite finishes, even if an exception is raised on the way. It is also much
-shorter than writing equivalent :keyword:`try`\ -\ :keyword:`finally` blocks::
-
- >>> with open('workfile', 'r') as f:
- ... read_data = f.read()
- >>> f.closed
- True
-
File objects have some additional methods, such as :meth:`~file.isatty` and
:meth:`~file.truncate` which are less frequently used; consult the Library
Reference for a complete guide to file objects.