Mercurial > cpython-lru_cache-weakref

annotate Doc/tutorial/inputoutput.rst @ 68401:45d76bb9fbcd 3.2

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
merge 3.1
author Benjamin Peterson <benjamin@python.org>
date Sat, 12 Mar 2011 11:58:40 -0600
parents 624bcf3adab5
children 4a68f4cfbdc8
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 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
23 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
24 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
25 concatenation operations you can create any layout you can imagine. The
68285
59e464a1bbf0 #11405: do not reference the string module again for its deprecated functions, only for Template class.
Georg Brandl <georg@python.org>
parents: 64763
diff changeset
26 string type has some methods that perform useful operations for padding
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
27 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
28 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
29
68285
59e464a1bbf0 #11405: do not reference the string module again for its deprecated functions, only for Template class.
Georg Brandl <georg@python.org>
parents: 64763
diff changeset
30 The :mod:`string` module contains a :class:`~string.Template` class which offers
59e464a1bbf0 #11405: do not reference the string module again for its deprecated functions, only for Template class.
Georg Brandl <georg@python.org>
parents: 64763
diff changeset
31 yet another way to substitute values into strings.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
32
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
33 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
34 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
35 or :func:`str` functions.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
36
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
37 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
38 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
39 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
40 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
41 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
42 :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
43 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
44 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
45
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
46 Some examples::
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 >>> s = 'Hello, world.'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
49 >>> str(s)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
50 'Hello, world.'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
51 >>> repr(s)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
52 "'Hello, world.'"
54927
e3025a4c0ad7 Merged revisions 73636 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 51776
diff changeset
53 >>> str(1.0/7.0)
e3025a4c0ad7 Merged revisions 73636 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 51776
diff changeset
54 '0.142857142857'
e3025a4c0ad7 Merged revisions 73636 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 51776
diff changeset
55 >>> repr(1.0/7.0)
e3025a4c0ad7 Merged revisions 73636 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 51776
diff changeset
56 '0.14285714285714285'
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
57 >>> x = 10 * 3.25
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
58 >>> y = 200 * 200
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
59 >>> 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
60 >>> print(s)
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
61 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
62 >>> # 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
63 ... hello = 'hello, world\n'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
64 >>> hellos = repr(hello)
43115
95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois.
Guido van Rossum <guido@python.org>
parents: 42604
diff changeset
65 >>> print(hellos)
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
66 'hello, world\n'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
67 >>> # 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
68 ... repr((x, y, ('spam', 'eggs')))
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
69 "(32.5, 40000, ('spam', 'eggs'))"
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
70
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
71 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
72
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
73 >>> for x in range(1, 11):
43201
4902671dd678 Tutorial formatting patch by Robin Stocker.
Georg Brandl <georg@python.org>
parents: 43115
diff changeset
74 ... 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
75 ... # 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
76 ... 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
77 ...
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
78 1 1 1
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
79 2 4 8
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
80 3 9 27
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
81 4 16 64
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
82 5 25 125
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
83 6 36 216
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
84 7 49 343
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
85 8 64 512
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
86 9 81 729
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
87 10 100 1000
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
88
43201
4902671dd678 Tutorial formatting patch by Robin Stocker.
Georg Brandl <georg@python.org>
parents: 43115
diff changeset
89 >>> for x in range(1, 11):
47283
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
90 ... print('{0:2d} {1:3d} {2:4d}'.format(x, x*x, x*x*x))
50563
93cf3a6ead63 Merged revisions 68226 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48668
diff changeset
91 ...
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
92 1 1 1
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
93 2 4 8
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
94 3 9 27
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
95 4 16 64
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
96 5 25 125
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
97 6 36 216
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
98 7 49 343
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
99 8 64 512
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
100 9 81 729
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
101 10 100 1000
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
102
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
103 (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
104 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
105
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
106 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
107 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
108 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
109 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
110 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
111 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
112 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
113 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
114
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
115 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
116 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
117
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
118 >>> '12'.zfill(5)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
119 '00012'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
120 >>> '-3.14'.zfill(7)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
121 '-003.14'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
122 >>> '3.14159265359'.zfill(5)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
123 '3.14159265359'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
124
47283
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
125 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
126
55797
afbb2b2ff6f7 Merged revisions 74613,74615,74619-74620,74622 via svnmerge from
Georg Brandl <georg@python.org>
parents: 55584
diff changeset
127 >>> print('We are the {} who say "{}!"'.format('knights', 'Ni'))
47283
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
128 We are the knights who say "Ni!"
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
129
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
130 The brackets and characters within them (called format fields) are replaced with
55797
afbb2b2ff6f7 Merged revisions 74613,74615,74619-74620,74622 via svnmerge from
Georg Brandl <georg@python.org>
parents: 55584
diff changeset
131 the objects passed into the :meth:`~str.format` method. A number in the
afbb2b2ff6f7 Merged revisions 74613,74615,74619-74620,74622 via svnmerge from
Georg Brandl <georg@python.org>
parents: 55584
diff changeset
132 brackets can be used to refer to the position of the object passed into the
55580
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from
Georg Brandl <georg@python.org>
parents: 54927
diff changeset
133 :meth:`~str.format` method. ::
47283
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
134
48577
71532ad7f3ed fix print syntax in tutorial
Benjamin Peterson <benjamin@python.org>
parents: 48563
diff changeset
135 >>> print('{0} and {1}'.format('spam', 'eggs'))
47283
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
136 spam and eggs
48577
71532ad7f3ed fix print syntax in tutorial
Benjamin Peterson <benjamin@python.org>
parents: 48563
diff changeset
137 >>> print('{1} and {0}'.format('spam', 'eggs'))
47283
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
138 eggs and spam
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
139
55580
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from
Georg Brandl <georg@python.org>
parents: 54927
diff changeset
140 If keyword arguments are used in the :meth:`~str.format` method, their values
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from
Georg Brandl <georg@python.org>
parents: 54927
diff changeset
141 are referred to by using the name of the argument. ::
47283
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
142
48578
b8d4dbb2938a Merged revisions 65253 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 48577
diff changeset
143 >>> print('This {food} is {adjective}.'.format(
b8d4dbb2938a Merged revisions 65253 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 48577
diff changeset
144 ... food='spam', adjective='absolutely horrible'))
47283
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
145 This spam is absolutely horrible.
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
146
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
147 Positional and keyword arguments can be arbitrarily combined::
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
148
48578
b8d4dbb2938a Merged revisions 65253 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 48577
diff changeset
149 >>> 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
150 other='Georg'))
47283
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
151 The story of Bill, Manfred, and Georg.
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
152
55797
afbb2b2ff6f7 Merged revisions 74613,74615,74619-74620,74622 via svnmerge from
Georg Brandl <georg@python.org>
parents: 55584
diff changeset
153 ``'!a'`` (apply :func:`ascii`), ``'!s'`` (apply :func:`str`) and ``'!r'``
afbb2b2ff6f7 Merged revisions 74613,74615,74619-74620,74622 via svnmerge from
Georg Brandl <georg@python.org>
parents: 55584
diff changeset
154 (apply :func:`repr`) can be used to convert the value before it is formatted::
afbb2b2ff6f7 Merged revisions 74613,74615,74619-74620,74622 via svnmerge from
Georg Brandl <georg@python.org>
parents: 55584
diff changeset
155
afbb2b2ff6f7 Merged revisions 74613,74615,74619-74620,74622 via svnmerge from
Georg Brandl <georg@python.org>
parents: 55584
diff changeset
156 >>> import math
afbb2b2ff6f7 Merged revisions 74613,74615,74619-74620,74622 via svnmerge from
Georg Brandl <georg@python.org>
parents: 55584
diff changeset
157 >>> print('The value of PI is approximately {}.'.format(math.pi))
afbb2b2ff6f7 Merged revisions 74613,74615,74619-74620,74622 via svnmerge from
Georg Brandl <georg@python.org>
parents: 55584
diff changeset
158 The value of PI is approximately 3.14159265359.
afbb2b2ff6f7 Merged revisions 74613,74615,74619-74620,74622 via svnmerge from
Georg Brandl <georg@python.org>
parents: 55584
diff changeset
159 >>> print('The value of PI is approximately {!r}.'.format(math.pi))
afbb2b2ff6f7 Merged revisions 74613,74615,74619-74620,74622 via svnmerge from
Georg Brandl <georg@python.org>
parents: 55584
diff changeset
160 The value of PI is approximately 3.141592653589793.
afbb2b2ff6f7 Merged revisions 74613,74615,74619-74620,74622 via svnmerge from
Georg Brandl <georg@python.org>
parents: 55584
diff changeset
161
55584
5fbac09c0e91 Merged revisions 74264 via svnmerge from
Georg Brandl <georg@python.org>
parents: 55580
diff changeset
162 An optional ``':'`` and format specifier can follow the field name. This allows
47283
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
163 greater control over how the value is formatted. The following example
68121
9861dc118322 Issue #11304: Input/output tutorial - PI is rounded not truncated.
Raymond Hettinger <python@rcn.com>
parents: 65137
diff changeset
164 rounds 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
165
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
166 >>> import math
47283
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
167 >>> 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
168 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
169
47283
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
170 Passing an integer after the ``':'`` will cause that field to be a minimum
55580
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from
Georg Brandl <georg@python.org>
parents: 54927
diff changeset
171 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
172
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
173 >>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 7678}
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
174 >>> for name, phone in table.items():
47283
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
175 ... print('{0:10} ==> {1:10d}'.format(name, phone))
50563
93cf3a6ead63 Merged revisions 68226 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48668
diff changeset
176 ...
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
177 Jack ==> 4098
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
178 Dcab ==> 7678
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
179 Sjoerd ==> 4127
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
180
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
181 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
182 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
183 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
184 square brackets ``'[]'`` to access the keys ::
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
185
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
186 >>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 8637678}
48578
b8d4dbb2938a Merged revisions 65253 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 48577
diff changeset
187 >>> 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
188 'Dcab: {0[Dcab]:d}'.format(table))
47283
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
189 Jack: 4098; Sjoerd: 4127; Dcab: 8637678
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
190
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
191 This could also be done by passing the table as keyword arguments with the '**'
55580
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from
Georg Brandl <georg@python.org>
parents: 54927
diff changeset
192 notation. ::
47283
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
193
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
194 >>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 8637678}
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
195 >>> 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
196 Jack: 4098; Sjoerd: 4127; Dcab: 8637678
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
197
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
198 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
199 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
200
51776
d06a3ebf306f Merged revisions 69846 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 50569
diff changeset
201 For a complete overview of string formatting with :meth:`str.format`, see
47283
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
202 :ref:`formatstrings`.
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
203
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 Old string formatting
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
206 ---------------------
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
207
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
208 The ``%`` operator can also be used for string formatting. It interprets the
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64763
diff changeset
209 left argument much like a :c:func:`sprintf`\ -style format string to be applied
47283
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
210 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
211 operation. For example::
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 >>> import math
48655
1635891b18e8 #3503: fix print statements in 3k doc.
Georg Brandl <georg@python.org>
parents: 48578
diff changeset
214 >>> 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
215 The value of PI is approximately 3.142.
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
216
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
217 Since :meth:`str.format` is quite new, a lot of Python code still uses the ``%``
55584
5fbac09c0e91 Merged revisions 74264 via svnmerge from
Georg Brandl <georg@python.org>
parents: 55580
diff changeset
218 operator. However, because this old style of formatting will eventually be
5fbac09c0e91 Merged revisions 74264 via svnmerge from
Georg Brandl <georg@python.org>
parents: 55580
diff changeset
219 removed from the language, :meth:`str.format` should generally be used.
47283
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
220
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
221 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
222
42604
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 .. _tut-files:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
225
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
226 Reading and Writing Files
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 .. index::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
230 builtin: open
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
231 object: file
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
232
64763
bed950cbd0c0 Add cross-references to the glossary entry for file objects.
Antoine Pitrou <solipsis@pitrou.net>
parents: 55797
diff changeset
233 :func:`open` returns a :term:`file object`, and is most commonly used with
bed950cbd0c0 Add cross-references to the glossary entry for file objects.
Antoine Pitrou <solipsis@pitrou.net>
parents: 55797
diff changeset
234 two arguments: ``open(filename, mode)``.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
235
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
44396
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents: 43440
diff changeset
238 >>> f = open('/tmp/workfile', 'w')
48668
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
239
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
240 .. 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
241
43115
95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois.
Guido van Rossum <guido@python.org>
parents: 42604
diff changeset
242 >>> print(f)
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
243 <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
244
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
245 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
246 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
247 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
248 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
249 ``'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
250 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
251 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
252 omitted.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
253
48668
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
254 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
255 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
256 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
257 :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
258 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
259
48668
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
260 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
261 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
262 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
263 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
264 :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
265 reading and writing such files.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
266
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 .. _tut-filemethods:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
269
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
270 Methods of File Objects
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
271 -----------------------
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 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
274 ``f`` has already been created.
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 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
277 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
278 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
279 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
280 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
281 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
282 string (``''``). ::
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
283
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
284 >>> f.read()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
285 'This is the entire file.\n'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
286 >>> f.read()
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
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
289 ``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
290 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
291 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
292 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
293 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
294 containing only a single newline. ::
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
295
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
296 >>> f.readline()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
297 '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
298 >>> f.readline()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
299 'Second line of the file\n'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
300 >>> f.readline()
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
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
303 ``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
304 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
305 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
306 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
307 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
308 ::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
309
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
310 >>> f.readlines()
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.\n', 'Second line of the file\n']
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
312
43418
0c8fec76111c Merged revisions 58211-58220 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 43219
diff changeset
313 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
314 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
315
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
316 >>> for line in f:
48668
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
317 ... print(line, end='')
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
318 ...
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
319 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
320 Second line of the file
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
321
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
322 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
323 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
324 should not be mixed.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
325
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
326 ``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
327 the number of characters written. ::
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
328
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
329 >>> 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
330 15
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 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
333 first::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
334
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
335 >>> value = ('the answer', 42)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
336 >>> s = str(value)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
337 >>> f.write(s)
48668
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
338 18
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
339
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
340 ``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
341 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
342 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
343 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
344 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
345 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
346 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
347 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
348
48668
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
349 >>> f = open('/tmp/workfile', 'rb+')
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
350 >>> f.write(b'0123456789abcdef')
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
351 16
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
352 >>> 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
353 5
50563
93cf3a6ead63 Merged revisions 68226 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48668
diff changeset
354 >>> f.read(1)
48668
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
355 b'5'
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
356 >>> 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
357 13
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
358 >>> f.read(1)
48668
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
359 b'd'
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
360
48668
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
361 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
362 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
363 to the very file end with ``seek(0, 2)``).
50563
93cf3a6ead63 Merged revisions 68226 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48668
diff changeset
364
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
365 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
366 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
367 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
368
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
369 >>> f.close()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
370 >>> f.read()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
371 Traceback (most recent call last):
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
372 File "<stdin>", line 1, in ?
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
373 ValueError: I/O operation on closed file
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
374
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
375 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
376 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
377 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
378 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
379
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
380 >>> 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
381 ... 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
382 >>> 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
383 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
384
55580
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from
Georg Brandl <georg@python.org>
parents: 54927
diff changeset
385 File objects have some additional methods, such as :meth:`~file.isatty` and
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from
Georg Brandl <georg@python.org>
parents: 54927
diff changeset
386 :meth:`~file.truncate` which are less frequently used; consult the Library
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from
Georg Brandl <georg@python.org>
parents: 54927
diff changeset
387 Reference for a complete guide to file objects.
42604
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
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
390 .. _tut-pickle:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
391
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
392 The :mod:`pickle` Module
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
393 ------------------------
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
394
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
395 .. index:: module: pickle
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
396
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
397 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
398 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
399 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
400 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
401 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
402 complicated.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
403
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
404 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
405 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
406 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
407 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
408 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
409 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
410 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
411 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
412
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
413 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
414 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
415
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
416 pickle.dump(x, f)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
417
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
418 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
419 for reading::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
420
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
421 x = pickle.load(f)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
422
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
423 (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
424 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
425 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
426
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
427 :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
428 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
429 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
430 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
431 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
432
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
433