Mercurial > cpython-lru_cache-weakref

annotate Doc/tutorial/inputoutput.rst @ 49961:e793fc3c8abe

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
More 3.0 -> 3.1 transistion in the Windows and OS/2 build files
author Christian Heimes <christian@cheimes.de>
date Thu, 04 Dec 2008 14:27:25 +0000
parents e2c706f9906c
children 93cf3a6ead63
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
43115
95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois.
Guido van Rossum <guido@python.org>
parents: 42604
diff changeset
18 the :func:`print` function. (A third way is using the :meth:`write` method
42604
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
47283
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
30 way is to use the :meth:`str.format` method.
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
31
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
32 The :mod:`string` module contains a class Template which offers yet another way
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
33 to substitute values into strings.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
34
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
35 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
36 Python has ways to convert any value to a string: pass it to the :func:`repr`
48666
fd7b93a01c04 #3523: no backquotes any more.
Georg Brandl <georg@python.org>
parents: 48655
diff changeset
37 or :func:`str` functions.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
38
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
39 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
40 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
41 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
42 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
43 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
44 :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
45 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
46 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
47
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
48 Some examples::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
49
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
50 >>> s = 'Hello, world.'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
51 >>> str(s)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
52 'Hello, world.'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
53 >>> repr(s)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
54 "'Hello, world.'"
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
55 >>> str(0.1)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
56 '0.1'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
57 >>> repr(0.1)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
58 '0.10000000000000001'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
59 >>> x = 10 * 3.25
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
60 >>> y = 200 * 200
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
61 >>> s = 'The value of x is ' + repr(x) + ', and y is ' + repr(y) + '...'
43115
95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois.
Guido van Rossum <guido@python.org>
parents: 42604
diff changeset
62 >>> print(s)
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
63 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
64 >>> # 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
65 ... hello = 'hello, world\n'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
66 >>> hellos = repr(hello)
43115
95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois.
Guido van Rossum <guido@python.org>
parents: 42604
diff changeset
67 >>> print(hellos)
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
68 'hello, world\n'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
69 >>> # 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
70 ... repr((x, y, ('spam', 'eggs')))
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
71 "(32.5, 40000, ('spam', 'eggs'))"
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
72
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
73 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
74
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
75 >>> for x in range(1, 11):
43201
4902671dd678 Tutorial formatting patch by Robin Stocker.
Georg Brandl <georg@python.org>
parents: 43115
diff changeset
76 ... print(repr(x).rjust(2), repr(x*x).rjust(3), end=' ')
43115
95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois.
Guido van Rossum <guido@python.org>
parents: 42604
diff changeset
77 ... # Note use of 'end' on previous line
95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois.
Guido van Rossum <guido@python.org>
parents: 42604
diff changeset
78 ... print(repr(x*x*x).rjust(4))
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
79 ...
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
80 1 1 1
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
81 2 4 8
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
82 3 9 27
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
83 4 16 64
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
84 5 25 125
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
85 6 36 216
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
86 7 49 343
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
87 8 64 512
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
88 9 81 729
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
89 10 100 1000
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
90
43201
4902671dd678 Tutorial formatting patch by Robin Stocker.
Georg Brandl <georg@python.org>
parents: 43115
diff changeset
91 >>> for x in range(1, 11):
47283
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
92 ... 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
93 ...
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
94 1 1 1
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
95 2 4 8
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
96 3 9 27
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
97 4 16 64
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
98 5 25 125
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
99 6 36 216
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
100 7 49 343
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
101 8 64 512
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
102 9 81 729
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
103 10 100 1000
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
104
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
105 (Note that in the first example, one space between each column was added by the
43115
95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois.
Guido van Rossum <guido@python.org>
parents: 42604
diff changeset
106 way :func:`print` works: it always adds spaces between its arguments.)
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
107
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
108 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
109 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
110 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
111 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
112 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
113 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
114 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
115 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
116
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
117 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
118 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
119
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
120 >>> '12'.zfill(5)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
121 '00012'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
122 >>> '-3.14'.zfill(7)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
123 '-003.14'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
124 >>> '3.14159265359'.zfill(5)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
125 '3.14159265359'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
126
47283
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
127 Basic usage of the :meth:`str.format` method looks like this::
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
128
48577
71532ad7f3ed fix print syntax in tutorial
Benjamin Peterson <benjamin@python.org>
parents: 48563
diff changeset
129 >>> print('We are the {0} who say "{1}!"'.format('knights', 'Ni'))
47283
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
130 We are the knights who say "Ni!"
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
131
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
132 The brackets and characters within them (called format fields) are replaced with
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
133 the objects passed into the format method. The number in the brackets refers to
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
134 the position of the object passed into the format method. ::
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
135
48577
71532ad7f3ed fix print syntax in tutorial
Benjamin Peterson <benjamin@python.org>
parents: 48563
diff changeset
136 >>> print('{0} and {1}'.format('spam', 'eggs'))
47283
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
137 spam and eggs
48577
71532ad7f3ed fix print syntax in tutorial
Benjamin Peterson <benjamin@python.org>
parents: 48563
diff changeset
138 >>> print('{1} and {0}'.format('spam', 'eggs'))
47283
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
139 eggs and spam
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
140
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
141 If keyword arguments are used in the format method, their values are referred to
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
142 by using the name of the argument. ::
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
143
48578
b8d4dbb2938a Merged revisions 65253 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 48577
diff changeset
144 >>> print('This {food} is {adjective}.'.format(
b8d4dbb2938a Merged revisions 65253 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 48577
diff changeset
145 ... food='spam', adjective='absolutely horrible'))
47283
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
146 This spam is absolutely horrible.
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
147
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
148 Positional and keyword arguments can be arbitrarily combined::
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
149
48578
b8d4dbb2938a Merged revisions 65253 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 48577
diff changeset
150 >>> print('The story of {0}, {1}, and {other}.'.format('Bill', 'Manfred',
b8d4dbb2938a Merged revisions 65253 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 48577
diff changeset
151 other='Georg'))
47283
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
152 The story of Bill, Manfred, and Georg.
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
153
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
154 An optional ``':``` and format specifier can follow the field name. This also
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
155 greater control over how the value is formatted. The following example
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
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
47283
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
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
47283
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
162 Passing an integer after the ``':'`` will cause that field to be a minimum
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
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():
47283
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
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
47283
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
175 instead of by position. This can be done by simply passing the dict and using
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
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}
48578
b8d4dbb2938a Merged revisions 65253 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 48577
diff changeset
179 >>> print('Jack: {0[Jack]:d}; Sjoerd: {0[Sjoerd]:d}; '
b8d4dbb2938a Merged revisions 65253 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 48577
diff changeset
180 'Dcab: {0[Dcab]:d}'.format(table))
47283
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
181 Jack: 4098; Sjoerd: 4127; Dcab: 8637678
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
182
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
183 This could also be done by passing the table as keyword arguments with the '**'
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
184 notation.::
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
185
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
186 >>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 8637678}
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
187 >>> 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
188 Jack: 4098; Sjoerd: 4127; Dcab: 8637678
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
189
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
190 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
191 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
192
47283
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
193 For a complete overview of string formating with :meth:`str.format`, see
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
194 :ref:`formatstrings`.
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
195
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
196
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
197 Old string formatting
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
198 ---------------------
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
199
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
200 The ``%`` operator can also be used for string formatting. It interprets the
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
201 left argument much like a :cfunc:`sprintf`\ -style format string to be applied
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
202 to the right argument, and returns the string resulting from this formatting
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
203 operation. For example::
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
204
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
205 >>> import math
48655
1635891b18e8 #3503: fix print statements in 3k doc.
Georg Brandl <georg@python.org>
parents: 48578
diff changeset
206 >>> print('The value of PI is approximately %5.3f.' % math.pi)
47283
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
207 The value of PI is approximately 3.142.
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
208
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
209 Since :meth:`str.format` is quite new, a lot of Python code still uses the ``%``
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
210 operator. However, because this old style of formatting will eventually removed
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
211 from the language :meth:`str.format` should generally be used.
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
212
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
213 More information can be found in the :ref:`old-string-formatting` section.
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
214
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
215
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
216 .. _tut-files:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
217
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
218 Reading and Writing Files
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
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
221 .. index::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
222 builtin: open
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
223 object: file
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
224
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
225 :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
226 arguments: ``open(filename, mode)``.
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 ::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
229
44396
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents: 43440
diff changeset
230 >>> f = open('/tmp/workfile', 'w')
48668
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
231
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
232 .. XXX str(f) is <io.TextIOWrapper object at 0x82e8dc4>
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
233
43115
95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois.
Guido van Rossum <guido@python.org>
parents: 42604
diff changeset
234 >>> print(f)
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
235 <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
236
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
237 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
238 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
239 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
240 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
241 ``'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
242 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
243 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
244 omitted.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
245
48668
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
246 Normally, files are opened in :dfn:`text mode`, that means, you read and write
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
247 strings from and to the file, which are encoded in a specific encoding (the
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
248 default being UTF-8). ``'b'`` appended to the mode opens the file in
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
249 :dfn:`binary mode`: now the data is read and written in the form of bytes
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
250 objects. This mode should be used for all files that don't contain text.
43440
8d7e93b47cab Clarify the difference between text and binary files. I'm not sure the
Skip Montanaro <skip@pobox.com>
parents: 43418
diff changeset
251
48668
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
252 In text mode, the default is to convert platform-specific line endings (``\n``
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
253 on Unix, ``\r\n`` on Windows) to just ``\n`` on reading and ``\n`` back to
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
254 platform-specific line endings on writing. This behind-the-scenes modification
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
255 to file data is fine for text files, but will corrupt binary data like that in
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
256 :file:`JPEG` or :file:`EXE` files. Be very careful to use binary mode when
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
257 reading and writing such files.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
258
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
259
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
260 .. _tut-filemethods:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
261
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
262 Methods of File Objects
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
263 -----------------------
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
264
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
265 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
266 ``f`` has already been created.
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 To read a file's contents, call ``f.read(size)``, which reads some quantity of
48668
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
269 data and returns it as a string or bytes object. *size* is an optional numeric
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
270 argument. When *size* is omitted or negative, the entire contents of the file
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
271 will be read and returned; it's your problem if the file is twice as large as
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
272 your machine's memory. Otherwise, at most *size* bytes are read and returned.
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
273 If the end of the file has been reached, ``f.read()`` will return an empty
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
274 string (``''``). ::
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
275
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
276 >>> f.read()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
277 'This is the entire file.\n'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
278 >>> f.read()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
279 ''
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()`` 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
282 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
283 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
284 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
285 has been reached, while a blank line is represented by ``'\n'``, a string
48668
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
286 containing only a single newline. ::
42604
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.readline()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
289 '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
290 >>> f.readline()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
291 'Second line of the file\n'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
292 >>> f.readline()
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()`` 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
296 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
297 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
298 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
299 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
300 ::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
301
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
302 >>> f.readlines()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
303 ['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
304
43418
0c8fec76111c Merged revisions 58211-58220 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 43219
diff changeset
305 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
306 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
307
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
308 >>> for line in f:
48668
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
309 ... print(line, end='')
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
310 ...
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
311 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
312 Second line of the file
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 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
315 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
316 should not be mixed.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
317
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
318 ``f.write(string)`` writes the contents of *string* to the file, returning
48668
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
319 the number of characters written. ::
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
320
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
321 >>> f.write('This is a test\n')
48668
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
322 15
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
323
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
324 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
325 first::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
326
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
327 >>> value = ('the answer', 42)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
328 >>> s = str(value)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
329 >>> f.write(s)
48668
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
330 18
42604
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.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
333 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
334 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
335 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
336 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
337 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
338 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
339 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
340
48668
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
341 >>> f = open('/tmp/workfile', 'rb+')
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
342 >>> f.write(b'0123456789abcdef')
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
343 16
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
344 >>> f.seek(5) # Go to the 6th byte in the file
48668
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
345 5
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
346 >>> f.read(1)
48668
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
347 b'5'
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
348 >>> f.seek(-3, 2) # Go to the 3rd byte before the end
48668
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
349 13
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
350 >>> f.read(1)
48668
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
351 b'd'
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
352
48668
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
353 In text files (those opened without a ``b`` in the mode string), only seeks
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
354 relative to the beginning of the file are allowed (the exception being seeking
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
355 to the very file end with ``seek(0, 2)``).
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
356
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
357 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
358 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
359 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
360
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
361 >>> f.close()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
362 >>> f.read()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
363 Traceback (most recent call last):
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
364 File "<stdin>", line 1, in ?
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
365 ValueError: I/O operation on closed file
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
366
48563
b51cd5d3795c Merged revisions 65012,65035,65037-65040,65048,65057,65077,65091-65095,65097-65099,65127-65128,65131,65133-65136,65139,65149-65151,65155,65158-65159,65176-65178,65183-65184,65187-65190,65192,65194 via svnmerge from
Georg Brandl <georg@python.org>
parents: 47283
diff changeset
367 It is good practice to use the :keyword:`with` keyword when dealing with file
b51cd5d3795c Merged revisions 65012,65035,65037-65040,65048,65057,65077,65091-65095,65097-65099,65127-65128,65131,65133-65136,65139,65149-65151,65155,65158-65159,65176-65178,65183-65184,65187-65190,65192,65194 via svnmerge from
Georg Brandl <georg@python.org>
parents: 47283
diff changeset
368 objects. This has the advantage that the file is properly closed after its
b51cd5d3795c Merged revisions 65012,65035,65037-65040,65048,65057,65077,65091-65095,65097-65099,65127-65128,65131,65133-65136,65139,65149-65151,65155,65158-65159,65176-65178,65183-65184,65187-65190,65192,65194 via svnmerge from
Georg Brandl <georg@python.org>
parents: 47283
diff changeset
369 suite finishes, even if an exception is raised on the way. It is also much
b51cd5d3795c Merged revisions 65012,65035,65037-65040,65048,65057,65077,65091-65095,65097-65099,65127-65128,65131,65133-65136,65139,65149-65151,65155,65158-65159,65176-65178,65183-65184,65187-65190,65192,65194 via svnmerge from
Georg Brandl <georg@python.org>
parents: 47283
diff changeset
370 shorter than writing equivalent :keyword:`try`\ -\ :keyword:`finally` blocks::
b51cd5d3795c Merged revisions 65012,65035,65037-65040,65048,65057,65077,65091-65095,65097-65099,65127-65128,65131,65133-65136,65139,65149-65151,65155,65158-65159,65176-65178,65183-65184,65187-65190,65192,65194 via svnmerge from
Georg Brandl <georg@python.org>
parents: 47283
diff changeset
371
b51cd5d3795c Merged revisions 65012,65035,65037-65040,65048,65057,65077,65091-65095,65097-65099,65127-65128,65131,65133-65136,65139,65149-65151,65155,65158-65159,65176-65178,65183-65184,65187-65190,65192,65194 via svnmerge from
Georg Brandl <georg@python.org>
parents: 47283
diff changeset
372 >>> with open('/tmp/workfile', 'r') as f:
b51cd5d3795c Merged revisions 65012,65035,65037-65040,65048,65057,65077,65091-65095,65097-65099,65127-65128,65131,65133-65136,65139,65149-65151,65155,65158-65159,65176-65178,65183-65184,65187-65190,65192,65194 via svnmerge from
Georg Brandl <georg@python.org>
parents: 47283
diff changeset
373 ... read_data = f.read()
b51cd5d3795c Merged revisions 65012,65035,65037-65040,65048,65057,65077,65091-65095,65097-65099,65127-65128,65131,65133-65136,65139,65149-65151,65155,65158-65159,65176-65178,65183-65184,65187-65190,65192,65194 via svnmerge from
Georg Brandl <georg@python.org>
parents: 47283
diff changeset
374 >>> f.closed
b51cd5d3795c Merged revisions 65012,65035,65037-65040,65048,65057,65077,65091-65095,65097-65099,65127-65128,65131,65133-65136,65139,65149-65151,65155,65158-65159,65176-65178,65183-65184,65187-65190,65192,65194 via svnmerge from
Georg Brandl <georg@python.org>
parents: 47283
diff changeset
375 True
b51cd5d3795c Merged revisions 65012,65035,65037-65040,65048,65057,65077,65091-65095,65097-65099,65127-65128,65131,65133-65136,65139,65149-65151,65155,65158-65159,65176-65178,65183-65184,65187-65190,65192,65194 via svnmerge from
Georg Brandl <georg@python.org>
parents: 47283
diff changeset
376
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
377 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
378 :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
379 for a complete guide to file objects.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
380
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 .. _tut-pickle:
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 The :mod:`pickle` Module
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
385 ------------------------
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 .. index:: module: pickle
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 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
390 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
391 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
392 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
393 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
394 complicated.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
395
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
396 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
397 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
398 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
399 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
400 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
401 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
402 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
403 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
404
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
405 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
406 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
407
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
408 pickle.dump(x, f)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
409
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
410 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
411 for reading::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
412
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
413 x = pickle.load(f)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
414
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
415 (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
416 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
417 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
418
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
419 :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
420 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
421 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
422 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
423 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
424
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
425