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

262262

reading 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

353382

those returned from the ``f.tell()``, or zero. Any other *offset* value produces

354383

undefined 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-377385

File objects have some additional methods, such as :meth:`~file.isatty` and

378386

:meth:`~file.truncate` which are less frequently used; consult the Library

379387

Reference for a complete guide to file objects.