Programming Python (21 page)

^[
8
]
Notice that
input
raises an
exception to signal end-of-file, but file read methods simply return
an empty string for this condition. Because
input
also strips the end-of-line
character at the end of lines, an empty string result means an empty
line, so an exception is necessary to specify the end-of-file
condition. File read methods retain the end-of-line character and
denote an empty line as
"\n"
instead of
""
. This is one way in
which reading
sys.stdin
directly
differs from
input
. The latter
also accepts a prompt string that is automatically printed before
input is accepted.

• Text files
  contain Unicode text. In your script, text file
  content is always a
  str
string—
  a sequence of characters
  (technically, Unicode “code points”). Text files perform the
  automatic line-end translations described in this chapter by default
  and automatically apply Unicode encodings to file content: they
  encode to and decode from raw binary bytes on transfers to and from
  the file, according to a provided or default encoding name. Encoding
  is trivial for ASCII text, but may be sophisticated in other
  cases.
  

• Binary files
  contain raw 8-bit bytes. In your script, binary file
  content is always a byte string, usually a
  bytes
object—a sequence of small integers,
  which supports most
  str
operations and displays as ASCII characters whenever possible.
  Binary files perform no translations of data when it is transferred
  to and from files: no line-end translations or Unicode encodings are
  performed.
  

To make a new
file, call
open
with
two arguments: the external
name
of the file to
be created and a
mode
string
w
(short for
write
). To
store data on the file, call the
file object’s
write
method with a string containing the data to store, and then call
the
close
method to
close the file. File
write
calls
return the number of characters or bytes written (which we’ll
sometimes omit in this book to save space), and as we’ll see,
close
calls are often optional, unless you
need to open and read the file again during the same program or
session:

C:\temp>
python
>>>
file = open('data.txt', 'w')
# open output file object: creates
>>>
file.write('Hello file world!\n')
# writes strings verbatim
18
>>>
file.write('Bye   file world.\n')
# returns number chars/bytes written
18
>>>
file.close()
# closed on gc and exit too

And that’s it—you’ve just generated a brand-new text file on
your computer, regardless of the computer on which you type this
code:

C:\temp>
dir data.txt /B
data.txt
C:\temp>
type data.txt
Hello file world!
Bye   file world.

There is nothing unusual about the new file; here, I use the DOS
dir
and
type
commands to list and display the new
file, but it shows up in a file explorer GUI, too.

file.writelines(['Hello file world!\n', 'Bye   file world.\n'])

open('somefile.txt', 'w').write("G'day Bruce\n")       # write to temporary object
open('somefile.txt', 'r').read()                       # read from temporary object

Manual file
close method calls are easy in straight-line code, but
how do you ensure file closure when exceptions might kick your program
beyond the point where the close call is coded? First of all, make
sure you must—files close themselves when they are collected, and this
will happen eventually, even when exceptions occur.

If closure is required, though, there are two basic
alternatives: the
try
statement’s
finally
clause is the most general,
since it allows you to provide general exit actions for any type of
exceptions:

myfile = open(filename, 'w')
try:
...process myfile...
finally:
myfile.close()

In recent Python releases, though, the
with
statement
provides a more concise alternative for some specific objects and exit
actions, including closing files:

with open(filename, 'w') as myfile:
...process myfile, auto-closed on statement exit...

This statement relies on the file object’s context manager: code
automatically run both on statement entry and on statement exit
regardless of exception behavior. Because the file object’s exit code
closes the file automatically, this guarantees file closure whether an
exception occurs during the statement or not.

The
with
statement is notably
shorter (3 lines) than the
try
/
finally
alternative, but it’s also less
general—
with
applies only to
objects that support the context manager protocol, whereas
try
/
finally
allows arbitrary exit actions for
arbitrary exception contexts. While some other object types have
context managers, too (e.g., thread locks),
with
is limited in scope. In fact, if you
want to remember just one exit actions option,
try
/
finally
is the most inclusive. Still,
with
yields less code for files
that must be closed and can serve well in such specific roles. It can
even save a line of code when no
exceptions
are expected (albeit at the
expense of further nesting and indenting file
processing
logic):

myfile = open(filename, 'w')               # traditional form
...process myfile...
myfile.close()
with open(filename) as myfile:             # context manager form
...process myfile...

In Python 3.1 and later, this statement can also specify
multiple (a.k.a. nested) context managers—any number of context
manager items may be separated by commas, and multiple items work the
same as nested
with
statements. In
general terms, the 3.1 and later code:

with A() as a, B() as b:
...statements...

Runs the same as the following, which works in 3.1, 3.0, and
2.6:

with A() as a:
with B() as b:
...statements...

For example, when the
with
statement block exits in the following, both files’ exit actions are
automatically run to close the files, regardless of exception
outcomes:

with open('data') as fin, open('results', 'w') as fout:
for line in fin:
fout.write(transform(line))

Context manager–dependent code like this seems to have become
more common in recent years, but this is likely at least in part
because newcomers are accustomed to languages that require manual
close calls in all cases. In most contexts there is no need to wrap
all your Python file-processing code in
with
statements—the files object’s
auto-close-on-collection behavior often suffices, and manual close
calls are enough for many other scripts. You should use the
with
or
try
options outlined here only if you must
close, and only in the presence of potential exceptions. Since
standard C Python automatically closes files on collection, though,
neither option is required in many (and perhaps
most) scripts.

Reading data
from external files is just as easy as writing, but
there are more methods that let us load data in a variety of modes.
Input text files are opened with either a mode flag of
r
(for “read”) or no mode flag at all—it
defaults to
r
if omitted, and it
commonly is. Once opened, we can read the lines of a text file with
the
readlines
method:

C:\temp>
python
>>>
file = open('data.txt')
# open input file object: 'r' default
>>>
lines = file.readlines()
# read into line string list
>>>
for line in lines:
# BUT use file line iterator! (ahead)
...
print(line, end='')
# lines have a '\n' at end
...
Hello file world!
Bye   file world.

The
readlines
method loads
the entire contents of the file into memory and gives it to our
scripts as a list of line strings that we can step through in a loop.
In fact, there are many ways to read an input file:

Let’s run these method calls to read files, lines, and
characters from a text file—the
seek(0)
call is used here before each test
to rewind the file to its beginning (more on this call in a
moment):

>>>
file.seek(0)
# go back to the front of file
>>>
file.read()
# read entire file into string
'Hello file world!\nBye   file world.\n'
>>>
file.seek(0)
# read entire file into lines list
>>>
file.readlines()
['Hello file world!\n', 'Bye   file world.\n']
>>>
file.seek(0)
>>>
file.readline()
# read one line at a time
'Hello file world!\n'
>>>
file.readline()
'Bye   file world.\n'
>>>
file.readline()
# empty string at end-of-file
''
>>>
file.seek(0)
# read N (or remaining) chars/bytes
>>>
file.read(1), file.read(8)
# empty string at end-of-file
('H', 'ello fil')

All of these input methods let us be specific about how much to
fetch. Here are a few rules of thumb about which to choose:

The
seek(0)
call used
repeatedly here means “go back to the start of the file.” In our
example, it is an alternative to reopening the file each time. In
files, all read and write operations take place at the current
position; files normally start at offset 0 when opened and advance as
data is transferred. The
seek
call
simply lets us move to a new position for the next transfer operation.
More on this method later when we explore random access
files.