Mercurial > cpython-lru_cache-weakref

annotate Doc/tutorial/inputoutput.rst @ 64158:ea0decd2acfb

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Fix typo
author Éric Araujo <merwok@netwok.org>
date Wed, 18 Aug 2010 22:35:23 +0000
parents afbb2b2ff6f7
children bed950cbd0c0
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.'"
54927
e3025a4c0ad7 Merged revisions 73636 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 51776
diff changeset
55 >>> str(1.0/7.0)
e3025a4c0ad7 Merged revisions 73636 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 51776
diff changeset
56 '0.142857142857'
e3025a4c0ad7 Merged revisions 73636 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 51776
diff changeset
57 >>> repr(1.0/7.0)
e3025a4c0ad7 Merged revisions 73636 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 51776
diff changeset
58 '0.14285714285714285'
42604
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))
50563
93cf3a6ead63 Merged revisions 68226 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48668
diff changeset
93 ...
42604
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
55797
afbb2b2ff6f7 Merged revisions 74613,74615,74619-74620,74622 via svnmerge from
Georg Brandl <georg@python.org>
parents: 55584
diff changeset
129 >>> 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
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
55797
afbb2b2ff6f7 Merged revisions 74613,74615,74619-74620,74622 via svnmerge from
Georg Brandl <georg@python.org>
parents: 55584
diff changeset
133 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
134 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
135 :meth:`~str.format` method. ::
47283
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
136
48577
71532ad7f3ed fix print syntax in tutorial
Benjamin Peterson <benjamin@python.org>
parents: 48563
diff changeset
137 >>> print('{0} and {1}'.format('spam', 'eggs'))
47283
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
138 spam and eggs
48577
71532ad7f3ed fix print syntax in tutorial
Benjamin Peterson <benjamin@python.org>
parents: 48563
diff changeset
139 >>> print('{1} and {0}'.format('spam', 'eggs'))
47283
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
140 eggs and spam
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
141
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
142 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
143 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
144
48578
b8d4dbb2938a Merged revisions 65253 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 48577
diff changeset
145 >>> print('This {food} is {adjective}.'.format(
b8d4dbb2938a Merged revisions 65253 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 48577
diff changeset
146 ... food='spam', adjective='absolutely horrible'))
47283
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
147 This spam is absolutely horrible.
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
148
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
149 Positional and keyword arguments can be arbitrarily combined::
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
150
48578
b8d4dbb2938a Merged revisions 65253 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 48577
diff changeset
151 >>> 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
152 other='Georg'))
47283
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
153 The story of Bill, Manfred, and Georg.
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
154
55797
afbb2b2ff6f7 Merged revisions 74613,74615,74619-74620,74622 via svnmerge from
Georg Brandl <georg@python.org>
parents: 55584
diff changeset
155 ``'!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
156 (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
157
afbb2b2ff6f7 Merged revisions 74613,74615,74619-74620,74622 via svnmerge from
Georg Brandl <georg@python.org>
parents: 55584
diff changeset
158 >>> import math
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 {}.'.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.14159265359.
afbb2b2ff6f7 Merged revisions 74613,74615,74619-74620,74622 via svnmerge from
Georg Brandl <georg@python.org>
parents: 55584
diff changeset
161 >>> 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
162 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
163
55584
5fbac09c0e91 Merged revisions 74264 via svnmerge from
Georg Brandl <georg@python.org>
parents: 55580
diff changeset
164 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
165 greater control over how the value is formatted. The following example
55584
5fbac09c0e91 Merged revisions 74264 via svnmerge from
Georg Brandl <georg@python.org>
parents: 55580
diff changeset
166 truncates 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
167
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
168 >>> import math
47283
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
169 >>> 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
170 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
171
47283
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
172 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
173 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
174
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
175 >>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 7678}
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
176 >>> for name, phone in table.items():
47283
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
177 ... 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
178 ...
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
179 Jack ==> 4098
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
180 Dcab ==> 7678
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
181 Sjoerd ==> 4127
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
182
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
183 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
184 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
185 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
186 square brackets ``'[]'`` to access the keys ::
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
187
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
188 >>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 8637678}
48578
b8d4dbb2938a Merged revisions 65253 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 48577
diff changeset
189 >>> 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
190 'Dcab: {0[Dcab]:d}'.format(table))
47283
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
191 Jack: 4098; Sjoerd: 4127; Dcab: 8637678
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
192
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
193 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
194 notation. ::
47283
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 >>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 8637678}
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
197 >>> 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
198 Jack: 4098; Sjoerd: 4127; Dcab: 8637678
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
199
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
200 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
201 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
202
51776
d06a3ebf306f Merged revisions 69846 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 50569
diff changeset
203 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
204 :ref:`formatstrings`.
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
205
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 Old string formatting
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
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
210 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
211 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
212 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
213 operation. For example::
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
214
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
215 >>> import math
48655
1635891b18e8 #3503: fix print statements in 3k doc.
Georg Brandl <georg@python.org>
parents: 48578
diff changeset
216 >>> 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
217 The value of PI is approximately 3.142.
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
218
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
219 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
220 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
221 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
222
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
223 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
224
42604
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 .. _tut-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 Reading and Writing Files
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
229 =========================
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
230
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
231 .. index::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
232 builtin: open
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
233 object: file
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
234
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
235 :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
236 arguments: ``open(filename, mode)``.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
237
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
238 ::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
239
44396
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents: 43440
diff changeset
240 >>> f = open('/tmp/workfile', 'w')
48668
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
241
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
242 .. 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
243
43115
95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois.
Guido van Rossum <guido@python.org>
parents: 42604
diff changeset
244 >>> print(f)
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
245 <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
246
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
247 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
248 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
249 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
250 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
251 ``'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
252 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
253 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
254 omitted.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
255
48668
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
256 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
257 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
258 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
259 :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
260 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
261
48668
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
262 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
263 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
264 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
265 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
266 :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
267 reading and writing such files.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
268
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
269
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
270 .. _tut-filemethods:
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 Methods of File Objects
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
273 -----------------------
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
274
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
275 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
276 ``f`` has already been created.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
277
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
278 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
279 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
280 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
281 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
282 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
283 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
284 string (``''``). ::
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
285
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 'This is the entire file.\n'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
288 >>> f.read()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
289 ''
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
290
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
291 ``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
292 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
293 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
294 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
295 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
296 containing only a single newline. ::
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
297
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 '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
300 >>> f.readline()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
301 'Second line of the file\n'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
302 >>> f.readline()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
303 ''
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
304
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
305 ``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
306 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
307 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
308 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
309 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
310 ::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
311
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
312 >>> f.readlines()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
313 ['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
314
43418
0c8fec76111c Merged revisions 58211-58220 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 43219
diff changeset
315 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
316 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
317
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
318 >>> for line in f:
48668
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
319 ... print(line, end='')
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
320 ...
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
321 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
322 Second line of the file
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 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
325 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
326 should not be mixed.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
327
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
328 ``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
329 the number of characters written. ::
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
330
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
331 >>> 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
332 15
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
333
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
334 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
335 first::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
336
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
337 >>> value = ('the answer', 42)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
338 >>> s = str(value)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
339 >>> f.write(s)
48668
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
340 18
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
341
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
342 ``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
343 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
344 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
345 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
346 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
347 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
348 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
349 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
350
48668
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
351 >>> f = open('/tmp/workfile', 'rb+')
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
352 >>> f.write(b'0123456789abcdef')
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
353 16
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
354 >>> 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
355 5
50563
93cf3a6ead63 Merged revisions 68226 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48668
diff changeset
356 >>> f.read(1)
48668
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
357 b'5'
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
358 >>> 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
359 13
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
360 >>> f.read(1)
48668
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
361 b'd'
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
362
48668
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
363 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
364 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
365 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
366
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
367 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
368 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
369 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
370
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
371 >>> f.close()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
372 >>> f.read()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
373 Traceback (most recent call last):
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
374 File "<stdin>", line 1, in ?
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
375 ValueError: I/O operation on closed file
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
376
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
377 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
378 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
379 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
380 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
381
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 >>> 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
383 ... 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
384 >>> 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
385 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
386
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
387 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
388 :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
389 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
390
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 .. _tut-pickle:
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 The :mod:`pickle` Module
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
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
397 .. index:: module: pickle
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
398
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
399 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
400 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
401 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
402 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
403 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
404 complicated.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
405
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
406 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
407 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
408 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
409 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
410 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
411 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
412 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
413 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
414
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
415 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
416 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
417
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
418 pickle.dump(x, f)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
419
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
420 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
421 for reading::
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 x = pickle.load(f)
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 (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
426 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
427 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
428
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
429 :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
430 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
431 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
432 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
433 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
434
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
435