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

annotate Doc/tutorial/inputoutput.rst @ 60008:0dfd62076ded

author	Benjamin Peterson <benjamin@python.org>
date	Thu, 25 Mar 2010 01:11:10 +0000
parents	afbb2b2ff6f7
children	bed950cbd0c0

rev	line source
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1 .. _tut-io:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	3 ****************
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	4 Input and Output
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	5 ****************
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	6
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	7 There are several ways to present the output of a program; data can be printed
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	8 in a human-readable form, or written to a file for future use. This chapter will
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	9 discuss some of the possibilities.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	10
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	11
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	12 .. _tut-formatting:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	13
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	14 Fancier Output Formatting
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	15 =========================
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	16
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	17 So far we've encountered two ways of writing values: expression statements and
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42604 diff changeset	18 the :func:`print` function. (A third way is using the :meth:`write` method
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	19 of file objects; the standard output file can be referenced as ``sys.stdout``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	20 See the Library Reference for more information on this.)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	21
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	22 .. index:: module: string
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	23
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	24 Often you'll want more control over the formatting of your output than simply
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	25 printing space-separated values. There are two ways to format your output; the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	26 first way is to do all the string handling yourself; using string slicing and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	27 concatenation operations you can create any layout you can imagine. The
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	28 standard module :mod:`string` contains some useful operations for padding
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	29 strings to a given column width; these will be discussed shortly. The second
47283 f28cbab11acd Merged revisions 63655 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 44999 diff changeset	30 way is to use the :meth:`str.format` method.
f28cbab11acd Merged revisions 63655 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 44999 diff changeset	31
f28cbab11acd Merged revisions 63655 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 44999 diff changeset	32 The :mod:`string` module contains a class Template which offers yet another way
f28cbab11acd Merged revisions 63655 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 44999 diff changeset	33 to substitute values into strings.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	34
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	35 One question remains, of course: how do you convert values to strings? Luckily,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	36 Python has ways to convert any value to a string: pass it to the :func:`repr`
48666 fd7b93a01c04 #3523: no backquotes any more. Georg Brandl <georg@python.org> parents: 48655 diff changeset	37 or :func:`str` functions.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	38
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	39 The :func:`str` function is meant to return representations of values which are
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	40 fairly human-readable, while :func:`repr` is meant to generate representations
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	41 which can be read by the interpreter (or will force a :exc:`SyntaxError` if
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	42 there is not equivalent syntax). For objects which don't have a particular
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	43 representation for human consumption, :func:`str` will return the same value as
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	44 :func:`repr`. Many values, such as numbers or structures like lists and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	45 dictionaries, have the same representation using either function. Strings and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	46 floating point numbers, in particular, have two distinct representations.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	47
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	48 Some examples::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	49
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	50 >>> s = 'Hello, world.'
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	51 >>> str(s)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	52 'Hello, world.'
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	53 >>> repr(s)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	54 "'Hello, world.'"
54927 e3025a4c0ad7 Merged revisions 73636 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 51776 diff changeset	55 >>> str(1.0/7.0)
e3025a4c0ad7 Merged revisions 73636 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 51776 diff changeset	56 '0.142857142857'
e3025a4c0ad7 Merged revisions 73636 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 51776 diff changeset	57 >>> repr(1.0/7.0)
e3025a4c0ad7 Merged revisions 73636 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 51776 diff changeset	58 '0.14285714285714285'
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	59 >>> x = 10 * 3.25
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	60 >>> y = 200 * 200
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	61 >>> s = 'The value of x is ' + repr(x) + ', and y is ' + repr(y) + '...'
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42604 diff changeset	62 >>> print(s)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	63 The value of x is 32.5, and y is 40000...
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	64 >>> # The repr() of a string adds string quotes and backslashes:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	65 ... hello = 'hello, world\n'
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	66 >>> hellos = repr(hello)
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42604 diff changeset	67 >>> print(hellos)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	68 'hello, world\n'
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	69 >>> # The argument to repr() may be any Python object:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	70 ... repr((x, y, ('spam', 'eggs')))
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	71 "(32.5, 40000, ('spam', 'eggs'))"
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	72
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	73 Here are two ways to write a table of squares and cubes::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	74
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	75 >>> for x in range(1, 11):
43201 4902671dd678 Tutorial formatting patch by Robin Stocker. Georg Brandl <georg@python.org> parents: 43115 diff changeset	76 ... print(repr(x).rjust(2), repr(x*x).rjust(3), end=' ')
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42604 diff changeset	77 ... # Note use of 'end' on previous line
95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42604 diff changeset	78 ... print(repr(xxx).rjust(4))
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	79 ...
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	80 1 1 1
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	81 2 4 8
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	82 3 9 27
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	83 4 16 64
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	84 5 25 125
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	85 6 36 216
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	86 7 49 343
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	87 8 64 512
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	88 9 81 729
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	89 10 100 1000
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	90
43201 4902671dd678 Tutorial formatting patch by Robin Stocker. Georg Brandl <georg@python.org> parents: 43115 diff changeset	91 >>> for x in range(1, 11):
47283 f28cbab11acd Merged revisions 63655 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 44999 diff changeset	92 ... print('{0:2d} {1:3d} {2:4d}'.format(x, xx, xx*x))
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 48668 diff changeset	93 ...
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	94 1 1 1
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	95 2 4 8
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	96 3 9 27
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	97 4 16 64
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	98 5 25 125
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	99 6 36 216
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	100 7 49 343
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	101 8 64 512
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	102 9 81 729
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	103 10 100 1000
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	104
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	105 (Note that in the first example, one space between each column was added by the
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42604 diff changeset	106 way :func:`print` works: it always adds spaces between its arguments.)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	107
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	108 This example demonstrates the :meth:`rjust` method of string objects, which
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	109 right-justifies a string in a field of a given width by padding it with spaces
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	110 on the left. There are similar methods :meth:`ljust` and :meth:`center`. These
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	111 methods do not write anything, they just return a new string. If the input
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	112 string is too long, they don't truncate it, but return it unchanged; this will
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	113 mess up your column lay-out but that's usually better than the alternative,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	114 which would be lying about a value. (If you really want truncation you can
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	115 always add a slice operation, as in ``x.ljust(n)[:n]``.)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	116
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	117 There is another method, :meth:`zfill`, which pads a numeric string on the left
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	118 with zeros. It understands about plus and minus signs::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	119
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	120 >>> '12'.zfill(5)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	121 '00012'
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	122 >>> '-3.14'.zfill(7)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	123 '-003.14'
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	124 >>> '3.14159265359'.zfill(5)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	125 '3.14159265359'
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	126
47283 f28cbab11acd Merged revisions 63655 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 44999 diff changeset	127 Basic usage of the :meth:`str.format` method looks like this::
f28cbab11acd Merged revisions 63655 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 44999 diff changeset	128
55797 afbb2b2ff6f7 Merged revisions 74613,74615,74619-74620,74622 via svnmerge from Georg Brandl <georg@python.org> parents: 55584 diff changeset	129 >>> print('We are the {} who say "{}!"'.format('knights', 'Ni'))
47283 f28cbab11acd Merged revisions 63655 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 44999 diff changeset	130 We are the knights who say "Ni!"
f28cbab11acd Merged revisions 63655 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 44999 diff changeset	131
f28cbab11acd Merged revisions 63655 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 44999 diff changeset	132 The brackets and characters within them (called format fields) are replaced with
55797 afbb2b2ff6f7 Merged revisions 74613,74615,74619-74620,74622 via svnmerge from Georg Brandl <georg@python.org> parents: 55584 diff changeset	133 the objects passed into the :meth:`~str.format` method. A number in the
afbb2b2ff6f7 Merged revisions 74613,74615,74619-74620,74622 via svnmerge from Georg Brandl <georg@python.org> parents: 55584 diff changeset	134 brackets can be used to refer to the position of the object passed into the
55580 7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 54927 diff changeset	135 :meth:`~str.format` method. ::
47283 f28cbab11acd Merged revisions 63655 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 44999 diff changeset	136
48577 71532ad7f3ed fix print syntax in tutorial Benjamin Peterson <benjamin@python.org> parents: 48563 diff changeset	137 >>> print('{0} and {1}'.format('spam', 'eggs'))
47283 f28cbab11acd Merged revisions 63655 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 44999 diff changeset	138 spam and eggs
48577 71532ad7f3ed fix print syntax in tutorial Benjamin Peterson <benjamin@python.org> parents: 48563 diff changeset	139 >>> print('{1} and {0}'.format('spam', 'eggs'))
47283 f28cbab11acd Merged revisions 63655 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 44999 diff changeset	140 eggs and spam
f28cbab11acd Merged revisions 63655 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 44999 diff changeset	141
55580 7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 54927 diff changeset	142 If keyword arguments are used in the :meth:`~str.format` method, their values
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 54927 diff changeset	143 are referred to by using the name of the argument. ::
47283 f28cbab11acd Merged revisions 63655 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 44999 diff changeset	144
48578 b8d4dbb2938a Merged revisions 65253 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 48577 diff changeset	145 >>> print('This {food} is {adjective}.'.format(
b8d4dbb2938a Merged revisions 65253 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 48577 diff changeset	146 ... food='spam', adjective='absolutely horrible'))
47283 f28cbab11acd Merged revisions 63655 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 44999 diff changeset	147 This spam is absolutely horrible.
f28cbab11acd Merged revisions 63655 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 44999 diff changeset	148
f28cbab11acd Merged revisions 63655 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 44999 diff changeset	149 Positional and keyword arguments can be arbitrarily combined::
f28cbab11acd Merged revisions 63655 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 44999 diff changeset	150
48578 b8d4dbb2938a Merged revisions 65253 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 48577 diff changeset	151 >>> print('The story of {0}, {1}, and {other}.'.format('Bill', 'Manfred',
b8d4dbb2938a Merged revisions 65253 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 48577 diff changeset	152 other='Georg'))
47283 f28cbab11acd Merged revisions 63655 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 44999 diff changeset	153 The story of Bill, Manfred, and Georg.
f28cbab11acd Merged revisions 63655 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 44999 diff changeset	154
55797 afbb2b2ff6f7 Merged revisions 74613,74615,74619-74620,74622 via svnmerge from Georg Brandl <georg@python.org> parents: 55584 diff changeset	155 ``'!a'`` (apply :func:`ascii`), ``'!s'`` (apply :func:`str`) and ``'!r'``
afbb2b2ff6f7 Merged revisions 74613,74615,74619-74620,74622 via svnmerge from Georg Brandl <georg@python.org> parents: 55584 diff changeset	156 (apply :func:`repr`) can be used to convert the value before it is formatted::
afbb2b2ff6f7 Merged revisions 74613,74615,74619-74620,74622 via svnmerge from Georg Brandl <georg@python.org> parents: 55584 diff changeset	157
afbb2b2ff6f7 Merged revisions 74613,74615,74619-74620,74622 via svnmerge from Georg Brandl <georg@python.org> parents: 55584 diff changeset	158 >>> import math
afbb2b2ff6f7 Merged revisions 74613,74615,74619-74620,74622 via svnmerge from Georg Brandl <georg@python.org> parents: 55584 diff changeset	159 >>> print('The value of PI is approximately {}.'.format(math.pi))
afbb2b2ff6f7 Merged revisions 74613,74615,74619-74620,74622 via svnmerge from Georg Brandl <georg@python.org> parents: 55584 diff changeset	160 The value of PI is approximately 3.14159265359.
afbb2b2ff6f7 Merged revisions 74613,74615,74619-74620,74622 via svnmerge from Georg Brandl <georg@python.org> parents: 55584 diff changeset	161 >>> print('The value of PI is approximately {!r}.'.format(math.pi))
afbb2b2ff6f7 Merged revisions 74613,74615,74619-74620,74622 via svnmerge from Georg Brandl <georg@python.org> parents: 55584 diff changeset	162 The value of PI is approximately 3.141592653589793.
afbb2b2ff6f7 Merged revisions 74613,74615,74619-74620,74622 via svnmerge from Georg Brandl <georg@python.org> parents: 55584 diff changeset	163
55584 5fbac09c0e91 Merged revisions 74264 via svnmerge from Georg Brandl <georg@python.org> parents: 55580 diff changeset	164 An optional ``':'`` and format specifier can follow the field name. This allows
47283 f28cbab11acd Merged revisions 63655 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 44999 diff changeset	165 greater control over how the value is formatted. The following example
55584 5fbac09c0e91 Merged revisions 74264 via svnmerge from Georg Brandl <georg@python.org> parents: 55580 diff changeset	166 truncates Pi to three places after the decimal.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	167
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	168 >>> import math
47283 f28cbab11acd Merged revisions 63655 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 44999 diff changeset	169 >>> print('The value of PI is approximately {0:.3f}.'.format(math.pi))
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	170 The value of PI is approximately 3.142.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	171
47283 f28cbab11acd Merged revisions 63655 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 44999 diff changeset	172 Passing an integer after the ``':'`` will cause that field to be a minimum
55580 7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 54927 diff changeset	173 number of characters wide. This is useful for making tables pretty. ::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	174
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	175 >>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 7678}
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	176 >>> for name, phone in table.items():
47283 f28cbab11acd Merged revisions 63655 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 44999 diff changeset	177 ... print('{0:10} ==> {1:10d}'.format(name, phone))
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 48668 diff changeset	178 ...
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	179 Jack ==> 4098
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	180 Dcab ==> 7678
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	181 Sjoerd ==> 4127
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	182
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	183 If you have a really long format string that you don't want to split up, it
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	184 would be nice if you could reference the variables to be formatted by name
47283 f28cbab11acd Merged revisions 63655 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 44999 diff changeset	185 instead of by position. This can be done by simply passing the dict and using
f28cbab11acd Merged revisions 63655 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 44999 diff changeset	186 square brackets ``'[]'`` to access the keys ::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	187
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	188 >>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 8637678}
48578 b8d4dbb2938a Merged revisions 65253 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 48577 diff changeset	189 >>> print('Jack: {0[Jack]:d}; Sjoerd: {0[Sjoerd]:d}; '
b8d4dbb2938a Merged revisions 65253 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 48577 diff changeset	190 'Dcab: {0[Dcab]:d}'.format(table))
47283 f28cbab11acd Merged revisions 63655 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 44999 diff changeset	191 Jack: 4098; Sjoerd: 4127; Dcab: 8637678
f28cbab11acd Merged revisions 63655 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 44999 diff changeset	192
f28cbab11acd Merged revisions 63655 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 44999 diff changeset	193 This could also be done by passing the table as keyword arguments with the '**'
55580 7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 54927 diff changeset	194 notation. ::
47283 f28cbab11acd Merged revisions 63655 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 44999 diff changeset	195
f28cbab11acd Merged revisions 63655 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 44999 diff changeset	196 >>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 8637678}
f28cbab11acd Merged revisions 63655 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 44999 diff changeset	197 >>> print('Jack: {Jack:d}; Sjoerd: {Sjoerd:d}; Dcab: {Dcab:d}'.format(**table))
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	198 Jack: 4098; Sjoerd: 4127; Dcab: 8637678
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	199
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	200 This is particularly useful in combination with the new built-in :func:`vars`
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	201 function, which returns a dictionary containing all local variables.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	202
51776 d06a3ebf306f Merged revisions 69846 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 50569 diff changeset	203 For a complete overview of string formatting with :meth:`str.format`, see
47283 f28cbab11acd Merged revisions 63655 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 44999 diff changeset	204 :ref:`formatstrings`.
f28cbab11acd Merged revisions 63655 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 44999 diff changeset	205
f28cbab11acd Merged revisions 63655 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 44999 diff changeset	206
f28cbab11acd Merged revisions 63655 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 44999 diff changeset	207 Old string formatting
f28cbab11acd Merged revisions 63655 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 44999 diff changeset	208 ---------------------
f28cbab11acd Merged revisions 63655 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 44999 diff changeset	209
f28cbab11acd Merged revisions 63655 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 44999 diff changeset	210 The ``%`` operator can also be used for string formatting. It interprets the
f28cbab11acd Merged revisions 63655 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 44999 diff changeset	211 left argument much like a :cfunc:`sprintf`\ -style format string to be applied
f28cbab11acd Merged revisions 63655 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 44999 diff changeset	212 to the right argument, and returns the string resulting from this formatting
f28cbab11acd Merged revisions 63655 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 44999 diff changeset	213 operation. For example::
f28cbab11acd Merged revisions 63655 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 44999 diff changeset	214
f28cbab11acd Merged revisions 63655 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 44999 diff changeset	215 >>> import math
48655 1635891b18e8 #3503: fix print statements in 3k doc. Georg Brandl <georg@python.org> parents: 48578 diff changeset	216 >>> print('The value of PI is approximately %5.3f.' % math.pi)
47283 f28cbab11acd Merged revisions 63655 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 44999 diff changeset	217 The value of PI is approximately 3.142.
f28cbab11acd Merged revisions 63655 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 44999 diff changeset	218
f28cbab11acd Merged revisions 63655 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 44999 diff changeset	219 Since :meth:`str.format` is quite new, a lot of Python code still uses the ``%``
55584 5fbac09c0e91 Merged revisions 74264 via svnmerge from Georg Brandl <georg@python.org> parents: 55580 diff changeset	220 operator. However, because this old style of formatting will eventually be
5fbac09c0e91 Merged revisions 74264 via svnmerge from Georg Brandl <georg@python.org> parents: 55580 diff changeset	221 removed from the language, :meth:`str.format` should generally be used.
47283 f28cbab11acd Merged revisions 63655 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 44999 diff changeset	222
f28cbab11acd Merged revisions 63655 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 44999 diff changeset	223 More information can be found in the :ref:`old-string-formatting` section.
f28cbab11acd Merged revisions 63655 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 44999 diff changeset	224
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	225
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	226 .. _tut-files:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	227
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	228 Reading and Writing Files
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	229 =========================
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	230
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	231 .. index::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	232 builtin: open
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	233 object: file
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	234
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	235 :func:`open` returns a file object, and is most commonly used with two
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	236 arguments: ``open(filename, mode)``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	237
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	238 ::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	239
44396 6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 43440 diff changeset	240 >>> f = open('/tmp/workfile', 'w')
48668 e2c706f9906c #3524: fix up some old-style IO descriptions. Georg Brandl <georg@python.org> parents: 48666 diff changeset	241
e2c706f9906c #3524: fix up some old-style IO descriptions. Georg Brandl <georg@python.org> parents: 48666 diff changeset	242 .. XXX str(f) is <io.TextIOWrapper object at 0x82e8dc4>
e2c706f9906c #3524: fix up some old-style IO descriptions. Georg Brandl <georg@python.org> parents: 48666 diff changeset	243
43115 95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois. Guido van Rossum <guido@python.org> parents: 42604 diff changeset	244 >>> print(f)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	245 <open file '/tmp/workfile', mode 'w' at 80a0960>
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	246
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	247 The first argument is a string containing the filename. The second argument is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	248 another string containing a few characters describing the way in which the file
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	249 will be used. mode can be ``'r'`` when the file will only be read, ``'w'``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	250 for only writing (an existing file with the same name will be erased), and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	251 ``'a'`` opens the file for appending; any data written to the file is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	252 automatically added to the end. ``'r+'`` opens the file for both reading and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	253 writing. The mode argument is optional; ``'r'`` will be assumed if it's
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	254 omitted.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	255
48668 e2c706f9906c #3524: fix up some old-style IO descriptions. Georg Brandl <georg@python.org> parents: 48666 diff changeset	256 Normally, files are opened in :dfn:`text mode`, that means, you read and write
e2c706f9906c #3524: fix up some old-style IO descriptions. Georg Brandl <georg@python.org> parents: 48666 diff changeset	257 strings from and to the file, which are encoded in a specific encoding (the
e2c706f9906c #3524: fix up some old-style IO descriptions. Georg Brandl <georg@python.org> parents: 48666 diff changeset	258 default being UTF-8). ``'b'`` appended to the mode opens the file in
e2c706f9906c #3524: fix up some old-style IO descriptions. Georg Brandl <georg@python.org> parents: 48666 diff changeset	259 :dfn:`binary mode`: now the data is read and written in the form of bytes
e2c706f9906c #3524: fix up some old-style IO descriptions. Georg Brandl <georg@python.org> parents: 48666 diff changeset	260 objects. This mode should be used for all files that don't contain text.
43440 8d7e93b47cab Clarify the difference between text and binary files. I'm not sure the Skip Montanaro <skip@pobox.com> parents: 43418 diff changeset	261
48668 e2c706f9906c #3524: fix up some old-style IO descriptions. Georg Brandl <georg@python.org> parents: 48666 diff changeset	262 In text mode, the default is to convert platform-specific line endings (``\n``
e2c706f9906c #3524: fix up some old-style IO descriptions. Georg Brandl <georg@python.org> parents: 48666 diff changeset	263 on Unix, ``\r\n`` on Windows) to just ``\n`` on reading and ``\n`` back to
e2c706f9906c #3524: fix up some old-style IO descriptions. Georg Brandl <georg@python.org> parents: 48666 diff changeset	264 platform-specific line endings on writing. This behind-the-scenes modification
e2c706f9906c #3524: fix up some old-style IO descriptions. Georg Brandl <georg@python.org> parents: 48666 diff changeset	265 to file data is fine for text files, but will corrupt binary data like that in
e2c706f9906c #3524: fix up some old-style IO descriptions. Georg Brandl <georg@python.org> parents: 48666 diff changeset	266 :file:`JPEG` or :file:`EXE` files. Be very careful to use binary mode when
e2c706f9906c #3524: fix up some old-style IO descriptions. Georg Brandl <georg@python.org> parents: 48666 diff changeset	267 reading and writing such files.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	268
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	269
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	270 .. _tut-filemethods:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	271
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	272 Methods of File Objects
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	273 -----------------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	274
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	275 The rest of the examples in this section will assume that a file object called
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	276 ``f`` has already been created.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	277
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	278 To read a file's contents, call ``f.read(size)``, which reads some quantity of
48668 e2c706f9906c #3524: fix up some old-style IO descriptions. Georg Brandl <georg@python.org> parents: 48666 diff changeset	279 data and returns it as a string or bytes object. size is an optional numeric
e2c706f9906c #3524: fix up some old-style IO descriptions. Georg Brandl <georg@python.org> parents: 48666 diff changeset	280 argument. When size is omitted or negative, the entire contents of the file
e2c706f9906c #3524: fix up some old-style IO descriptions. Georg Brandl <georg@python.org> parents: 48666 diff changeset	281 will be read and returned; it's your problem if the file is twice as large as
e2c706f9906c #3524: fix up some old-style IO descriptions. Georg Brandl <georg@python.org> parents: 48666 diff changeset	282 your machine's memory. Otherwise, at most size bytes are read and returned.
e2c706f9906c #3524: fix up some old-style IO descriptions. Georg Brandl <georg@python.org> parents: 48666 diff changeset	283 If the end of the file has been reached, ``f.read()`` will return an empty
e2c706f9906c #3524: fix up some old-style IO descriptions. Georg Brandl <georg@python.org> parents: 48666 diff changeset	284 string (``''``). ::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	285
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	286 >>> f.read()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	287 'This is the entire file.\n'
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	288 >>> f.read()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	289 ''
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	290
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	291 ``f.readline()`` reads a single line from the file; a newline character (``\n``)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	292 is left at the end of the string, and is only omitted on the last line of the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	293 file if the file doesn't end in a newline. This makes the return value
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	294 unambiguous; if ``f.readline()`` returns an empty string, the end of the file
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	295 has been reached, while a blank line is represented by ``'\n'``, a string
48668 e2c706f9906c #3524: fix up some old-style IO descriptions. Georg Brandl <georg@python.org> parents: 48666 diff changeset	296 containing only a single newline. ::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	297
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	298 >>> f.readline()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	299 'This is the first line of the file.\n'
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	300 >>> f.readline()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	301 'Second line of the file\n'
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	302 >>> f.readline()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	303 ''
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	304
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	305 ``f.readlines()`` returns a list containing all the lines of data in the file.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	306 If given an optional parameter sizehint, it reads that many bytes from the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	307 file and enough more to complete a line, and returns the lines from that. This
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	308 is often used to allow efficient reading of a large file by lines, but without
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	309 having to load the entire file in memory. Only complete lines will be returned.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	310 ::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	311
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	312 >>> f.readlines()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	313 ['This is the first line of the file.\n', 'Second line of the file\n']
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	314
43418 0c8fec76111c Merged revisions 58211-58220 via svnmerge from Thomas Wouters <thomas@python.org> parents: 43219 diff changeset	315 An alternative approach to reading lines is to loop over the file object. This is
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	316 memory efficient, fast, and leads to simpler code::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	317
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	318 >>> for line in f:
48668 e2c706f9906c #3524: fix up some old-style IO descriptions. Georg Brandl <georg@python.org> parents: 48666 diff changeset	319 ... print(line, end='')
e2c706f9906c #3524: fix up some old-style IO descriptions. Georg Brandl <georg@python.org> parents: 48666 diff changeset	320 ...
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	321 This is the first line of the file.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	322 Second line of the file
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	323
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	324 The alternative approach is simpler but does not provide as fine-grained
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	325 control. Since the two approaches manage line buffering differently, they
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	326 should not be mixed.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	327
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	328 ``f.write(string)`` writes the contents of string to the file, returning
48668 e2c706f9906c #3524: fix up some old-style IO descriptions. Georg Brandl <georg@python.org> parents: 48666 diff changeset	329 the number of characters written. ::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	330
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	331 >>> f.write('This is a test\n')
48668 e2c706f9906c #3524: fix up some old-style IO descriptions. Georg Brandl <georg@python.org> parents: 48666 diff changeset	332 15
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	333
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	334 To write something other than a string, it needs to be converted to a string
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	335 first::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	336
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	337 >>> value = ('the answer', 42)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	338 >>> s = str(value)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	339 >>> f.write(s)
48668 e2c706f9906c #3524: fix up some old-style IO descriptions. Georg Brandl <georg@python.org> parents: 48666 diff changeset	340 18
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	341
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	342 ``f.tell()`` returns an integer giving the file object's current position in the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	343 file, measured in bytes from the beginning of the file. To change the file
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	344 object's position, use ``f.seek(offset, from_what)``. The position is computed
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	345 from adding offset to a reference point; the reference point is selected by
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	346 the from_what argument. A from_what value of 0 measures from the beginning
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	347 of the file, 1 uses the current file position, and 2 uses the end of the file as
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	348 the reference point. from_what can be omitted and defaults to 0, using the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	349 beginning of the file as the reference point. ::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	350
48668 e2c706f9906c #3524: fix up some old-style IO descriptions. Georg Brandl <georg@python.org> parents: 48666 diff changeset	351 >>> f = open('/tmp/workfile', 'rb+')
e2c706f9906c #3524: fix up some old-style IO descriptions. Georg Brandl <georg@python.org> parents: 48666 diff changeset	352 >>> f.write(b'0123456789abcdef')
e2c706f9906c #3524: fix up some old-style IO descriptions. Georg Brandl <georg@python.org> parents: 48666 diff changeset	353 16
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	354 >>> f.seek(5) # Go to the 6th byte in the file
48668 e2c706f9906c #3524: fix up some old-style IO descriptions. Georg Brandl <georg@python.org> parents: 48666 diff changeset	355 5
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 48668 diff changeset	356 >>> f.read(1)
48668 e2c706f9906c #3524: fix up some old-style IO descriptions. Georg Brandl <georg@python.org> parents: 48666 diff changeset	357 b'5'
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	358 >>> f.seek(-3, 2) # Go to the 3rd byte before the end
48668 e2c706f9906c #3524: fix up some old-style IO descriptions. Georg Brandl <georg@python.org> parents: 48666 diff changeset	359 13
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	360 >>> f.read(1)
48668 e2c706f9906c #3524: fix up some old-style IO descriptions. Georg Brandl <georg@python.org> parents: 48666 diff changeset	361 b'd'
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	362
48668 e2c706f9906c #3524: fix up some old-style IO descriptions. Georg Brandl <georg@python.org> parents: 48666 diff changeset	363 In text files (those opened without a ``b`` in the mode string), only seeks
e2c706f9906c #3524: fix up some old-style IO descriptions. Georg Brandl <georg@python.org> parents: 48666 diff changeset	364 relative to the beginning of the file are allowed (the exception being seeking
e2c706f9906c #3524: fix up some old-style IO descriptions. Georg Brandl <georg@python.org> parents: 48666 diff changeset	365 to the very file end with ``seek(0, 2)``).
50563 93cf3a6ead63 Merged revisions 68226 via svnmerge from Georg Brandl <georg@python.org> parents: 48668 diff changeset	366
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	367 When you're done with a file, call ``f.close()`` to close it and free up any
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	368 system resources taken up by the open file. After calling ``f.close()``,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	369 attempts to use the file object will automatically fail. ::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	370
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	371 >>> f.close()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	372 >>> f.read()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	373 Traceback (most recent call last):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	374 File "<stdin>", line 1, in ?
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	375 ValueError: I/O operation on closed file
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	376
48563 b51cd5d3795c Merged revisions 65012,65035,65037-65040,65048,65057,65077,65091-65095,65097-65099,65127-65128,65131,65133-65136,65139,65149-65151,65155,65158-65159,65176-65178,65183-65184,65187-65190,65192,65194 via svnmerge from Georg Brandl <georg@python.org> parents: 47283 diff changeset	377 It is good practice to use the :keyword:`with` keyword when dealing with file
b51cd5d3795c Merged revisions 65012,65035,65037-65040,65048,65057,65077,65091-65095,65097-65099,65127-65128,65131,65133-65136,65139,65149-65151,65155,65158-65159,65176-65178,65183-65184,65187-65190,65192,65194 via svnmerge from Georg Brandl <georg@python.org> parents: 47283 diff changeset	378 objects. This has the advantage that the file is properly closed after its
b51cd5d3795c Merged revisions 65012,65035,65037-65040,65048,65057,65077,65091-65095,65097-65099,65127-65128,65131,65133-65136,65139,65149-65151,65155,65158-65159,65176-65178,65183-65184,65187-65190,65192,65194 via svnmerge from Georg Brandl <georg@python.org> parents: 47283 diff changeset	379 suite finishes, even if an exception is raised on the way. It is also much
b51cd5d3795c Merged revisions 65012,65035,65037-65040,65048,65057,65077,65091-65095,65097-65099,65127-65128,65131,65133-65136,65139,65149-65151,65155,65158-65159,65176-65178,65183-65184,65187-65190,65192,65194 via svnmerge from Georg Brandl <georg@python.org> parents: 47283 diff changeset	380 shorter than writing equivalent :keyword:`try`\ -\ :keyword:`finally` blocks::
b51cd5d3795c Merged revisions 65012,65035,65037-65040,65048,65057,65077,65091-65095,65097-65099,65127-65128,65131,65133-65136,65139,65149-65151,65155,65158-65159,65176-65178,65183-65184,65187-65190,65192,65194 via svnmerge from Georg Brandl <georg@python.org> parents: 47283 diff changeset	381
b51cd5d3795c Merged revisions 65012,65035,65037-65040,65048,65057,65077,65091-65095,65097-65099,65127-65128,65131,65133-65136,65139,65149-65151,65155,65158-65159,65176-65178,65183-65184,65187-65190,65192,65194 via svnmerge from Georg Brandl <georg@python.org> parents: 47283 diff changeset	382 >>> with open('/tmp/workfile', 'r') as f:
b51cd5d3795c Merged revisions 65012,65035,65037-65040,65048,65057,65077,65091-65095,65097-65099,65127-65128,65131,65133-65136,65139,65149-65151,65155,65158-65159,65176-65178,65183-65184,65187-65190,65192,65194 via svnmerge from Georg Brandl <georg@python.org> parents: 47283 diff changeset	383 ... read_data = f.read()
b51cd5d3795c Merged revisions 65012,65035,65037-65040,65048,65057,65077,65091-65095,65097-65099,65127-65128,65131,65133-65136,65139,65149-65151,65155,65158-65159,65176-65178,65183-65184,65187-65190,65192,65194 via svnmerge from Georg Brandl <georg@python.org> parents: 47283 diff changeset	384 >>> f.closed
b51cd5d3795c Merged revisions 65012,65035,65037-65040,65048,65057,65077,65091-65095,65097-65099,65127-65128,65131,65133-65136,65139,65149-65151,65155,65158-65159,65176-65178,65183-65184,65187-65190,65192,65194 via svnmerge from Georg Brandl <georg@python.org> parents: 47283 diff changeset	385 True
b51cd5d3795c Merged revisions 65012,65035,65037-65040,65048,65057,65077,65091-65095,65097-65099,65127-65128,65131,65133-65136,65139,65149-65151,65155,65158-65159,65176-65178,65183-65184,65187-65190,65192,65194 via svnmerge from Georg Brandl <georg@python.org> parents: 47283 diff changeset	386
55580 7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 54927 diff changeset	387 File objects have some additional methods, such as :meth:`~file.isatty` and
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 54927 diff changeset	388 :meth:`~file.truncate` which are less frequently used; consult the Library
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 54927 diff changeset	389 Reference for a complete guide to file objects.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	390
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	391
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	392 .. _tut-pickle:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	393
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	394 The :mod:`pickle` Module
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	395 ------------------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	396
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	397 .. index:: module: pickle
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	398
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	399 Strings can easily be written to and read from a file. Numbers take a bit more
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	400 effort, since the :meth:`read` method only returns strings, which will have to
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	401 be passed to a function like :func:`int`, which takes a string like ``'123'``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	402 and returns its numeric value 123. However, when you want to save more complex
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	403 data types like lists, dictionaries, or class instances, things get a lot more
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	404 complicated.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	405
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	406 Rather than have users be constantly writing and debugging code to save
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	407 complicated data types, Python provides a standard module called :mod:`pickle`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	408 This is an amazing module that can take almost any Python object (even some
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	409 forms of Python code!), and convert it to a string representation; this process
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	410 is called :dfn:`pickling`. Reconstructing the object from the string
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	411 representation is called :dfn:`unpickling`. Between pickling and unpickling,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	412 the string representing the object may have been stored in a file or data, or
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	413 sent over a network connection to some distant machine.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	414
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	415 If you have an object ``x``, and a file object ``f`` that's been opened for
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	416 writing, the simplest way to pickle the object takes only one line of code::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	417
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	418 pickle.dump(x, f)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	419
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	420 To unpickle the object again, if ``f`` is a file object which has been opened
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	421 for reading::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	422
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	423 x = pickle.load(f)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	424
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	425 (There are other variants of this, used when pickling many objects or when you
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	426 don't want to write the pickled data to a file; consult the complete
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	427 documentation for :mod:`pickle` in the Python Library Reference.)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	428
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	429 :mod:`pickle` is the standard way to make Python objects which can be stored and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	430 reused by other programs or by a future invocation of the same program; the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	431 technical term for this is a :dfn:`persistent` object. Because :mod:`pickle` is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	432 so widely used, many authors who write Python extensions take care to ensure
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	433 that new data types such as matrices can be properly pickled and unpickled.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	434
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	435

Mercurial > cpython-lru_cache-weakref

annotate Doc/tutorial/inputoutput.rst @ 60008:0dfd62076ded