Mercurial > cpython-lru_cache-weakref

annotate Doc/tutorial/inputoutput.rst @ 87690:66c1c9f32567 default tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add use_weakref option to functools.lru_cache The use_weakref option makes lru_cache create weak references to the function arguments when creating the cache key, which prevents them from staying in the memory forever even after all other references to them are gone. This is a proof of concept for http://bugs.python.org/issue19859
author Radomir Dopieralski <devel@sheep.art.pl>
date Tue, 03 Dec 2013 16:02:48 +0100
parents 81bc2d64c006
children
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
78578
7e56c46f5707 fix typo
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68413
diff changeset
40 there is no equivalent syntax). For objects which don't have a particular
42604
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
68413
4a68f4cfbdc8 Merge with 3.1.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 68291 68411
diff changeset
43 dictionaries, have the same representation using either function. Strings, in
4a68f4cfbdc8 Merge with 3.1.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 68291 68411
diff changeset
44 particular, have two distinct representations.
42604
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.'"
68413
4a68f4cfbdc8 Merge with 3.1.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 68291 68411
diff changeset
53 >>> str(1/7)
54927
e3025a4c0ad7 Merged revisions 73636 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 51776
diff changeset
54 '0.14285714285714285'
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
55 >>> x = 10 * 3.25
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
56 >>> y = 200 * 200
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
57 >>> 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
58 >>> print(s)
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
59 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
60 >>> # 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
61 ... hello = 'hello, world\n'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
62 >>> hellos = repr(hello)
43115
95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois.
Guido van Rossum <guido@python.org>
parents: 42604
diff changeset
63 >>> print(hellos)
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
64 'hello, world\n'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
65 >>> # 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
66 ... repr((x, y, ('spam', 'eggs')))
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
67 "(32.5, 40000, ('spam', 'eggs'))"
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
68
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
69 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
70
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
71 >>> for x in range(1, 11):
43201
4902671dd678 Tutorial formatting patch by Robin Stocker.
Georg Brandl <georg@python.org>
parents: 43115
diff changeset
72 ... 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
73 ... # 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
74 ... 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
75 ...
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
76 1 1 1
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
77 2 4 8
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
78 3 9 27
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
79 4 16 64
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
80 5 25 125
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
81 6 36 216
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
82 7 49 343
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
83 8 64 512
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
84 9 81 729
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
85 10 100 1000
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
86
43201
4902671dd678 Tutorial formatting patch by Robin Stocker.
Georg Brandl <georg@python.org>
parents: 43115
diff changeset
87 >>> for x in range(1, 11):
47283
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
88 ... 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
89 ...
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
90 1 1 1
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
91 2 4 8
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
92 3 9 27
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
93 4 16 64
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
94 5 25 125
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
95 6 36 216
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
96 7 49 343
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
97 8 64 512
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
98 9 81 729
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
99 10 100 1000
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
100
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
101 (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
102 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
103
68411
87167b08312f Fix markup in inputoutput.rst.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 68285
diff changeset
104 This example demonstrates the :meth:`str.rjust` method of string
87167b08312f Fix markup in inputoutput.rst.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 68285
diff changeset
105 objects, which right-justifies a string in a field of a given width by padding
87167b08312f Fix markup in inputoutput.rst.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 68285
diff changeset
106 it with spaces on the left. There are similar methods :meth:`str.ljust` and
87167b08312f Fix markup in inputoutput.rst.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 68285
diff changeset
107 :meth:`str.center`. These methods do not write anything, they just return a
87167b08312f Fix markup in inputoutput.rst.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 68285
diff changeset
108 new string. If the input string is too long, they don't truncate it, but
87167b08312f Fix markup in inputoutput.rst.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 68285
diff changeset
109 return it unchanged; this will mess up your column lay-out but that's usually
87167b08312f Fix markup in inputoutput.rst.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 68285
diff changeset
110 better than the alternative, which would be lying about a value. (If you
87167b08312f Fix markup in inputoutput.rst.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 68285
diff changeset
111 really want truncation you can always add a slice operation, as in
87167b08312f Fix markup in inputoutput.rst.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 68285
diff changeset
112 ``x.ljust(n)[:n]``.)
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
113
68411
87167b08312f Fix markup in inputoutput.rst.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 68285
diff changeset
114 There is another method, :meth:`str.zfill`, which pads a numeric string on the
87167b08312f Fix markup in inputoutput.rst.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 68285
diff changeset
115 left with zeros. It understands about plus and minus signs::
42604
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 >>> '12'.zfill(5)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
118 '00012'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
119 >>> '-3.14'.zfill(7)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
120 '-003.14'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
121 >>> '3.14159265359'.zfill(5)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
122 '3.14159265359'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
123
47283
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
124 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
125
55797
afbb2b2ff6f7 Merged revisions 74613,74615,74619-74620,74622 via svnmerge from
Georg Brandl <georg@python.org>
parents: 55584
diff changeset
126 >>> 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
127 We are the knights who say "Ni!"
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
128
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
129 The brackets and characters within them (called format fields) are replaced with
68411
87167b08312f Fix markup in inputoutput.rst.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 68285
diff changeset
130 the objects passed into the :meth:`str.format` method. A number in the
55797
afbb2b2ff6f7 Merged revisions 74613,74615,74619-74620,74622 via svnmerge from
Georg Brandl <georg@python.org>
parents: 55584
diff changeset
131 brackets can be used to refer to the position of the object passed into the
68411
87167b08312f Fix markup in inputoutput.rst.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 68285
diff changeset
132 :meth:`str.format` method. ::
47283
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
133
48577
71532ad7f3ed fix print syntax in tutorial
Benjamin Peterson <benjamin@python.org>
parents: 48563
diff changeset
134 >>> print('{0} and {1}'.format('spam', 'eggs'))
47283
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
135 spam and eggs
48577
71532ad7f3ed fix print syntax in tutorial
Benjamin Peterson <benjamin@python.org>
parents: 48563
diff changeset
136 >>> print('{1} and {0}'.format('spam', 'eggs'))
47283
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
137 eggs and spam
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
138
68411
87167b08312f Fix markup in inputoutput.rst.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 68285
diff changeset
139 If keyword arguments are used in the :meth:`str.format` method, their values
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 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
141
48578
b8d4dbb2938a Merged revisions 65253 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 48577
diff changeset
142 >>> print('This {food} is {adjective}.'.format(
b8d4dbb2938a Merged revisions 65253 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 48577
diff changeset
143 ... food='spam', adjective='absolutely horrible'))
47283
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
144 This spam is absolutely horrible.
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
145
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
146 Positional and keyword arguments can be arbitrarily combined::
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
147
48578
b8d4dbb2938a Merged revisions 65253 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 48577
diff changeset
148 >>> 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
149 other='Georg'))
47283
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
150 The story of Bill, Manfred, and Georg.
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
151
55797
afbb2b2ff6f7 Merged revisions 74613,74615,74619-74620,74622 via svnmerge from
Georg Brandl <georg@python.org>
parents: 55584
diff changeset
152 ``'!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
153 (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
154
afbb2b2ff6f7 Merged revisions 74613,74615,74619-74620,74622 via svnmerge from
Georg Brandl <georg@python.org>
parents: 55584
diff changeset
155 >>> import math
afbb2b2ff6f7 Merged revisions 74613,74615,74619-74620,74622 via svnmerge from
Georg Brandl <georg@python.org>
parents: 55584
diff changeset
156 >>> 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
157 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
158 >>> 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
159 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
160
55584
5fbac09c0e91 Merged revisions 74264 via svnmerge from
Georg Brandl <georg@python.org>
parents: 55580
diff changeset
161 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
162 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
163 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
164
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
165 >>> import math
47283
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
166 >>> 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
167 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
168
47283
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
169 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
170 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
171
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
172 >>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 7678}
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
173 >>> for name, phone in table.items():
47283
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
174 ... 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
175 ...
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
176 Jack ==> 4098
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
177 Dcab ==> 7678
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
178 Sjoerd ==> 4127
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
179
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
180 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
181 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
182 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
183 square brackets ``'[]'`` to access the keys ::
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
184
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
185 >>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 8637678}
48578
b8d4dbb2938a Merged revisions 65253 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 48577
diff changeset
186 >>> print('Jack: {0[Jack]:d}; Sjoerd: {0[Sjoerd]:d}; '
79788
a0fba0382ae0 Issue #16265: Fix collapsing of code sample in tutorial.
Andrew Svetlov <andrew.svetlov@gmail.com>
parents: 78578
diff changeset
187 ... 'Dcab: {0[Dcab]:d}'.format(table))
47283
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
188 Jack: 4098; Sjoerd: 4127; Dcab: 8637678
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
189
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
190 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
191 notation. ::
47283
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 >>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 8637678}
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
194 >>> 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
195 Jack: 4098; Sjoerd: 4127; Dcab: 8637678
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
196
68411
87167b08312f Fix markup in inputoutput.rst.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 68285
diff changeset
197 This is particularly useful in combination with the built-in function
87167b08312f Fix markup in inputoutput.rst.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 68285
diff changeset
198 :func:`vars`, which returns a dictionary containing all local variables.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
199
51776
d06a3ebf306f Merged revisions 69846 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 50569
diff changeset
200 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
201 :ref:`formatstrings`.
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
202
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 Old string formatting
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 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
208 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
209 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
210 operation. For example::
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
211
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
212 >>> import math
48655
1635891b18e8 #3503: fix print statements in 3k doc.
Georg Brandl <georg@python.org>
parents: 48578
diff changeset
213 >>> 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
214 The value of PI is approximately 3.142.
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
215
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 44999
diff changeset
216 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
217
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
218
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
219 .. _tut-files:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
220
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
221 Reading and Writing Files
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
222 =========================
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 .. index::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
225 builtin: open
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
226 object: file
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
227
64763
bed950cbd0c0 Add cross-references to the glossary entry for file objects.
Antoine Pitrou <solipsis@pitrou.net>
parents: 55797
diff changeset
228 :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
229 two arguments: ``open(filename, mode)``.
42604
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 ::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
232
82353
7556601180c8 Issue #8890: Stop advertising an insecure use of /tmp in docs
Petri Lehtinen <petri@digip.org>
parents: 79809
diff changeset
233 >>> f = open('workfile', 'w')
48668
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
234
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
235 .. 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
236
43115
95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois.
Guido van Rossum <guido@python.org>
parents: 42604
diff changeset
237 >>> print(f)
82353
7556601180c8 Issue #8890: Stop advertising an insecure use of /tmp in docs
Petri Lehtinen <petri@digip.org>
parents: 79809
diff changeset
238 <open file 'workfile', mode 'w' at 80a0960>
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
239
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
240 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
241 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
242 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
243 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
244 ``'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
245 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
246 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
247 omitted.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
248
48668
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
249 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
250 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
251 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
252 :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
253 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
254
79809
7b2a13b20b33 Clarify universal-newline wording in tutorial (issue #16266).
Chris Jerdonek <chris.jerdonek@gmail.com>
parents: 79788
diff changeset
255 In text mode, the default when reading is to convert platform-specific line
7b2a13b20b33 Clarify universal-newline wording in tutorial (issue #16266).
Chris Jerdonek <chris.jerdonek@gmail.com>
parents: 79788
diff changeset
256 endings (``\n`` on Unix, ``\r\n`` on Windows) to just ``\n``. When writing in
7b2a13b20b33 Clarify universal-newline wording in tutorial (issue #16266).
Chris Jerdonek <chris.jerdonek@gmail.com>
parents: 79788
diff changeset
257 text mode, the default is to convert occurrences of ``\n`` back to
7b2a13b20b33 Clarify universal-newline wording in tutorial (issue #16266).
Chris Jerdonek <chris.jerdonek@gmail.com>
parents: 79788
diff changeset
258 platform-specific line endings. This behind-the-scenes modification
48668
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
259 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
260 :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
261 reading and writing such files.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
262
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
263
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
264 .. _tut-filemethods:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
265
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
266 Methods of File Objects
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
267 -----------------------
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
268
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
269 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
270 ``f`` has already been created.
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 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
273 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
274 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
275 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
276 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
277 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
278 string (``''``). ::
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
279
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
280 >>> f.read()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
281 'This is the entire file.\n'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
282 >>> f.read()
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
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
285 ``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
286 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
287 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
288 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
289 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
290 containing only a single newline. ::
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
291
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
292 >>> f.readline()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
293 '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
294 >>> f.readline()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
295 'Second line of the file\n'
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 ''
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
298
83395
1e8be05a4039 #13510: clarify that f.readlines() is note necessary to iterate over a file. Patch by Dan Riti.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 82353
diff changeset
299 For reading lines from a file, you can loop over the file object. This is memory
1e8be05a4039 #13510: clarify that f.readlines() is note necessary to iterate over a file. Patch by Dan Riti.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 82353
diff changeset
300 efficient, fast, and leads to simple code::
42604
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 >>> for line in f:
48668
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
303 ... print(line, end='')
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
304 ...
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
305 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
306 Second line of the file
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
307
83395
1e8be05a4039 #13510: clarify that f.readlines() is note necessary to iterate over a file. Patch by Dan Riti.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 82353
diff changeset
308 If you want to read all the lines of a file in a list you can also use
1e8be05a4039 #13510: clarify that f.readlines() is note necessary to iterate over a file. Patch by Dan Riti.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 82353
diff changeset
309 ``list(f)`` or ``f.readlines()``.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
310
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
311 ``f.write(string)`` writes the contents of *string* to the file, returning
48668
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
312 the number of characters written. ::
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
313
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
314 >>> f.write('This is a test\n')
48668
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
315 15
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
316
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
317 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
318 first::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
319
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
320 >>> value = ('the answer', 42)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
321 >>> s = str(value)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
322 >>> f.write(s)
48668
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
323 18
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
324
84919
81bc2d64c006 #16273: Fix tutorial discussion of seek/tell (opaque text-mode values).
R David Murray <rdmurray@bitdance.com>
parents: 83900
diff changeset
325 ``f.tell()`` returns an integer giving the file object's current position in the file
81bc2d64c006 #16273: Fix tutorial discussion of seek/tell (opaque text-mode values).
R David Murray <rdmurray@bitdance.com>
parents: 83900
diff changeset
326 represented as number of bytes from the beginning of the file when in `binary mode` and
81bc2d64c006 #16273: Fix tutorial discussion of seek/tell (opaque text-mode values).
R David Murray <rdmurray@bitdance.com>
parents: 83900
diff changeset
327 an opaque number when in `text mode`.
81bc2d64c006 #16273: Fix tutorial discussion of seek/tell (opaque text-mode values).
R David Murray <rdmurray@bitdance.com>
parents: 83900
diff changeset
328
81bc2d64c006 #16273: Fix tutorial discussion of seek/tell (opaque text-mode values).
R David Murray <rdmurray@bitdance.com>
parents: 83900
diff changeset
329 To change the file object's position, use ``f.seek(offset, from_what)``. The position is computed
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
330 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
331 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
332 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
333 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
334 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
335
82353
7556601180c8 Issue #8890: Stop advertising an insecure use of /tmp in docs
Petri Lehtinen <petri@digip.org>
parents: 79809
diff changeset
336 >>> f = open('workfile', 'rb+')
48668
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
337 >>> f.write(b'0123456789abcdef')
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
338 16
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
339 >>> 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
340 5
50563
93cf3a6ead63 Merged revisions 68226 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48668
diff changeset
341 >>> f.read(1)
48668
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
342 b'5'
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
343 >>> 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
344 13
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
345 >>> f.read(1)
48668
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
346 b'd'
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
347
48668
e2c706f9906c #3524: fix up some old-style IO descriptions.
Georg Brandl <georg@python.org>
parents: 48666
diff changeset
348 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
349 relative to the beginning of the file are allowed (the exception being seeking
84919
81bc2d64c006 #16273: Fix tutorial discussion of seek/tell (opaque text-mode values).
R David Murray <rdmurray@bitdance.com>
parents: 83900
diff changeset
350 to the very file end with ``seek(0, 2)``) and the only valid *offset* values are
81bc2d64c006 #16273: Fix tutorial discussion of seek/tell (opaque text-mode values).
R David Murray <rdmurray@bitdance.com>
parents: 83900
diff changeset
351 those returned from the ``f.tell()``, or zero. Any other *offset* value produces
81bc2d64c006 #16273: Fix tutorial discussion of seek/tell (opaque text-mode values).
R David Murray <rdmurray@bitdance.com>
parents: 83900
diff changeset
352 undefined behaviour.
81bc2d64c006 #16273: Fix tutorial discussion of seek/tell (opaque text-mode values).
R David Murray <rdmurray@bitdance.com>
parents: 83900
diff changeset
353
50563
93cf3a6ead63 Merged revisions 68226 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48668
diff changeset
354
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
355 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
356 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
357 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
358
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
359 >>> f.close()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
360 >>> f.read()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
361 Traceback (most recent call last):
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
362 File "<stdin>", line 1, in ?
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
363 ValueError: I/O operation on closed file
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
364
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
365 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
366 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
367 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
368 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
369
82353
7556601180c8 Issue #8890: Stop advertising an insecure use of /tmp in docs
Petri Lehtinen <petri@digip.org>
parents: 79809
diff changeset
370 >>> with open('workfile', 'r') as f:
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
371 ... 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
372 >>> 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
373 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
374
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
375 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
376 :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
377 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
378
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
379
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
380 .. _tut-pickle:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
381
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
382 The :mod:`pickle` Module
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
383 ------------------------
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
384
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
385 .. index:: module: pickle
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
386
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
387 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
388 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
389 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
390 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
391 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
392 complicated.
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 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
395 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
396 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
397 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
398 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
399 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
400 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
401 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
402
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
403 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
404 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
405
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
406 pickle.dump(x, f)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
407
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
408 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
409 for reading::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
410
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
411 x = pickle.load(f)
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 (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
414 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
415 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
416
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
417 :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
418 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
419 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
420 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
421 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
422
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
423