cpython-lru_cache-weakref: Doc/tutorial/inputoutput.rst annotate

annotate Doc/tutorial/inputoutput.rst @ 58765:2ba7677bfa95 legacy-trunk

testCopysign was defined twice in test_math; combine the definitions

author	Mark Dickinson <dickinsm@gmail.com>
date	Sat, 06 Feb 2010 23:11:25 +0000
parents	337ebb829b8c
children	de5c3a39ade7

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 .. index:: module: string
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	23
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	24 Often you'll want more control over the formatting of your output than simply
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	25 printing space-separated values. There are two ways to format your output; the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	26 first way is to do all the string handling yourself; using string slicing and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	27 concatenation operations you can create any layout you can imagine. The
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	28 standard module :mod:`string` contains some useful operations for padding
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	29 strings to a given column width; these will be discussed shortly. The second
47282 70f9a5db279c update the tutorial to use str.format Benjamin Peterson <benjamin@python.org> parents: 44973 diff changeset	30 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	31
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	32 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	33 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	34 or :func:`str` functions.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	35
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	36 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	37 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	38 which can be read by the interpreter (or will force a :exc:`SyntaxError` if
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	39 there is not equivalent syntax). For objects which don't have a particular
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	40 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	41 :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	42 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	43 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	44
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	45 Some examples::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	46
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	47 >>> s = 'Hello, world.'
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	48 >>> str(s)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	49 'Hello, world.'
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	50 >>> repr(s)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	51 "'Hello, world.'"
57428 337ebb829b8c Fix some documentation examples involving the repr of a float. Mark Dickinson <dickinsm@gmail.com> parents: 55945 diff changeset	52 >>> 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	53 '0.142857142857'
337ebb829b8c Fix some documentation examples involving the repr of a float. Mark Dickinson <dickinsm@gmail.com> parents: 55945 diff changeset	54 >>> 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	55 '0.14285714285714285'
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	56 >>> x = 10 * 3.25
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	57 >>> y = 200 * 200
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	58 >>> 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	59 >>> print s
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	60 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	61 >>> # 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	62 ... hello = 'hello, world\n'
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	63 >>> hellos = repr(hello)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	64 >>> print hellos
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	65 'hello, world\n'
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	66 >>> # 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	67 ... repr((x, y, ('spam', 'eggs')))
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	68 "(32.5, 40000, ('spam', 'eggs'))"
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	69
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	70 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	71
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	72 >>> for x in range(1, 11):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	73 ... 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	74 ... # Note trailing comma on previous line
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	75 ... print repr(xxx).rjust(4)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	76 ...
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	77 1 1 1
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	78 2 4 8
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	79 3 9 27
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	80 4 16 64
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	81 5 25 125
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	82 6 36 216
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	83 7 49 343
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	84 8 64 512
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	85 9 81 729
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	86 10 100 1000
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	87
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	88 >>> for x in range(1,11):
47282 70f9a5db279c update the tutorial to use str.format Benjamin Peterson <benjamin@python.org> parents: 44973 diff changeset	89 ... print '{0:2d} {1:3d} {2:4d}'.format(x, xx, xx*x)
50508 c52177f36852 Remove trailing whitespace. Georg Brandl <georg@python.org> parents: 50459 diff changeset	90 ...
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	91 1 1 1
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	92 2 4 8
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	93 3 9 27
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	94 4 16 64
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	95 5 25 125
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	96 6 36 216
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	97 7 49 343
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	98 8 64 512
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	99 9 81 729
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	100 10 100 1000
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	101
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	102 (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	103 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	104
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	105 This example demonstrates the :meth:`rjust` method of string objects, which
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	106 right-justifies a string in a field of a given width by padding it with spaces
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	107 on the left. There are similar methods :meth:`ljust` and :meth:`center`. These
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	108 methods do not write anything, they just return a new string. If the input
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	109 string is too long, they don't truncate it, but return it unchanged; this will
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	110 mess up your column lay-out but that's usually better than the alternative,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	111 which would be lying about a value. (If you really want truncation you can
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	112 always add a slice operation, as in ``x.ljust(n)[:n]``.)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	113
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	114 There is another method, :meth:`zfill`, which pads a numeric string on the left
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	115 with zeros. It understands about plus and minus signs::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	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
47282 70f9a5db279c update the tutorial to use str.format Benjamin Peterson <benjamin@python.org> parents: 44973 diff changeset	124 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	125
55787 ba5b2683c064 #6813: better documentation for numberless string formats. Georg Brandl <georg@python.org> parents: 55500 diff changeset	126 >>> 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	127 We are the knights who say "Ni!"
70f9a5db279c update the tutorial to use str.format Benjamin Peterson <benjamin@python.org> parents: 44973 diff changeset	128
70f9a5db279c update the tutorial to use str.format Benjamin Peterson <benjamin@python.org> parents: 44973 diff changeset	129 The brackets and characters within them (called format fields) are replaced with
55787 ba5b2683c064 #6813: better documentation for numberless string formats. Georg Brandl <georg@python.org> parents: 55500 diff changeset	130 the objects passed into the :meth:`~str.format` method. A number in the
55500 4fe5801bf712 Fix a few markup glitches. Georg Brandl <georg@python.org> parents: 55320 diff changeset	131 brackets refers to the position of the object passed into the
4fe5801bf712 Fix a few markup glitches. Georg Brandl <georg@python.org> parents: 55320 diff changeset	132 :meth:`~str.format` method. ::
47282 70f9a5db279c update the tutorial to use str.format Benjamin Peterson <benjamin@python.org> parents: 44973 diff changeset	133
70f9a5db279c update the tutorial to use str.format Benjamin Peterson <benjamin@python.org> parents: 44973 diff changeset	134 >>> print '{0} and {1}'.format('spam', 'eggs')
70f9a5db279c update the tutorial to use str.format Benjamin Peterson <benjamin@python.org> parents: 44973 diff changeset	135 spam and eggs
70f9a5db279c update the tutorial to use str.format Benjamin Peterson <benjamin@python.org> parents: 44973 diff changeset	136 >>> print '{1} and {0}'.format('spam', 'eggs')
70f9a5db279c update the tutorial to use str.format Benjamin Peterson <benjamin@python.org> parents: 44973 diff changeset	137 eggs and spam
70f9a5db279c update the tutorial to use str.format Benjamin Peterson <benjamin@python.org> parents: 44973 diff changeset	138
55500 4fe5801bf712 Fix a few markup glitches. Georg Brandl <georg@python.org> parents: 55320 diff changeset	139 If keyword arguments are used in the :meth:`~str.format` method, their values
4fe5801bf712 Fix a few markup glitches. Georg Brandl <georg@python.org> parents: 55320 diff changeset	140 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	141
48084 0c12a37d5e5d Shorten some overlong lines. Georg Brandl <georg@python.org> parents: 47996 diff changeset	142 >>> print 'This {food} is {adjective}.'.format(
0c12a37d5e5d Shorten some overlong lines. Georg Brandl <georg@python.org> parents: 47996 diff changeset	143 ... food='spam', adjective='absolutely horrible')
47282 70f9a5db279c update the tutorial to use str.format Benjamin Peterson <benjamin@python.org> parents: 44973 diff changeset	144 This spam is absolutely horrible.
70f9a5db279c update the tutorial to use str.format Benjamin Peterson <benjamin@python.org> parents: 44973 diff changeset	145
70f9a5db279c update the tutorial to use str.format Benjamin Peterson <benjamin@python.org> parents: 44973 diff changeset	146 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	147
48084 0c12a37d5e5d Shorten some overlong lines. Georg Brandl <georg@python.org> parents: 47996 diff changeset	148 >>> 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	149 ... other='Georg')
47282 70f9a5db279c update the tutorial to use str.format Benjamin Peterson <benjamin@python.org> parents: 44973 diff changeset	150 The story of Bill, Manfred, and Georg.
70f9a5db279c update the tutorial to use str.format Benjamin Peterson <benjamin@python.org> parents: 44973 diff changeset	151
55787 ba5b2683c064 #6813: better documentation for numberless string formats. Georg Brandl <georg@python.org> parents: 55500 diff changeset	152 ``'!s'`` (apply :func:`str`) and ``'!r'`` (apply :func:`repr`) can be used to
ba5b2683c064 #6813: better documentation for numberless string formats. Georg Brandl <georg@python.org> parents: 55500 diff changeset	153 convert the value before it is formatted. ::
ba5b2683c064 #6813: better documentation for numberless string formats. Georg Brandl <georg@python.org> parents: 55500 diff changeset	154
ba5b2683c064 #6813: better documentation for numberless string formats. Georg Brandl <georg@python.org> parents: 55500 diff changeset	155 >>> import math
ba5b2683c064 #6813: better documentation for numberless string formats. Georg Brandl <georg@python.org> parents: 55500 diff changeset	156 >>> print 'The value of PI is approximately {}.'.format(math.pi)
ba5b2683c064 #6813: better documentation for numberless string formats. Georg Brandl <georg@python.org> parents: 55500 diff changeset	157 The value of PI is approximately 3.14159265359.
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 {!r}.'.format(math.pi)
ba5b2683c064 #6813: better documentation for numberless string formats. Georg Brandl <georg@python.org> parents: 55500 diff changeset	159 The value of PI is approximately 3.141592653589793.
ba5b2683c064 #6813: better documentation for numberless string formats. Georg Brandl <georg@python.org> parents: 55500 diff changeset	160
55320 259138a988a5 #6505: fix typos. Georg Brandl <georg@python.org> parents: 51775 diff changeset	161 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	162 greater control over how the value is formatted. The following example
55320 259138a988a5 #6505: fix typos. Georg Brandl <georg@python.org> parents: 51775 diff changeset	163 truncates Pi to three places after the decimal.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	164
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	165 >>> import math
47282 70f9a5db279c update the tutorial to use str.format Benjamin Peterson <benjamin@python.org> parents: 44973 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
47282 70f9a5db279c update the tutorial to use str.format Benjamin Peterson <benjamin@python.org> parents: 44973 diff changeset	169 Passing an integer after the ``':'`` will cause that field to be a minimum
55500 4fe5801bf712 Fix a few markup glitches. Georg Brandl <georg@python.org> parents: 55320 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():
47282 70f9a5db279c update the tutorial to use str.format Benjamin Peterson <benjamin@python.org> parents: 44973 diff changeset	174 ... print '{0:10} ==> {1:10d}'.format(name, phone)
50508 c52177f36852 Remove trailing whitespace. Georg Brandl <georg@python.org> parents: 50459 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
47282 70f9a5db279c update the tutorial to use str.format Benjamin Peterson <benjamin@python.org> parents: 44973 diff changeset	182 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	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}
48084 0c12a37d5e5d Shorten some overlong lines. Georg Brandl <georg@python.org> parents: 47996 diff changeset	186 >>> print ('Jack: {0[Jack]:d}; Sjoerd: {0[Sjoerd]:d}; '
0c12a37d5e5d Shorten some overlong lines. Georg Brandl <georg@python.org> parents: 47996 diff changeset	187 ... 'Dcab: {0[Dcab]:d}'.format(table))
47282 70f9a5db279c update the tutorial to use str.format Benjamin Peterson <benjamin@python.org> parents: 44973 diff changeset	188 Jack: 4098; Sjoerd: 4127; Dcab: 8637678
70f9a5db279c update the tutorial to use str.format Benjamin Peterson <benjamin@python.org> parents: 44973 diff changeset	189
70f9a5db279c update the tutorial to use str.format Benjamin Peterson <benjamin@python.org> parents: 44973 diff changeset	190 This could also be done by passing the table as keyword arguments with the '**'
55500 4fe5801bf712 Fix a few markup glitches. Georg Brandl <georg@python.org> parents: 55320 diff changeset	191 notation. ::
47282 70f9a5db279c update the tutorial to use str.format Benjamin Peterson <benjamin@python.org> parents: 44973 diff changeset	192
70f9a5db279c update the tutorial to use str.format Benjamin Peterson <benjamin@python.org> parents: 44973 diff changeset	193 >>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 8637678}
70f9a5db279c update the tutorial to use str.format Benjamin Peterson <benjamin@python.org> parents: 44973 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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	197 This is particularly useful in combination with the new built-in :func:`vars`
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	198 function, which returns a dictionary containing all local variables.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	199
51775 af9b6c43804e Issue #5341: Fix a variety of spelling errors. Mark Dickinson <dickinsm@gmail.com> parents: 50508 diff changeset	200 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	201 :ref:`formatstrings`.
70f9a5db279c update the tutorial to use str.format Benjamin Peterson <benjamin@python.org> parents: 44973 diff changeset	202
70f9a5db279c update the tutorial to use str.format Benjamin Peterson <benjamin@python.org> parents: 44973 diff changeset	203
70f9a5db279c update the tutorial to use str.format Benjamin Peterson <benjamin@python.org> parents: 44973 diff changeset	204 Old string formatting
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
70f9a5db279c update the tutorial to use str.format Benjamin Peterson <benjamin@python.org> parents: 44973 diff changeset	207 The ``%`` operator can also be used for string formatting. It interprets the
70f9a5db279c update the tutorial to use str.format Benjamin Peterson <benjamin@python.org> parents: 44973 diff changeset	208 left argument much like a :cfunc:`sprintf`\ -style format string to be applied
70f9a5db279c update the tutorial to use str.format Benjamin Peterson <benjamin@python.org> parents: 44973 diff changeset	209 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	210 operation. For example::
70f9a5db279c update the tutorial to use str.format Benjamin Peterson <benjamin@python.org> parents: 44973 diff changeset	211
70f9a5db279c update the tutorial to use str.format Benjamin Peterson <benjamin@python.org> parents: 44973 diff changeset	212 >>> import math
70f9a5db279c update the tutorial to use str.format Benjamin Peterson <benjamin@python.org> parents: 44973 diff changeset	213 >>> 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	214 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	215
70f9a5db279c update the tutorial to use str.format Benjamin Peterson <benjamin@python.org> parents: 44973 diff changeset	216 Since :meth:`str.format` is quite new, a lot of Python code still uses the ``%``
55320 259138a988a5 #6505: fix typos. Georg Brandl <georg@python.org> parents: 51775 diff changeset	217 operator. However, because this old style of formatting will eventually be
259138a988a5 #6505: fix typos. Georg Brandl <georg@python.org> parents: 51775 diff changeset	218 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	219
70f9a5db279c update the tutorial to use str.format Benjamin Peterson <benjamin@python.org> parents: 44973 diff changeset	220 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	221
42604 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 .. _tut-files:
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 Reading and Writing 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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	228 .. index::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	229 builtin: open
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	230 object: file
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 :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	233 arguments: ``open(filename, mode)``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	234
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	235 ::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	236
44383 3625234bf3d2 Some cleanup in the docs. Georg Brandl <georg@python.org> parents: 43413 diff changeset	237 >>> f = open('/tmp/workfile', 'w')
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	238 >>> print f
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	239 <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	240
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	241 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	242 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	243 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	244 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	245 ``'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	246 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	247 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	248 omitted.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	249
49184 59db4b3a06b0 Remove things specific to the old Macintosh, and spell "Mac OS X" consistently. Georg Brandl <georg@python.org> parents: 48197 diff changeset	250 On Windows, ``'b'`` appended to the mode opens the file in binary mode, so there
55945 9ace86299bb8 Change to tutorial wording for reading text / binary files on Windows. Issue #6301. Michael Foord <fuzzyman@voidspace.org.uk> parents: 55787 diff changeset	251 are also modes like ``'rb'``, ``'wb'``, and ``'r+b'``. Python on Windows makes
9ace86299bb8 Change to tutorial wording for reading text / binary files on Windows. Issue #6301. Michael Foord <fuzzyman@voidspace.org.uk> parents: 55787 diff changeset	252 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	253 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	254 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	255 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	256 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	257 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	258 platform-independently for all binary files.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	259
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	260
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	261 .. _tut-filemethods:
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 Methods of File Objects
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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	266 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	267 ``f`` has already been created.
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 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	270 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	271 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	272 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	273 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	274 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	275 ::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	276
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	277 >>> f.read()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	278 'This is the entire file.\n'
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 ''
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	281
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	282 ``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	283 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	284 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	285 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	286 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	287 containing only a single newline. ::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	288
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	289 >>> f.readline()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	290 '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	291 >>> f.readline()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	292 'Second 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 ''
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	295
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	296 ``f.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	297 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	298 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	299 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	300 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	301 ::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	302
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	303 >>> f.readlines()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	304 ['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	305
43413 409091b28c7e alternate -> alternative. Georg Brandl <georg@python.org> parents: 42604 diff changeset	306 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	307 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	308
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	309 >>> for line in f:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	310 print line,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	311
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	312 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	313 Second line of the file
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	314
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	315 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	316 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	317 should not be mixed.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	318
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	319 ``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	320 ``None``. ::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	321
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	322 >>> f.write('This is a test\n')
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	323
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	324 To write something other than a string, it needs to be converted to a string
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	325 first::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	326
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	327 >>> value = ('the answer', 42)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	328 >>> s = str(value)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	329 >>> f.write(s)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	330
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	331 ``f.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	332 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	333 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	334 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	335 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	336 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	337 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	338 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	339
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	340 >>> f = open('/tmp/workfile', 'r+')
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	341 >>> f.write('0123456789abcdef')
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	342 >>> f.seek(5) # Go to the 6th byte in the file
50508 c52177f36852 Remove trailing whitespace. Georg Brandl <georg@python.org> parents: 50459 diff changeset	343 >>> f.read(1)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	344 '5'
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	345 >>> 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	346 >>> f.read(1)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	347 'd'
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	348
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	349 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	350 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	351 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	352
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	353 >>> f.close()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	354 >>> f.read()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	355 Traceback (most recent call last):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	356 File "<stdin>", line 1, in ?
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	357 ValueError: I/O operation on closed file
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	358
47996 d31d61f46498 #3388: add a paragraph about using "with" for file objects. Georg Brandl <georg@python.org> parents: 47282 diff changeset	359 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	360 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	361 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	362 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	363
d31d61f46498 #3388: add a paragraph about using "with" for file objects. Georg Brandl <georg@python.org> parents: 47282 diff changeset	364 >>> 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	365 ... read_data = f.read()
d31d61f46498 #3388: add a paragraph about using "with" for file objects. Georg Brandl <georg@python.org> parents: 47282 diff changeset	366 >>> f.closed
d31d61f46498 #3388: add a paragraph about using "with" for file objects. Georg Brandl <georg@python.org> parents: 47282 diff changeset	367 True
d31d61f46498 #3388: add a paragraph about using "with" for file objects. Georg Brandl <georg@python.org> parents: 47282 diff changeset	368
55500 4fe5801bf712 Fix a few markup glitches. Georg Brandl <georg@python.org> parents: 55320 diff changeset	369 File objects have some additional methods, such as :meth:`~file.isatty` and
4fe5801bf712 Fix a few markup glitches. Georg Brandl <georg@python.org> parents: 55320 diff changeset	370 :meth:`~file.truncate` which are less frequently used; consult the Library
4fe5801bf712 Fix a few markup glitches. Georg Brandl <georg@python.org> parents: 55320 diff changeset	371 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	372
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	373
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	374 .. _tut-pickle:
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 The :mod:`pickle` Module
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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	379 .. index:: module: pickle
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 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	382 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	383 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	384 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	385 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	386 complicated.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	387
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	388 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	389 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	390 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	391 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	392 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	393 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	394 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	395 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	396
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	397 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	398 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	399
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	400 pickle.dump(x, f)
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 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	403 for reading::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	404
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	405 x = pickle.load(f)
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 (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	408 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	409 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	410
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	411 :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	412 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	413 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	414 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	415 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	416
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	417

Mercurial > cpython-lru_cache-weakref

annotate Doc/tutorial/inputoutput.rst @ 58765:2ba7677bfa95 legacy-trunk