Mercurial > cpython-lru_cache-weakref

annotate Doc/tutorial/inputoutput.rst @ 47787:b32101c19bf8 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Grammar fixes
author Andrew M. Kuchling <amk@amk.ca>
date Fri, 20 Jun 2008 23:14:32 +0000
parents 70f9a5db279c
children d31d61f46498
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1 .. _tut-io:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3 ****************
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
4 Input and Output
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
5 ****************
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
6
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
7 There are several ways to present the output of a program; data can be printed
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
8 in a human-readable form, or written to a file for future use. This chapter will
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
9 discuss some of the possibilities.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
10
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
11
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
12 .. _tut-formatting:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
13
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
14 Fancier Output Formatting
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
15 =========================
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
16
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
17 So far we've encountered two ways of writing values: *expression statements* and
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
18 the :keyword:`print` statement. (A third way is using the :meth:`write` method
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
19 of file objects; the standard output file can be referenced as ``sys.stdout``.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
20 See the Library Reference for more information on this.)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
21
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
22 .. index:: module: string
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
23
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
24 Often you'll want more control over the formatting of your output than simply
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
25 printing space-separated values. There are two ways to format your output; the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
26 first way is to do all the string handling yourself; using string slicing and
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
27 concatenation operations you can create any layout you can imagine. The
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
28 standard module :mod:`string` contains some useful operations for padding
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
29 strings to a given column width; these will be discussed shortly. The second
47282
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
30 way is to use the :meth:`str.format` method.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
31
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
32 One question remains, of course: how do you convert values to strings? Luckily,
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
33 Python has ways to convert any value to a string: pass it to the :func:`repr`
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
34 or :func:`str` functions. Reverse quotes (``````) are equivalent to
47282
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
35 :func:`repr`, but they are no longer used in modern Python code and are removed
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
36 in future versions of the language.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
37
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
38 The :func:`str` function is meant to return representations of values which are
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
39 fairly human-readable, while :func:`repr` is meant to generate representations
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
40 which can be read by the interpreter (or will force a :exc:`SyntaxError` if
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
41 there is not equivalent syntax). For objects which don't have a particular
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
42 representation for human consumption, :func:`str` will return the same value as
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
43 :func:`repr`. Many values, such as numbers or structures like lists and
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
44 dictionaries, have the same representation using either function. Strings and
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
45 floating point numbers, in particular, have two distinct representations.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
46
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
47 Some examples::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
48
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
49 >>> s = 'Hello, world.'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
50 >>> str(s)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
51 'Hello, world.'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
52 >>> repr(s)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
53 "'Hello, world.'"
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
54 >>> str(0.1)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
55 '0.1'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
56 >>> repr(0.1)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
57 '0.10000000000000001'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
58 >>> x = 10 * 3.25
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
59 >>> y = 200 * 200
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
60 >>> s = 'The value of x is ' + repr(x) + ', and y is ' + repr(y) + '...'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
61 >>> print s
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
62 The value of x is 32.5, and y is 40000...
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
63 >>> # The repr() of a string adds string quotes and backslashes:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
64 ... hello = 'hello, world\n'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
65 >>> hellos = repr(hello)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
66 >>> print hellos
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
67 'hello, world\n'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
68 >>> # The argument to repr() may be any Python object:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
69 ... repr((x, y, ('spam', 'eggs')))
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
70 "(32.5, 40000, ('spam', 'eggs'))"
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
71 >>> # reverse quotes are convenient in interactive sessions:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
72 ... `x, y, ('spam', 'eggs')`
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
73 "(32.5, 40000, ('spam', 'eggs'))"
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
74
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
75 Here are two ways to write a table of squares and cubes::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
76
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
77 >>> for x in range(1, 11):
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
78 ... print repr(x).rjust(2), repr(x*x).rjust(3),
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
79 ... # Note trailing comma on previous line
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
80 ... print repr(x*x*x).rjust(4)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
81 ...
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
82 1 1 1
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
83 2 4 8
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
84 3 9 27
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
85 4 16 64
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
86 5 25 125
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
87 6 36 216
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
88 7 49 343
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
89 8 64 512
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
90 9 81 729
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
91 10 100 1000
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
92
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
93 >>> for x in range(1,11):
47282
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
94 ... print '{0:2d} {1:3d} {2:4d}'.format(x, x*x, x*x*x)
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
95 ...
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
96 1 1 1
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
97 2 4 8
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
98 3 9 27
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
99 4 16 64
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
100 5 25 125
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
101 6 36 216
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
102 7 49 343
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
103 8 64 512
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
104 9 81 729
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
105 10 100 1000
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
106
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
107 (Note that in the first example, one space between each column was added by the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
108 way :keyword:`print` works: it always adds spaces between its arguments.)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
109
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
110 This example demonstrates the :meth:`rjust` method of string objects, which
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
111 right-justifies a string in a field of a given width by padding it with spaces
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
112 on the left. There are similar methods :meth:`ljust` and :meth:`center`. These
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
113 methods do not write anything, they just return a new string. If the input
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
114 string is too long, they don't truncate it, but return it unchanged; this will
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
115 mess up your column lay-out but that's usually better than the alternative,
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
116 which would be lying about a value. (If you really want truncation you can
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
117 always add a slice operation, as in ``x.ljust(n)[:n]``.)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
118
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
119 There is another method, :meth:`zfill`, which pads a numeric string on the left
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
120 with zeros. It understands about plus and minus signs::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
121
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
122 >>> '12'.zfill(5)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
123 '00012'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
124 >>> '-3.14'.zfill(7)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
125 '-003.14'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
126 >>> '3.14159265359'.zfill(5)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
127 '3.14159265359'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
128
47282
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
129 Basic usage of the :meth:`str.format` method looks like this::
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
130
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
131 >>> print 'We are the {0} who say "{1}!"'.format('knights', 'Ni')
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
132 We are the knights who say "Ni!"
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
133
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
134 The brackets and characters within them (called format fields) are replaced with
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
135 the objects passed into the format method. The number in the brackets refers to
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
136 the position of the object passed into the format method. ::
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
137
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
138 >>> print '{0} and {1}'.format('spam', 'eggs')
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
139 spam and eggs
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
140 >>> print '{1} and {0}'.format('spam', 'eggs')
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
141 eggs and spam
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
142
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
143 If keyword arguments are used in the format method, their values are referred to
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
144 by using the name of the argument. ::
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
145
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
146 >>> print 'This {food} is {adjective}.'.format(food='spam', adjective='absolutely horrible')
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
147 This spam is absolutely horrible.
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
148
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
149 Positional and keyword arguments can be arbitrarily combined::
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
150
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
151 >>> print 'The story of {0}, {1}, and {other}.'.format('Bill', 'Manfred', other='Georg')
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
152 The story of Bill, Manfred, and Georg.
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
153
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
154 An optional ``':``` and format specifier can follow the field name. This also
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
155 greater control over how the value is formatted. The following example
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
156 truncates the Pi to three places after the decimal.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
157
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
158 >>> import math
47282
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
159 >>> print 'The value of PI is approximately {0:.3f}.'.format(math.pi)
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
160 The value of PI is approximately 3.142.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
161
47282
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
162 Passing an integer after the ``':'`` will cause that field to be a minimum
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
163 number of characters wide. This is useful for making tables pretty.::
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
164
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
165 >>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 7678}
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
166 >>> for name, phone in table.items():
47282
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
167 ... print '{0:10} ==> {1:10d}'.format(name, phone)
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
168 ...
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
169 Jack ==> 4098
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
170 Dcab ==> 7678
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
171 Sjoerd ==> 4127
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
172
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
173 If you have a really long format string that you don't want to split up, it
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
174 would be nice if you could reference the variables to be formatted by name
47282
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
175 instead of by position. This can be done by simply passing the dict and using
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
176 square brackets ``'[]'`` to access the keys ::
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
177
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
178 >>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 8637678}
47282
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
179 >>> print 'Jack: {0[Jack]:d}; Sjoerd: {0[Sjoerd]:d}; Dcab: {0[Dcab]:d}'.format(table)
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
180 Jack: 4098; Sjoerd: 4127; Dcab: 8637678
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
181
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
182 This could also be done by passing the table as keyword arguments with the '**'
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
183 notation.::
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
184
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
185 >>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 8637678}
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
186 >>> print 'Jack: {Jack:d}; Sjoerd: {Sjoerd:d}; Dcab: {Dcab:d}'.format(**table)
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
187 Jack: 4098; Sjoerd: 4127; Dcab: 8637678
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
188
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
189 This is particularly useful in combination with the new built-in :func:`vars`
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
190 function, which returns a dictionary containing all local variables.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
191
47282
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
192 For a complete overview of string formating with :meth:`str.format`, see
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
193 :ref:`formatstrings`.
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
194
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
195
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
196 Old string formatting
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
197 ---------------------
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
198
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
199 The ``%`` operator can also be used for string formatting. It interprets the
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
200 left argument much like a :cfunc:`sprintf`\ -style format string to be applied
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
201 to the right argument, and returns the string resulting from this formatting
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
202 operation. For example::
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
203
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
204 >>> import math
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
205 >>> print 'The value of PI is approximately %5.3f.' % math.pi
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
206 The value of PI is approximately 3.142.
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
207
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
208 Since :meth:`str.format` is quite new, a lot of Python code still uses the ``%``
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
209 operator. However, because this old style of formatting will eventually removed
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
210 from the language :meth:`str.format` should generally be used.
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
211
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
212 More information can be found in the :ref:`string-formatting` section.
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
213
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
214
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
215 .. _tut-files:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
216
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
217 Reading and Writing Files
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
218 =========================
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
219
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
220 .. index::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
221 builtin: open
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
222 object: file
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
223
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
224 :func:`open` returns a file object, and is most commonly used with two
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
225 arguments: ``open(filename, mode)``.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
226
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
227 ::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
228
44383
3625234bf3d2 Some cleanup in the docs.
Georg Brandl <georg@python.org>
parents: 43413
diff changeset
229 >>> f = open('/tmp/workfile', 'w')
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
230 >>> print f
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
231 <open file '/tmp/workfile', mode 'w' at 80a0960>
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
232
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
233 The first argument is a string containing the filename. The second argument is
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
234 another string containing a few characters describing the way in which the file
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
235 will be used. *mode* can be ``'r'`` when the file will only be read, ``'w'``
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
236 for only writing (an existing file with the same name will be erased), and
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
237 ``'a'`` opens the file for appending; any data written to the file is
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
238 automatically added to the end. ``'r+'`` opens the file for both reading and
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
239 writing. The *mode* argument is optional; ``'r'`` will be assumed if it's
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
240 omitted.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
241
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
242 On Windows and the Macintosh, ``'b'`` appended to the mode opens the file in
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
243 binary mode, so there are also modes like ``'rb'``, ``'wb'``, and ``'r+b'``.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
244 Windows makes a distinction between text and binary files; the end-of-line
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
245 characters in text files are automatically altered slightly when data is read or
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
246 written. This behind-the-scenes modification to file data is fine for ASCII
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
247 text files, but it'll corrupt binary data like that in :file:`JPEG` or
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
248 :file:`EXE` files. Be very careful to use binary mode when reading and writing
44973
aaa5a794f887 Clarify "b" mode under Unix.
Georg Brandl <georg@python.org>
parents: 44383
diff changeset
249 such files. On Unix, it doesn't hurt to append a ``'b'`` to the mode, so
aaa5a794f887 Clarify "b" mode under Unix.
Georg Brandl <georg@python.org>
parents: 44383
diff changeset
250 you can use it platform-independently for all binary files.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
251
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
252
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
253 .. _tut-filemethods:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
254
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
255 Methods of File Objects
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
256 -----------------------
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
257
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
258 The rest of the examples in this section will assume that a file object called
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
259 ``f`` has already been created.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
260
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
261 To read a file's contents, call ``f.read(size)``, which reads some quantity of
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
262 data and returns it as a string. *size* is an optional numeric argument. When
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
263 *size* is omitted or negative, the entire contents of the file will be read and
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
264 returned; it's your problem if the file is twice as large as your machine's
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
265 memory. Otherwise, at most *size* bytes are read and returned. If the end of
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
266 the file has been reached, ``f.read()`` will return an empty string (``""``).
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
267 ::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
268
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
269 >>> f.read()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
270 'This is the entire file.\n'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
271 >>> f.read()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
272 ''
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
273
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
274 ``f.readline()`` reads a single line from the file; a newline character (``\n``)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
275 is left at the end of the string, and is only omitted on the last line of the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
276 file if the file doesn't end in a newline. This makes the return value
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
277 unambiguous; if ``f.readline()`` returns an empty string, the end of the file
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
278 has been reached, while a blank line is represented by ``'\n'``, a string
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
279 containing only a single newline. ::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
280
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
281 >>> f.readline()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
282 'This is the first line of the file.\n'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
283 >>> f.readline()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
284 'Second line of the file\n'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
285 >>> f.readline()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
286 ''
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
287
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
288 ``f.readlines()`` returns a list containing all the lines of data in the file.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
289 If given an optional parameter *sizehint*, it reads that many bytes from the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
290 file and enough more to complete a line, and returns the lines from that. This
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
291 is often used to allow efficient reading of a large file by lines, but without
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
292 having to load the entire file in memory. Only complete lines will be returned.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
293 ::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
294
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
295 >>> f.readlines()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
296 ['This is the first line of the file.\n', 'Second line of the file\n']
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
297
43413
409091b28c7e alternate -> alternative.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
298 An alternative approach to reading lines is to loop over the file object. This is
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
299 memory efficient, fast, and leads to simpler code::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
300
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
301 >>> for line in f:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
302 print line,
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
303
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
304 This is the first line of the file.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
305 Second line of the file
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
306
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
307 The alternative approach is simpler but does not provide as fine-grained
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
308 control. Since the two approaches manage line buffering differently, they
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
309 should not be mixed.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
310
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
311 ``f.write(string)`` writes the contents of *string* to the file, returning
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
312 ``None``. ::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
313
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
314 >>> f.write('This is a test\n')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
315
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
316 To write something other than a string, it needs to be converted to a string
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
317 first::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
318
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
319 >>> value = ('the answer', 42)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
320 >>> s = str(value)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
321 >>> f.write(s)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
322
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
323 ``f.tell()`` returns an integer giving the file object's current position in the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
324 file, measured in bytes from the beginning of the file. To change the file
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
325 object's position, use ``f.seek(offset, from_what)``. The position is computed
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
326 from adding *offset* to a reference point; the reference point is selected by
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
327 the *from_what* argument. A *from_what* value of 0 measures from the beginning
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
328 of the file, 1 uses the current file position, and 2 uses the end of the file as
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
329 the reference point. *from_what* can be omitted and defaults to 0, using the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
330 beginning of the file as the reference point. ::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
331
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
332 >>> f = open('/tmp/workfile', 'r+')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
333 >>> f.write('0123456789abcdef')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
334 >>> f.seek(5) # Go to the 6th byte in the file
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
335 >>> f.read(1)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
336 '5'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
337 >>> f.seek(-3, 2) # Go to the 3rd byte before the end
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
338 >>> f.read(1)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
339 'd'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
340
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
341 When you're done with a file, call ``f.close()`` to close it and free up any
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
342 system resources taken up by the open file. After calling ``f.close()``,
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
343 attempts to use the file object will automatically fail. ::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
344
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
345 >>> f.close()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
346 >>> f.read()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
347 Traceback (most recent call last):
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
348 File "<stdin>", line 1, in ?
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
349 ValueError: I/O operation on closed file
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
350
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
351 File objects have some additional methods, such as :meth:`isatty` and
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
352 :meth:`truncate` which are less frequently used; consult the Library Reference
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
353 for a complete guide to file objects.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
354
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
355
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
356 .. _tut-pickle:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
357
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
358 The :mod:`pickle` Module
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
359 ------------------------
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
360
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
361 .. index:: module: pickle
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
362
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
363 Strings can easily be written to and read from a file. Numbers take a bit more
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
364 effort, since the :meth:`read` method only returns strings, which will have to
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
365 be passed to a function like :func:`int`, which takes a string like ``'123'``
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
366 and returns its numeric value 123. However, when you want to save more complex
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
367 data types like lists, dictionaries, or class instances, things get a lot more
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
368 complicated.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
369
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
370 Rather than have users be constantly writing and debugging code to save
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
371 complicated data types, Python provides a standard module called :mod:`pickle`.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
372 This is an amazing module that can take almost any Python object (even some
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
373 forms of Python code!), and convert it to a string representation; this process
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
374 is called :dfn:`pickling`. Reconstructing the object from the string
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
375 representation is called :dfn:`unpickling`. Between pickling and unpickling,
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
376 the string representing the object may have been stored in a file or data, or
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
377 sent over a network connection to some distant machine.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
378
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
379 If you have an object ``x``, and a file object ``f`` that's been opened for
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
380 writing, the simplest way to pickle the object takes only one line of code::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
381
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
382 pickle.dump(x, f)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
383
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
384 To unpickle the object again, if ``f`` is a file object which has been opened
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
385 for reading::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
386
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
387 x = pickle.load(f)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
388
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
389 (There are other variants of this, used when pickling many objects or when you
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
390 don't want to write the pickled data to a file; consult the complete
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
391 documentation for :mod:`pickle` in the Python Library Reference.)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
392
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
393 :mod:`pickle` is the standard way to make Python objects which can be stored and
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
394 reused by other programs or by a future invocation of the same program; the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
395 technical term for this is a :dfn:`persistent` object. Because :mod:`pickle` is
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
396 so widely used, many authors who write Python extensions take care to ensure
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
397 that new data types such as matrices can be properly pickled and unpickled.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
398
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
399