Mercurial > cpython-lru_cache-weakref

annotate Doc/tutorial/inputoutput.rst @ 80661:94de77bd0b4b 2.7

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Issue #16194: document imp.load_dynamic problems when read several extension modules from the same binary object file.
author Andrew Svetlov <andrew.svetlov@gmail.com>
date Thu, 29 Nov 2012 19:51:28 +0200
parents 0dbdaa0ff648
children 488957f9b664
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1 .. _tut-io:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3 ****************
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
4 Input and Output
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
5 ****************
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
6
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
7 There are several ways to present the output of a program; data can be printed
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
8 in a human-readable form, or written to a file for future use. This chapter will
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
9 discuss some of the possibilities.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
10
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
11
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
12 .. _tut-formatting:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
13
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
14 Fancier Output Formatting
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
15 =========================
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
16
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
17 So far we've encountered two ways of writing values: *expression statements* and
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
18 the :keyword:`print` statement. (A third way is using the :meth:`write` method
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
19 of file objects; the standard output file can be referenced as ``sys.stdout``.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
20 See the Library Reference for more information on this.)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
21
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
22 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
68294
23839b3c621d #11405: do not reference the string module again for its deprecated functions, only for Template class.
Georg Brandl <georg@python.org>
parents: 68256
diff changeset
26 string types have 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
47282
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
28 way is to use the :meth:`str.format` method.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
29
68294
23839b3c621d #11405: do not reference the string module again for its deprecated functions, only for Template class.
Georg Brandl <georg@python.org>
parents: 68256
diff changeset
30 The :mod:`string` module contains a :class:`~string.Template` class which offers
23839b3c621d #11405: do not reference the string module again for its deprecated functions, only for Template class.
Georg Brandl <georg@python.org>
parents: 68256
diff changeset
31 yet another way to substitute values into strings.
23839b3c621d #11405: do not reference the string module again for its deprecated functions, only for Template class.
Georg Brandl <georg@python.org>
parents: 68256
diff changeset
32
42604
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`
48197
7224fff98823 Remove mention of backquotes in the tutorial.
Georg Brandl <georg@python.org>
parents: 48084
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
78577
0dbdaa0ff648 fix typo
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74395
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
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
43 dictionaries, have the same representation using either function. Strings and
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
44 floating point numbers, in particular, have two distinct representations.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
45
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
46 Some examples::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
47
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
48 >>> s = 'Hello, world.'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
49 >>> str(s)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
50 'Hello, world.'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
51 >>> repr(s)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
52 "'Hello, world.'"
57428
337ebb829b8c Fix some documentation examples involving the repr of a float.
Mark Dickinson <dickinsm@gmail.com>
parents: 55945
diff changeset
53 >>> str(1.0/7.0)
337ebb829b8c Fix some documentation examples involving the repr of a float.
Mark Dickinson <dickinsm@gmail.com>
parents: 55945
diff changeset
54 '0.142857142857'
337ebb829b8c Fix some documentation examples involving the repr of a float.
Mark Dickinson <dickinsm@gmail.com>
parents: 55945
diff changeset
55 >>> repr(1.0/7.0)
337ebb829b8c Fix some documentation examples involving the repr of a float.
Mark Dickinson <dickinsm@gmail.com>
parents: 55945
diff changeset
56 '0.14285714285714285'
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
57 >>> x = 10 * 3.25
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
58 >>> y = 200 * 200
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
59 >>> s = 'The value of x is ' + repr(x) + ', and y is ' + repr(y) + '...'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
60 >>> print s
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
61 The value of x is 32.5, and y is 40000...
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
62 >>> # The repr() of a string adds string quotes and backslashes:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
63 ... hello = 'hello, world\n'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
64 >>> hellos = repr(hello)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
65 >>> print hellos
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
66 'hello, world\n'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
67 >>> # The argument to repr() may be any Python object:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
68 ... repr((x, y, ('spam', 'eggs')))
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
69 "(32.5, 40000, ('spam', 'eggs'))"
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
70
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
71 Here are two ways to write a table of squares and cubes::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
72
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
73 >>> for x in range(1, 11):
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
74 ... print repr(x).rjust(2), repr(x*x).rjust(3),
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
75 ... # Note trailing comma on previous line
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
76 ... print repr(x*x*x).rjust(4)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
77 ...
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
78 1 1 1
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
79 2 4 8
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
80 3 9 27
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
81 4 16 64
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
82 5 25 125
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
83 6 36 216
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
84 7 49 343
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
85 8 64 512
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
86 9 81 729
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
87 10 100 1000
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
88
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
89 >>> for x in range(1,11):
47282
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
90 ... print '{0:2d} {1:3d} {2:4d}'.format(x, x*x, x*x*x)
50522
ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from
Georg Brandl <georg@python.org>
parents: 49184
diff changeset
91 ...
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
92 1 1 1
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
93 2 4 8
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
94 3 9 27
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
95 4 16 64
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
96 5 25 125
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
97 6 36 216
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
98 7 49 343
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
99 8 64 512
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
100 9 81 729
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
101 10 100 1000
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
102
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
103 (Note that in the first example, one space between each column was added by the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
104 way :keyword:`print` works: it always adds spaces between its arguments.)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
105
68410
f757b3b79c2a Fix markup in inputoutput.rst.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 68294
diff changeset
106 This example demonstrates the :meth:`str.rjust` method of string
f757b3b79c2a Fix markup in inputoutput.rst.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 68294
diff changeset
107 objects, which right-justifies a string in a field of a given width by padding
f757b3b79c2a Fix markup in inputoutput.rst.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 68294
diff changeset
108 it with spaces on the left. There are similar methods :meth:`str.ljust` and
f757b3b79c2a Fix markup in inputoutput.rst.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 68294
diff changeset
109 :meth:`str.center`. These methods do not write anything, they just return a
f757b3b79c2a Fix markup in inputoutput.rst.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 68294
diff changeset
110 new string. If the input string is too long, they don't truncate it, but
f757b3b79c2a Fix markup in inputoutput.rst.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 68294
diff changeset
111 return it unchanged; this will mess up your column lay-out but that's usually
f757b3b79c2a Fix markup in inputoutput.rst.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 68294
diff changeset
112 better than the alternative, which would be lying about a value. (If you
f757b3b79c2a Fix markup in inputoutput.rst.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 68294
diff changeset
113 really want truncation you can always add a slice operation, as in
f757b3b79c2a Fix markup in inputoutput.rst.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 68294
diff changeset
114 ``x.ljust(n)[:n]``.)
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
115
68410
f757b3b79c2a Fix markup in inputoutput.rst.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 68294
diff changeset
116 There is another method, :meth:`str.zfill`, which pads a numeric string on the
f757b3b79c2a Fix markup in inputoutput.rst.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 68294
diff changeset
117 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
118
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
119 >>> '12'.zfill(5)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
120 '00012'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
121 >>> '-3.14'.zfill(7)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
122 '-003.14'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
123 >>> '3.14159265359'.zfill(5)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
124 '3.14159265359'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
125
47282
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
126 Basic usage of the :meth:`str.format` method looks like this::
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
127
55787
ba5b2683c064 #6813: better documentation for numberless string formats.
Georg Brandl <georg@python.org>
parents: 55500
diff changeset
128 >>> print 'We are the {} who say "{}!"'.format('knights', 'Ni')
47282
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
129 We are the knights who say "Ni!"
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
130
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
131 The brackets and characters within them (called format fields) are replaced with
68410
f757b3b79c2a Fix markup in inputoutput.rst.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 68294
diff changeset
132 the objects passed into the :meth:`str.format` method. A number in the
56819
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56816
diff changeset
133 brackets refers to the position of the object passed into the
68410
f757b3b79c2a Fix markup in inputoutput.rst.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 68294
diff changeset
134 :meth:`str.format` method. ::
47282
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
135
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
136 >>> print '{0} and {1}'.format('spam', 'eggs')
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
137 spam and eggs
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
138 >>> print '{1} and {0}'.format('spam', 'eggs')
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
139 eggs and spam
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
140
68410
f757b3b79c2a Fix markup in inputoutput.rst.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 68294
diff changeset
141 If keyword arguments are used in the :meth:`str.format` method, their values
56819
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56816
diff changeset
142 are referred to by using the name of the argument. ::
47282
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
143
48084
0c12a37d5e5d Shorten some overlong lines.
Georg Brandl <georg@python.org>
parents: 47996
diff changeset
144 >>> print 'This {food} is {adjective}.'.format(
0c12a37d5e5d Shorten some overlong lines.
Georg Brandl <georg@python.org>
parents: 47996
diff changeset
145 ... food='spam', adjective='absolutely horrible')
47282
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
146 This spam is absolutely horrible.
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
147
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
148 Positional and keyword arguments can be arbitrarily combined::
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
149
48084
0c12a37d5e5d Shorten some overlong lines.
Georg Brandl <georg@python.org>
parents: 47996
diff changeset
150 >>> print 'The story of {0}, {1}, and {other}.'.format('Bill', 'Manfred',
0c12a37d5e5d Shorten some overlong lines.
Georg Brandl <georg@python.org>
parents: 47996
diff changeset
151 ... other='Georg')
47282
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
152 The story of Bill, Manfred, and Georg.
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
153
56820
85aa706f7126 Merged revisions 74492,74531,74545-74550,74553-74555,74588,74603,74608,74614,74616-74618,74631-74633,74652-74653,74666,74671,74737,74739,74779,74781-74782,74784,74791,74793,74818-74820,74822,74832 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56819
diff changeset
154 ``'!s'`` (apply :func:`str`) and ``'!r'`` (apply :func:`repr`) can be used to
85aa706f7126 Merged revisions 74492,74531,74545-74550,74553-74555,74588,74603,74608,74614,74616-74618,74631-74633,74652-74653,74666,74671,74737,74739,74779,74781-74782,74784,74791,74793,74818-74820,74822,74832 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56819
diff changeset
155 convert the value before it is formatted. ::
85aa706f7126 Merged revisions 74492,74531,74545-74550,74553-74555,74588,74603,74608,74614,74616-74618,74631-74633,74652-74653,74666,74671,74737,74739,74779,74781-74782,74784,74791,74793,74818-74820,74822,74832 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56819
diff changeset
156
85aa706f7126 Merged revisions 74492,74531,74545-74550,74553-74555,74588,74603,74608,74614,74616-74618,74631-74633,74652-74653,74666,74671,74737,74739,74779,74781-74782,74784,74791,74793,74818-74820,74822,74832 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56819
diff changeset
157 >>> import math
55787
ba5b2683c064 #6813: better documentation for numberless string formats.
Georg Brandl <georg@python.org>
parents: 55500
diff changeset
158 >>> print 'The value of PI is approximately {}.'.format(math.pi)
56820
85aa706f7126 Merged revisions 74492,74531,74545-74550,74553-74555,74588,74603,74608,74614,74616-74618,74631-74633,74652-74653,74666,74671,74737,74739,74779,74781-74782,74784,74791,74793,74818-74820,74822,74832 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56819
diff changeset
159 The value of PI is approximately 3.14159265359.
55787
ba5b2683c064 #6813: better documentation for numberless string formats.
Georg Brandl <georg@python.org>
parents: 55500
diff changeset
160 >>> print 'The value of PI is approximately {!r}.'.format(math.pi)
56820
85aa706f7126 Merged revisions 74492,74531,74545-74550,74553-74555,74588,74603,74608,74614,74616-74618,74631-74633,74652-74653,74666,74671,74737,74739,74779,74781-74782,74784,74791,74793,74818-74820,74822,74832 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56819
diff changeset
161 The value of PI is approximately 3.141592653589793.
85aa706f7126 Merged revisions 74492,74531,74545-74550,74553-74555,74588,74603,74608,74614,74616-74618,74631-74633,74652-74653,74666,74671,74737,74739,74779,74781-74782,74784,74791,74793,74818-74820,74822,74832 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56819
diff changeset
162
56816
66de7111230a Merged revisions 74008,74021-74022,74074-74075,74077,74148,74179,74188,74192-74194,74200,74205 via svnmerge from
Georg Brandl <georg@python.org>
parents: 55049
diff changeset
163 An optional ``':'`` and format specifier can follow the field name. This allows
47282
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
164 greater control over how the value is formatted. The following example
67998
de5c3a39ade7 Issue #11304: Input/output tutorial - PI is rounded not truncated.
Raymond Hettinger <python@rcn.com>
parents: 57428
diff changeset
165 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
166
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
167 >>> import math
47282
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
168 >>> 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
169 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
170
47282
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
171 Passing an integer after the ``':'`` will cause that field to be a minimum
56819
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56816
diff changeset
172 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
173
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
174 >>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 7678}
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
175 >>> for name, phone in table.items():
47282
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
176 ... print '{0:10} ==> {1:10d}'.format(name, phone)
50522
ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from
Georg Brandl <georg@python.org>
parents: 49184
diff changeset
177 ...
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
178 Jack ==> 4098
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
179 Dcab ==> 7678
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
180 Sjoerd ==> 4127
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
181
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
182 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
183 would be nice if you could reference the variables to be formatted by name
47282
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
184 instead of by position. This can be done by simply passing the dict and using
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
185 square brackets ``'[]'`` to access the keys ::
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
186
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
187 >>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 8637678}
48084
0c12a37d5e5d Shorten some overlong lines.
Georg Brandl <georg@python.org>
parents: 47996
diff changeset
188 >>> print ('Jack: {0[Jack]:d}; Sjoerd: {0[Sjoerd]:d}; '
0c12a37d5e5d Shorten some overlong lines.
Georg Brandl <georg@python.org>
parents: 47996
diff changeset
189 ... 'Dcab: {0[Dcab]:d}'.format(table))
47282
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
190 Jack: 4098; Sjoerd: 4127; Dcab: 8637678
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
191
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
192 This could also be done by passing the table as keyword arguments with the '**'
56819
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56816
diff changeset
193 notation. ::
47282
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
194
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
195 >>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 8637678}
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
196 >>> 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
197 Jack: 4098; Sjoerd: 4127; Dcab: 8637678
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
198
68410
f757b3b79c2a Fix markup in inputoutput.rst.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 68294
diff changeset
199 This is particularly useful in combination with the built-in function
f757b3b79c2a Fix markup in inputoutput.rst.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 68294
diff changeset
200 :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
201
55049
74c0a78114ae Merged revisions 69846 via svnmerge from
Jesus Cea <jcea@jcea.es>
parents: 50522
diff changeset
202 For a complete overview of string formatting with :meth:`str.format`, see
47282
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
203 :ref:`formatstrings`.
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
204
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
205
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
206 Old string formatting
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
207 ---------------------
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
208
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
209 The ``%`` operator can also be used for string formatting. It interprets the
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68410
diff changeset
210 left argument much like a :c:func:`sprintf`\ -style format string to be applied
47282
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
211 to the right argument, and returns the string resulting from this formatting
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
212 operation. For example::
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
213
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
214 >>> import math
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
215 >>> print 'The value of PI is approximately %5.3f.' % math.pi
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
216 The value of PI is approximately 3.142.
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
217
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
218 Since :meth:`str.format` is quite new, a lot of Python code still uses the ``%``
56816
66de7111230a Merged revisions 74008,74021-74022,74074-74075,74077,74148,74179,74188,74192-74194,74200,74205 via svnmerge from
Georg Brandl <georg@python.org>
parents: 55049
diff changeset
219 operator. However, because this old style of formatting will eventually be
66de7111230a Merged revisions 74008,74021-74022,74074-74075,74077,74148,74179,74188,74192-74194,74200,74205 via svnmerge from
Georg Brandl <georg@python.org>
parents: 55049
diff changeset
220 removed from the language, :meth:`str.format` should generally be used.
47282
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
221
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
222 More information can be found in the :ref:`string-formatting` section.
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 44973
diff changeset
223
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
224
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
225 .. _tut-files:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
226
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
227 Reading and Writing Files
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
228 =========================
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
229
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
230 .. index::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
231 builtin: open
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
232 object: file
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
233
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
234 :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
235 arguments: ``open(filename, mode)``.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
236
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
237 ::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
238
44383
3625234bf3d2 Some cleanup in the docs.
Georg Brandl <georg@python.org>
parents: 43413
diff changeset
239 >>> f = open('/tmp/workfile', 'w')
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
240 >>> print f
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
241 <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
242
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
243 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
244 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
245 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
246 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
247 ``'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
248 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
249 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
250 omitted.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
251
49184
59db4b3a06b0 Remove things specific to the old Macintosh, and spell "Mac OS X" consistently.
Georg Brandl <georg@python.org>
parents: 48197
diff changeset
252 On Windows, ``'b'`` appended to the mode opens the file in binary mode, so there
56820
85aa706f7126 Merged revisions 74492,74531,74545-74550,74553-74555,74588,74603,74608,74614,74616-74618,74631-74633,74652-74653,74666,74671,74737,74739,74779,74781-74782,74784,74791,74793,74818-74820,74822,74832 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56819
diff changeset
253 are also modes like ``'rb'``, ``'wb'``, and ``'r+b'``. Python on Windows makes
85aa706f7126 Merged revisions 74492,74531,74545-74550,74553-74555,74588,74603,74608,74614,74616-74618,74631-74633,74652-74653,74666,74671,74737,74739,74779,74781-74782,74784,74791,74793,74818-74820,74822,74832 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56819
diff changeset
254 a distinction between text and binary files; the end-of-line characters in text
49184
59db4b3a06b0 Remove things specific to the old Macintosh, and spell "Mac OS X" consistently.
Georg Brandl <georg@python.org>
parents: 48197
diff changeset
255 files are automatically altered slightly when data is read or written. This
59db4b3a06b0 Remove things specific to the old Macintosh, and spell "Mac OS X" consistently.
Georg Brandl <georg@python.org>
parents: 48197
diff changeset
256 behind-the-scenes modification to file data is fine for ASCII text files, but
59db4b3a06b0 Remove things specific to the old Macintosh, and spell "Mac OS X" consistently.
Georg Brandl <georg@python.org>
parents: 48197
diff changeset
257 it'll corrupt binary data like that in :file:`JPEG` or :file:`EXE` files. Be
59db4b3a06b0 Remove things specific to the old Macintosh, and spell "Mac OS X" consistently.
Georg Brandl <georg@python.org>
parents: 48197
diff changeset
258 very careful to use binary mode when reading and writing such files. On Unix,
59db4b3a06b0 Remove things specific to the old Macintosh, and spell "Mac OS X" consistently.
Georg Brandl <georg@python.org>
parents: 48197
diff changeset
259 it doesn't hurt to append a ``'b'`` to the mode, so you can use it
59db4b3a06b0 Remove things specific to the old Macintosh, and spell "Mac OS X" consistently.
Georg Brandl <georg@python.org>
parents: 48197
diff changeset
260 platform-independently for all binary files.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
261
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
262
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
263 .. _tut-filemethods:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
264
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
265 Methods of File Objects
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
266 -----------------------
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
267
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
268 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
269 ``f`` has already been created.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
270
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
271 To read a file's contents, call ``f.read(size)``, which reads some quantity of
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
272 data and returns it as a string. *size* is an optional numeric argument. When
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
273 *size* is omitted or negative, the entire contents of the file will be read and
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
274 returned; it's your problem if the file is twice as large as your machine's
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
275 memory. Otherwise, at most *size* bytes are read and returned. If the end of
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
276 the file has been reached, ``f.read()`` will return an empty string (``""``).
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
277 ::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
278
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
279 >>> f.read()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
280 'This is the entire file.\n'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
281 >>> f.read()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
282 ''
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
283
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
284 ``f.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
285 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
286 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
287 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
288 has been reached, while a blank line is represented by ``'\n'``, a string
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
289 containing only a single newline. ::
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()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
292 '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
293 >>> f.readline()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
294 'Second line of the file\n'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
295 >>> f.readline()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
296 ''
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.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
299 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
300 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
301 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
302 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
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()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
306 ['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
307
43413
409091b28c7e alternate -> alternative.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
308 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
309 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
310
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
311 >>> for line in f:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
312 print line,
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 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
315 Second line of the file
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 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
318 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
319 should not be mixed.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
320
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
321 ``f.write(string)`` writes the contents of *string* to the file, returning
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
322 ``None``. ::
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 >>> f.write('This is a test\n')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
325
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
326 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
327 first::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
328
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
329 >>> value = ('the answer', 42)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
330 >>> s = str(value)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
331 >>> f.write(s)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
332
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
333 ``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
334 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
335 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
336 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
337 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
338 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
339 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
340 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
341
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
342 >>> f = open('/tmp/workfile', 'r+')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
343 >>> f.write('0123456789abcdef')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
344 >>> f.seek(5) # Go to the 6th byte in the file
50522
ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from
Georg Brandl <georg@python.org>
parents: 49184
diff changeset
345 >>> f.read(1)
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
346 '5'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
347 >>> f.seek(-3, 2) # Go to the 3rd byte before the end
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
348 >>> f.read(1)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
349 'd'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
350
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
351 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
352 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
353 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
354
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
355 >>> f.close()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
356 >>> f.read()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
357 Traceback (most recent call last):
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
358 File "<stdin>", line 1, in ?
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
359 ValueError: I/O operation on closed file
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
360
47996
d31d61f46498 #3388: add a paragraph about using "with" for file objects.
Georg Brandl <georg@python.org>
parents: 47282
diff changeset
361 It is good practice to use the :keyword:`with` keyword when dealing with file
d31d61f46498 #3388: add a paragraph about using "with" for file objects.
Georg Brandl <georg@python.org>
parents: 47282
diff changeset
362 objects. This has the advantage that the file is properly closed after its
d31d61f46498 #3388: add a paragraph about using "with" for file objects.
Georg Brandl <georg@python.org>
parents: 47282
diff changeset
363 suite finishes, even if an exception is raised on the way. It is also much
d31d61f46498 #3388: add a paragraph about using "with" for file objects.
Georg Brandl <georg@python.org>
parents: 47282
diff changeset
364 shorter than writing equivalent :keyword:`try`\ -\ :keyword:`finally` blocks::
d31d61f46498 #3388: add a paragraph about using "with" for file objects.
Georg Brandl <georg@python.org>
parents: 47282
diff changeset
365
d31d61f46498 #3388: add a paragraph about using "with" for file objects.
Georg Brandl <georg@python.org>
parents: 47282
diff changeset
366 >>> with open('/tmp/workfile', 'r') as f:
d31d61f46498 #3388: add a paragraph about using "with" for file objects.
Georg Brandl <georg@python.org>
parents: 47282
diff changeset
367 ... read_data = f.read()
d31d61f46498 #3388: add a paragraph about using "with" for file objects.
Georg Brandl <georg@python.org>
parents: 47282
diff changeset
368 >>> f.closed
d31d61f46498 #3388: add a paragraph about using "with" for file objects.
Georg Brandl <georg@python.org>
parents: 47282
diff changeset
369 True
d31d61f46498 #3388: add a paragraph about using "with" for file objects.
Georg Brandl <georg@python.org>
parents: 47282
diff changeset
370
56819
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56816
diff changeset
371 File objects have some additional methods, such as :meth:`~file.isatty` and
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56816
diff changeset
372 :meth:`~file.truncate` which are less frequently used; consult the Library
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56816
diff changeset
373 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
374
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
375
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
376 .. _tut-pickle:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
377
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
378 The :mod:`pickle` Module
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
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
381 .. index:: module: pickle
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
382
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
383 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
384 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
385 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
386 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
387 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
388 complicated.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
389
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
390 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
391 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
392 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
393 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
394 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
395 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
396 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
397 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
398
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
399 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
400 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
401
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
402 pickle.dump(x, f)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
403
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
404 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
405 for reading::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
406
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
407 x = pickle.load(f)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
408
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
409 (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
410 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
411 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
412
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
413 :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
414 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
415 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
416 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
417 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
418
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
419