bpo-6519: Improve Python Input Output Tutorial (GH-2143) (GH-2146) · python/cpython@5a86154
@@ -261,6 +261,35 @@ to file data is fine for text files, but will corrupt binary data like that in
261261:file:`JPEG` or :file:`EXE` files. Be very careful to use binary mode when
262262reading and writing such files.
263263264+It is good practice to use the :keyword:`with` keyword when dealing
265+with file objects. The advantage is that the file is properly closed
266+after its suite finishes, even if an exception is raised at some
267+point. Using :keyword:`with` is also much shorter than writing
268+equivalent :keyword:`try`\ -\ :keyword:`finally` blocks::
269+270+ >>> with open('workfile') as f:
271+ ... read_data = f.read()
272+ >>> f.closed
273+ True
274+275+If you're not using the :keyword:`with` keyword, then you should call
276+``f.close()`` to close the file and immediately free up any system
277+resources used by it. If you don't explicitly close a file, Python's
278+garbage collector will eventually destroy the object and close the
279+open file for you, but the file may stay open for a while. Another
280+risk is that different Python implementations will do this clean-up at
281+different times.
282+283+After a file object is closed, either by a :keyword:`with` statement
284+or by calling ``f.close()``, attempts to use the file object will
285+automatically fail. ::
286+287+ >>> f.close()
288+ >>> f.read()
289+ Traceback (most recent call last):
290+ File "<stdin>", line 1, in <module>
291+ ValueError: I/O operation on closed file
292+264293265294.. _tut-filemethods:
266295@@ -353,27 +382,6 @@ to the very file end with ``seek(0, 2)``) and the only valid *offset* values are
353382those returned from the ``f.tell()``, or zero. Any other *offset* value produces
354383undefined behaviour.
355384356-357-When you're done with a file, call ``f.close()`` to close it and free up any
358-system resources taken up by the open file. After calling ``f.close()``,
359-attempts to use the file object will automatically fail. ::
360-361- >>> f.close()
362- >>> f.read()
363- Traceback (most recent call last):
364- File "<stdin>", line 1, in <module>
365- ValueError: I/O operation on closed file
366-367-It is good practice to use the :keyword:`with` keyword when dealing with file
368-objects. This has the advantage that the file is properly closed after its
369-suite finishes, even if an exception is raised on the way. It is also much
370-shorter than writing equivalent :keyword:`try`\ -\ :keyword:`finally` blocks::
371-372- >>> with open('workfile', 'r') as f:
373- ... read_data = f.read()
374- >>> f.closed
375- True
376-377385File objects have some additional methods, such as :meth:`~file.isatty` and
378386:meth:`~file.truncate` which are less frequently used; consult the Library
379387Reference for a complete guide to file objects.