2007-08-15 22:28:22 +08:00
|
|
|
.. _tut-io:
|
|
|
|
|
|
|
|
****************
|
|
|
|
Input and Output
|
|
|
|
****************
|
|
|
|
|
|
|
|
There are several ways to present the output of a program; data can be printed
|
|
|
|
in a human-readable form, or written to a file for future use. This chapter will
|
|
|
|
discuss some of the possibilities.
|
|
|
|
|
|
|
|
|
|
|
|
.. _tut-formatting:
|
|
|
|
|
|
|
|
Fancier Output Formatting
|
|
|
|
=========================
|
|
|
|
|
|
|
|
So far we've encountered two ways of writing values: *expression statements* and
|
2007-08-31 11:25:11 +08:00
|
|
|
the :func:`print` function. (A third way is using the :meth:`write` method
|
2007-08-15 22:28:22 +08:00
|
|
|
of file objects; the standard output file can be referenced as ``sys.stdout``.
|
|
|
|
See the Library Reference for more information on this.)
|
|
|
|
|
|
|
|
Often you'll want more control over the formatting of your output than simply
|
|
|
|
printing space-separated values. There are two ways to format your output; the
|
|
|
|
first way is to do all the string handling yourself; using string slicing and
|
|
|
|
concatenation operations you can create any layout you can imagine. The
|
2011-03-06 17:56:18 +08:00
|
|
|
string type has some methods that perform useful operations for padding
|
2007-08-15 22:28:22 +08:00
|
|
|
strings to a given column width; these will be discussed shortly. The second
|
2008-05-26 09:03:56 +08:00
|
|
|
way is to use the :meth:`str.format` method.
|
|
|
|
|
2011-03-06 17:56:18 +08:00
|
|
|
The :mod:`string` module contains a :class:`~string.Template` class which offers
|
|
|
|
yet another way to substitute values into strings.
|
2007-08-15 22:28:22 +08:00
|
|
|
|
|
|
|
One question remains, of course: how do you convert values to strings? Luckily,
|
|
|
|
Python has ways to convert any value to a string: pass it to the :func:`repr`
|
2008-08-08 14:45:01 +08:00
|
|
|
or :func:`str` functions.
|
2007-08-15 22:28:22 +08:00
|
|
|
|
|
|
|
The :func:`str` function is meant to return representations of values which are
|
|
|
|
fairly human-readable, while :func:`repr` is meant to generate representations
|
|
|
|
which can be read by the interpreter (or will force a :exc:`SyntaxError` if
|
2012-08-15 01:51:43 +08:00
|
|
|
there is no equivalent syntax). For objects which don't have a particular
|
2007-08-15 22:28:22 +08:00
|
|
|
representation for human consumption, :func:`str` will return the same value as
|
|
|
|
:func:`repr`. Many values, such as numbers or structures like lists and
|
2011-03-13 08:27:26 +08:00
|
|
|
dictionaries, have the same representation using either function. Strings, in
|
|
|
|
particular, have two distinct representations.
|
2007-08-15 22:28:22 +08:00
|
|
|
|
|
|
|
Some examples::
|
|
|
|
|
|
|
|
>>> s = 'Hello, world.'
|
|
|
|
>>> str(s)
|
|
|
|
'Hello, world.'
|
|
|
|
>>> repr(s)
|
|
|
|
"'Hello, world.'"
|
2011-03-13 08:27:26 +08:00
|
|
|
>>> str(1/7)
|
2009-06-29 04:59:42 +08:00
|
|
|
'0.14285714285714285'
|
2007-08-15 22:28:22 +08:00
|
|
|
>>> x = 10 * 3.25
|
|
|
|
>>> y = 200 * 200
|
|
|
|
>>> s = 'The value of x is ' + repr(x) + ', and y is ' + repr(y) + '...'
|
2007-08-31 11:25:11 +08:00
|
|
|
>>> print(s)
|
2007-08-15 22:28:22 +08:00
|
|
|
The value of x is 32.5, and y is 40000...
|
|
|
|
>>> # The repr() of a string adds string quotes and backslashes:
|
|
|
|
... hello = 'hello, world\n'
|
|
|
|
>>> hellos = repr(hello)
|
2007-08-31 11:25:11 +08:00
|
|
|
>>> print(hellos)
|
2007-08-15 22:28:22 +08:00
|
|
|
'hello, world\n'
|
|
|
|
>>> # The argument to repr() may be any Python object:
|
|
|
|
... repr((x, y, ('spam', 'eggs')))
|
|
|
|
"(32.5, 40000, ('spam', 'eggs'))"
|
|
|
|
|
|
|
|
Here are two ways to write a table of squares and cubes::
|
|
|
|
|
|
|
|
>>> for x in range(1, 11):
|
2007-09-03 15:10:24 +08:00
|
|
|
... print(repr(x).rjust(2), repr(x*x).rjust(3), end=' ')
|
2007-08-31 11:25:11 +08:00
|
|
|
... # Note use of 'end' on previous line
|
|
|
|
... print(repr(x*x*x).rjust(4))
|
2007-08-15 22:28:22 +08:00
|
|
|
...
|
|
|
|
1 1 1
|
|
|
|
2 4 8
|
|
|
|
3 9 27
|
|
|
|
4 16 64
|
|
|
|
5 25 125
|
|
|
|
6 36 216
|
|
|
|
7 49 343
|
|
|
|
8 64 512
|
|
|
|
9 81 729
|
|
|
|
10 100 1000
|
|
|
|
|
2007-09-03 15:10:24 +08:00
|
|
|
>>> for x in range(1, 11):
|
2008-05-26 09:03:56 +08:00
|
|
|
... print('{0:2d} {1:3d} {2:4d}'.format(x, x*x, x*x*x))
|
2009-01-04 05:18:54 +08:00
|
|
|
...
|
2007-08-15 22:28:22 +08:00
|
|
|
1 1 1
|
|
|
|
2 4 8
|
|
|
|
3 9 27
|
|
|
|
4 16 64
|
|
|
|
5 25 125
|
|
|
|
6 36 216
|
|
|
|
7 49 343
|
|
|
|
8 64 512
|
|
|
|
9 81 729
|
|
|
|
10 100 1000
|
|
|
|
|
|
|
|
(Note that in the first example, one space between each column was added by the
|
2007-08-31 11:25:11 +08:00
|
|
|
way :func:`print` works: it always adds spaces between its arguments.)
|
2007-08-15 22:28:22 +08:00
|
|
|
|
2011-03-13 08:19:57 +08:00
|
|
|
This example demonstrates the :meth:`str.rjust` method of string
|
|
|
|
objects, which right-justifies a string in a field of a given width by padding
|
|
|
|
it with spaces on the left. There are similar methods :meth:`str.ljust` and
|
|
|
|
:meth:`str.center`. These methods do not write anything, they just return a
|
|
|
|
new string. If the input string is too long, they don't truncate it, but
|
|
|
|
return it unchanged; this will mess up your column lay-out but that's usually
|
|
|
|
better than the alternative, which would be lying about a value. (If you
|
|
|
|
really want truncation you can always add a slice operation, as in
|
|
|
|
``x.ljust(n)[:n]``.)
|
2007-08-15 22:28:22 +08:00
|
|
|
|
2011-03-13 08:19:57 +08:00
|
|
|
There is another method, :meth:`str.zfill`, which pads a numeric string on the
|
|
|
|
left with zeros. It understands about plus and minus signs::
|
2007-08-15 22:28:22 +08:00
|
|
|
|
|
|
|
>>> '12'.zfill(5)
|
|
|
|
'00012'
|
|
|
|
>>> '-3.14'.zfill(7)
|
|
|
|
'-003.14'
|
|
|
|
>>> '3.14159265359'.zfill(5)
|
|
|
|
'3.14159265359'
|
|
|
|
|
2008-05-26 09:03:56 +08:00
|
|
|
Basic usage of the :meth:`str.format` method looks like this::
|
|
|
|
|
2009-09-01 15:42:40 +08:00
|
|
|
>>> print('We are the {} who say "{}!"'.format('knights', 'Ni'))
|
2008-05-26 09:03:56 +08:00
|
|
|
We are the knights who say "Ni!"
|
|
|
|
|
|
|
|
The brackets and characters within them (called format fields) are replaced with
|
2011-03-13 08:19:57 +08:00
|
|
|
the objects passed into the :meth:`str.format` method. A number in the
|
2009-09-01 15:42:40 +08:00
|
|
|
brackets can be used to refer to the position of the object passed into the
|
2011-03-13 08:19:57 +08:00
|
|
|
:meth:`str.format` method. ::
|
2008-05-26 09:03:56 +08:00
|
|
|
|
2008-07-27 05:59:03 +08:00
|
|
|
>>> print('{0} and {1}'.format('spam', 'eggs'))
|
2008-05-26 09:03:56 +08:00
|
|
|
spam and eggs
|
2008-07-27 05:59:03 +08:00
|
|
|
>>> print('{1} and {0}'.format('spam', 'eggs'))
|
2008-05-26 09:03:56 +08:00
|
|
|
eggs and spam
|
|
|
|
|
2011-03-13 08:19:57 +08:00
|
|
|
If keyword arguments are used in the :meth:`str.format` method, their values
|
Merged revisions 74074,74077,74111,74188,74192-74193,74200,74252-74253,74258-74261 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r74074 | georg.brandl | 2009-07-18 05:03:10 -0400 (Sat, 18 Jul 2009) | 1 line
#6513: fix example code: warning categories are classes, not instances.
........
r74077 | georg.brandl | 2009-07-18 05:43:40 -0400 (Sat, 18 Jul 2009) | 1 line
#6489: fix an ambiguity in getiterator() documentation.
........
r74111 | benjamin.peterson | 2009-07-20 09:30:10 -0400 (Mon, 20 Jul 2009) | 1 line
remove docs for deprecated -p option
........
r74188 | benjamin.peterson | 2009-07-23 10:25:31 -0400 (Thu, 23 Jul 2009) | 1 line
use bools
........
r74192 | georg.brandl | 2009-07-24 12:28:38 -0400 (Fri, 24 Jul 2009) | 1 line
Fix arg types of et#.
........
r74193 | georg.brandl | 2009-07-24 12:46:38 -0400 (Fri, 24 Jul 2009) | 1 line
Dont put "void" in signature for nullary functions.
........
r74200 | georg.brandl | 2009-07-25 09:02:15 -0400 (Sat, 25 Jul 2009) | 1 line
#6571: add index entries for more operators.
........
r74252 | georg.brandl | 2009-07-29 12:06:31 -0400 (Wed, 29 Jul 2009) | 1 line
#6593: fix link targets.
........
r74253 | georg.brandl | 2009-07-29 12:09:17 -0400 (Wed, 29 Jul 2009) | 1 line
#6591: add reference to ioctl in fcntl module for platforms other than Windows.
........
r74258 | georg.brandl | 2009-07-29 12:57:05 -0400 (Wed, 29 Jul 2009) | 1 line
Add a link to readline, and mention IPython and bpython.
........
r74259 | georg.brandl | 2009-07-29 13:07:21 -0400 (Wed, 29 Jul 2009) | 1 line
Fix some markup and small factual glitches found by M. Markert.
........
r74260 | georg.brandl | 2009-07-29 13:15:20 -0400 (Wed, 29 Jul 2009) | 1 line
Fix a few markup glitches.
........
r74261 | georg.brandl | 2009-07-29 13:50:25 -0400 (Wed, 29 Jul 2009) | 1 line
Rewrite the section about classes a bit; mostly tidbits, and a larger update to the section about "private" variables to reflect the Pythonic consensus better.
........
2009-07-30 03:54:39 +08:00
|
|
|
are referred to by using the name of the argument. ::
|
2008-05-26 09:03:56 +08:00
|
|
|
|
2008-07-27 06:27:04 +08:00
|
|
|
>>> print('This {food} is {adjective}.'.format(
|
|
|
|
... food='spam', adjective='absolutely horrible'))
|
2008-05-26 09:03:56 +08:00
|
|
|
This spam is absolutely horrible.
|
|
|
|
|
|
|
|
Positional and keyword arguments can be arbitrarily combined::
|
|
|
|
|
2008-07-27 06:27:04 +08:00
|
|
|
>>> print('The story of {0}, {1}, and {other}.'.format('Bill', 'Manfred',
|
|
|
|
other='Georg'))
|
2008-05-26 09:03:56 +08:00
|
|
|
The story of Bill, Manfred, and Georg.
|
|
|
|
|
2009-09-01 15:42:40 +08:00
|
|
|
``'!a'`` (apply :func:`ascii`), ``'!s'`` (apply :func:`str`) and ``'!r'``
|
|
|
|
(apply :func:`repr`) can be used to convert the value before it is formatted::
|
|
|
|
|
|
|
|
>>> import math
|
|
|
|
>>> print('The value of PI is approximately {}.'.format(math.pi))
|
|
|
|
The value of PI is approximately 3.14159265359.
|
|
|
|
>>> print('The value of PI is approximately {!r}.'.format(math.pi))
|
|
|
|
The value of PI is approximately 3.141592653589793.
|
|
|
|
|
Merged revisions 74075,74187,74197,74201,74216,74225 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r74075 | georg.brandl | 2009-07-18 05:06:31 -0400 (Sat, 18 Jul 2009) | 1 line
#6505: fix typos.
........
r74187 | benjamin.peterson | 2009-07-23 10:19:08 -0400 (Thu, 23 Jul 2009) | 1 line
use bools for autoraise
........
r74197 | benjamin.peterson | 2009-07-24 22:03:48 -0400 (Fri, 24 Jul 2009) | 1 line
clarify
........
r74201 | amaury.forgeotdarc | 2009-07-25 12:22:06 -0400 (Sat, 25 Jul 2009) | 2 lines
Better name a variable: 'buf' seems to imply a mutable buffer.
........
r74216 | michael.foord | 2009-07-26 17:12:14 -0400 (Sun, 26 Jul 2009) | 1 line
Issue 6581. Michael Foord
........
r74225 | kurt.kaiser | 2009-07-27 12:09:28 -0400 (Mon, 27 Jul 2009) | 5 lines
1. Clean workspace more thoughly before build.
2. Add url of branch we are building to 'results' webpage.
(url is now available in $repo_path, could be added to failure email.)
3. Adjust permissions to improve upload reliability.
........
2009-07-30 04:12:15 +08:00
|
|
|
An optional ``':'`` and format specifier can follow the field name. This allows
|
2008-05-26 09:03:56 +08:00
|
|
|
greater control over how the value is formatted. The following example
|
2011-02-24 08:06:16 +08:00
|
|
|
rounds Pi to three places after the decimal.
|
2007-08-15 22:28:22 +08:00
|
|
|
|
|
|
|
>>> import math
|
2008-05-26 09:03:56 +08:00
|
|
|
>>> print('The value of PI is approximately {0:.3f}.'.format(math.pi))
|
2007-08-15 22:28:22 +08:00
|
|
|
The value of PI is approximately 3.142.
|
|
|
|
|
2008-05-26 09:03:56 +08:00
|
|
|
Passing an integer after the ``':'`` will cause that field to be a minimum
|
Merged revisions 74074,74077,74111,74188,74192-74193,74200,74252-74253,74258-74261 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r74074 | georg.brandl | 2009-07-18 05:03:10 -0400 (Sat, 18 Jul 2009) | 1 line
#6513: fix example code: warning categories are classes, not instances.
........
r74077 | georg.brandl | 2009-07-18 05:43:40 -0400 (Sat, 18 Jul 2009) | 1 line
#6489: fix an ambiguity in getiterator() documentation.
........
r74111 | benjamin.peterson | 2009-07-20 09:30:10 -0400 (Mon, 20 Jul 2009) | 1 line
remove docs for deprecated -p option
........
r74188 | benjamin.peterson | 2009-07-23 10:25:31 -0400 (Thu, 23 Jul 2009) | 1 line
use bools
........
r74192 | georg.brandl | 2009-07-24 12:28:38 -0400 (Fri, 24 Jul 2009) | 1 line
Fix arg types of et#.
........
r74193 | georg.brandl | 2009-07-24 12:46:38 -0400 (Fri, 24 Jul 2009) | 1 line
Dont put "void" in signature for nullary functions.
........
r74200 | georg.brandl | 2009-07-25 09:02:15 -0400 (Sat, 25 Jul 2009) | 1 line
#6571: add index entries for more operators.
........
r74252 | georg.brandl | 2009-07-29 12:06:31 -0400 (Wed, 29 Jul 2009) | 1 line
#6593: fix link targets.
........
r74253 | georg.brandl | 2009-07-29 12:09:17 -0400 (Wed, 29 Jul 2009) | 1 line
#6591: add reference to ioctl in fcntl module for platforms other than Windows.
........
r74258 | georg.brandl | 2009-07-29 12:57:05 -0400 (Wed, 29 Jul 2009) | 1 line
Add a link to readline, and mention IPython and bpython.
........
r74259 | georg.brandl | 2009-07-29 13:07:21 -0400 (Wed, 29 Jul 2009) | 1 line
Fix some markup and small factual glitches found by M. Markert.
........
r74260 | georg.brandl | 2009-07-29 13:15:20 -0400 (Wed, 29 Jul 2009) | 1 line
Fix a few markup glitches.
........
r74261 | georg.brandl | 2009-07-29 13:50:25 -0400 (Wed, 29 Jul 2009) | 1 line
Rewrite the section about classes a bit; mostly tidbits, and a larger update to the section about "private" variables to reflect the Pythonic consensus better.
........
2009-07-30 03:54:39 +08:00
|
|
|
number of characters wide. This is useful for making tables pretty. ::
|
2007-08-15 22:28:22 +08:00
|
|
|
|
|
|
|
>>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 7678}
|
|
|
|
>>> for name, phone in table.items():
|
2008-05-26 09:03:56 +08:00
|
|
|
... print('{0:10} ==> {1:10d}'.format(name, phone))
|
2009-01-04 05:18:54 +08:00
|
|
|
...
|
2007-08-15 22:28:22 +08:00
|
|
|
Jack ==> 4098
|
|
|
|
Dcab ==> 7678
|
|
|
|
Sjoerd ==> 4127
|
|
|
|
|
|
|
|
If you have a really long format string that you don't want to split up, it
|
|
|
|
would be nice if you could reference the variables to be formatted by name
|
2008-05-26 09:03:56 +08:00
|
|
|
instead of by position. This can be done by simply passing the dict and using
|
|
|
|
square brackets ``'[]'`` to access the keys ::
|
2007-08-15 22:28:22 +08:00
|
|
|
|
|
|
|
>>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 8637678}
|
2008-07-27 06:27:04 +08:00
|
|
|
>>> print('Jack: {0[Jack]:d}; Sjoerd: {0[Sjoerd]:d}; '
|
|
|
|
'Dcab: {0[Dcab]:d}'.format(table))
|
2008-05-26 09:03:56 +08:00
|
|
|
Jack: 4098; Sjoerd: 4127; Dcab: 8637678
|
|
|
|
|
|
|
|
This could also be done by passing the table as keyword arguments with the '**'
|
Merged revisions 74074,74077,74111,74188,74192-74193,74200,74252-74253,74258-74261 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r74074 | georg.brandl | 2009-07-18 05:03:10 -0400 (Sat, 18 Jul 2009) | 1 line
#6513: fix example code: warning categories are classes, not instances.
........
r74077 | georg.brandl | 2009-07-18 05:43:40 -0400 (Sat, 18 Jul 2009) | 1 line
#6489: fix an ambiguity in getiterator() documentation.
........
r74111 | benjamin.peterson | 2009-07-20 09:30:10 -0400 (Mon, 20 Jul 2009) | 1 line
remove docs for deprecated -p option
........
r74188 | benjamin.peterson | 2009-07-23 10:25:31 -0400 (Thu, 23 Jul 2009) | 1 line
use bools
........
r74192 | georg.brandl | 2009-07-24 12:28:38 -0400 (Fri, 24 Jul 2009) | 1 line
Fix arg types of et#.
........
r74193 | georg.brandl | 2009-07-24 12:46:38 -0400 (Fri, 24 Jul 2009) | 1 line
Dont put "void" in signature for nullary functions.
........
r74200 | georg.brandl | 2009-07-25 09:02:15 -0400 (Sat, 25 Jul 2009) | 1 line
#6571: add index entries for more operators.
........
r74252 | georg.brandl | 2009-07-29 12:06:31 -0400 (Wed, 29 Jul 2009) | 1 line
#6593: fix link targets.
........
r74253 | georg.brandl | 2009-07-29 12:09:17 -0400 (Wed, 29 Jul 2009) | 1 line
#6591: add reference to ioctl in fcntl module for platforms other than Windows.
........
r74258 | georg.brandl | 2009-07-29 12:57:05 -0400 (Wed, 29 Jul 2009) | 1 line
Add a link to readline, and mention IPython and bpython.
........
r74259 | georg.brandl | 2009-07-29 13:07:21 -0400 (Wed, 29 Jul 2009) | 1 line
Fix some markup and small factual glitches found by M. Markert.
........
r74260 | georg.brandl | 2009-07-29 13:15:20 -0400 (Wed, 29 Jul 2009) | 1 line
Fix a few markup glitches.
........
r74261 | georg.brandl | 2009-07-29 13:50:25 -0400 (Wed, 29 Jul 2009) | 1 line
Rewrite the section about classes a bit; mostly tidbits, and a larger update to the section about "private" variables to reflect the Pythonic consensus better.
........
2009-07-30 03:54:39 +08:00
|
|
|
notation. ::
|
2008-05-26 09:03:56 +08:00
|
|
|
|
|
|
|
>>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 8637678}
|
|
|
|
>>> print('Jack: {Jack:d}; Sjoerd: {Sjoerd:d}; Dcab: {Dcab:d}'.format(**table))
|
2007-08-15 22:28:22 +08:00
|
|
|
Jack: 4098; Sjoerd: 4127; Dcab: 8637678
|
|
|
|
|
2011-03-13 08:19:57 +08:00
|
|
|
This is particularly useful in combination with the built-in function
|
|
|
|
:func:`vars`, which returns a dictionary containing all local variables.
|
2007-08-15 22:28:22 +08:00
|
|
|
|
2009-02-22 04:59:32 +08:00
|
|
|
For a complete overview of string formatting with :meth:`str.format`, see
|
2008-05-26 09:03:56 +08:00
|
|
|
:ref:`formatstrings`.
|
|
|
|
|
|
|
|
|
|
|
|
Old string formatting
|
|
|
|
---------------------
|
|
|
|
|
|
|
|
The ``%`` operator can also be used for string formatting. It interprets the
|
2010-10-06 18:11:56 +08:00
|
|
|
left argument much like a :c:func:`sprintf`\ -style format string to be applied
|
2008-05-26 09:03:56 +08:00
|
|
|
to the right argument, and returns the string resulting from this formatting
|
|
|
|
operation. For example::
|
|
|
|
|
|
|
|
>>> import math
|
2008-08-05 17:04:16 +08:00
|
|
|
>>> print('The value of PI is approximately %5.3f.' % math.pi)
|
2008-05-26 09:03:56 +08:00
|
|
|
The value of PI is approximately 3.142.
|
|
|
|
|
|
|
|
Since :meth:`str.format` is quite new, a lot of Python code still uses the ``%``
|
Merged revisions 74075,74187,74197,74201,74216,74225 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r74075 | georg.brandl | 2009-07-18 05:06:31 -0400 (Sat, 18 Jul 2009) | 1 line
#6505: fix typos.
........
r74187 | benjamin.peterson | 2009-07-23 10:19:08 -0400 (Thu, 23 Jul 2009) | 1 line
use bools for autoraise
........
r74197 | benjamin.peterson | 2009-07-24 22:03:48 -0400 (Fri, 24 Jul 2009) | 1 line
clarify
........
r74201 | amaury.forgeotdarc | 2009-07-25 12:22:06 -0400 (Sat, 25 Jul 2009) | 2 lines
Better name a variable: 'buf' seems to imply a mutable buffer.
........
r74216 | michael.foord | 2009-07-26 17:12:14 -0400 (Sun, 26 Jul 2009) | 1 line
Issue 6581. Michael Foord
........
r74225 | kurt.kaiser | 2009-07-27 12:09:28 -0400 (Mon, 27 Jul 2009) | 5 lines
1. Clean workspace more thoughly before build.
2. Add url of branch we are building to 'results' webpage.
(url is now available in $repo_path, could be added to failure email.)
3. Adjust permissions to improve upload reliability.
........
2009-07-30 04:12:15 +08:00
|
|
|
operator. However, because this old style of formatting will eventually be
|
|
|
|
removed from the language, :meth:`str.format` should generally be used.
|
2008-05-26 09:03:56 +08:00
|
|
|
|
|
|
|
More information can be found in the :ref:`old-string-formatting` section.
|
|
|
|
|
2007-08-15 22:28:22 +08:00
|
|
|
|
|
|
|
.. _tut-files:
|
|
|
|
|
|
|
|
Reading and Writing Files
|
|
|
|
=========================
|
|
|
|
|
|
|
|
.. index::
|
|
|
|
builtin: open
|
|
|
|
object: file
|
|
|
|
|
2010-09-15 19:11:28 +08:00
|
|
|
:func:`open` returns a :term:`file object`, and is most commonly used with
|
|
|
|
two arguments: ``open(filename, mode)``.
|
2007-08-15 22:28:22 +08:00
|
|
|
|
|
|
|
::
|
|
|
|
|
Merged revisions 59605-59624 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r59606 | georg.brandl | 2007-12-29 11:57:00 +0100 (Sat, 29 Dec 2007) | 2 lines
Some cleanup in the docs.
........
r59611 | martin.v.loewis | 2007-12-29 19:49:21 +0100 (Sat, 29 Dec 2007) | 2 lines
Bug #1699: Define _BSD_SOURCE only on OpenBSD.
........
r59612 | raymond.hettinger | 2007-12-29 23:09:34 +0100 (Sat, 29 Dec 2007) | 1 line
Simpler documentation for itertools.tee(). Should be backported.
........
r59613 | raymond.hettinger | 2007-12-29 23:16:24 +0100 (Sat, 29 Dec 2007) | 1 line
Improve docs for itertools.groupby(). The use of xrange(0) to create a unique object is less obvious than object().
........
r59620 | christian.heimes | 2007-12-31 15:47:07 +0100 (Mon, 31 Dec 2007) | 3 lines
Added wininst-9.0.exe executable for VS 2008
Integrated bdist_wininst into PCBuild9 directory
........
r59621 | christian.heimes | 2007-12-31 15:51:18 +0100 (Mon, 31 Dec 2007) | 1 line
Moved PCbuild directory to PC/VS7.1
........
r59622 | christian.heimes | 2007-12-31 15:59:26 +0100 (Mon, 31 Dec 2007) | 1 line
Fix paths for build bot
........
r59623 | christian.heimes | 2007-12-31 16:02:41 +0100 (Mon, 31 Dec 2007) | 1 line
Fix paths for build bot, part 2
........
r59624 | christian.heimes | 2007-12-31 16:18:55 +0100 (Mon, 31 Dec 2007) | 1 line
Renamed PCBuild9 directory to PCBuild
........
2008-01-01 00:14:33 +08:00
|
|
|
>>> f = open('/tmp/workfile', 'w')
|
2008-08-08 15:04:38 +08:00
|
|
|
|
|
|
|
.. XXX str(f) is <io.TextIOWrapper object at 0x82e8dc4>
|
|
|
|
|
2007-08-31 11:25:11 +08:00
|
|
|
>>> print(f)
|
2007-08-15 22:28:22 +08:00
|
|
|
<open file '/tmp/workfile', mode 'w' at 80a0960>
|
|
|
|
|
|
|
|
The first argument is a string containing the filename. The second argument is
|
|
|
|
another string containing a few characters describing the way in which the file
|
|
|
|
will be used. *mode* can be ``'r'`` when the file will only be read, ``'w'``
|
|
|
|
for only writing (an existing file with the same name will be erased), and
|
|
|
|
``'a'`` opens the file for appending; any data written to the file is
|
|
|
|
automatically added to the end. ``'r+'`` opens the file for both reading and
|
|
|
|
writing. The *mode* argument is optional; ``'r'`` will be assumed if it's
|
|
|
|
omitted.
|
|
|
|
|
2008-08-08 15:04:38 +08:00
|
|
|
Normally, files are opened in :dfn:`text mode`, that means, you read and write
|
|
|
|
strings from and to the file, which are encoded in a specific encoding (the
|
|
|
|
default being UTF-8). ``'b'`` appended to the mode opens the file in
|
|
|
|
:dfn:`binary mode`: now the data is read and written in the form of bytes
|
|
|
|
objects. This mode should be used for all files that don't contain text.
|
2007-09-26 09:10:12 +08:00
|
|
|
|
2008-08-08 15:04:38 +08:00
|
|
|
In text mode, the default is to convert platform-specific line endings (``\n``
|
|
|
|
on Unix, ``\r\n`` on Windows) to just ``\n`` on reading and ``\n`` back to
|
|
|
|
platform-specific line endings on writing. This behind-the-scenes modification
|
|
|
|
to file data is fine for text files, but will corrupt binary data like that in
|
|
|
|
:file:`JPEG` or :file:`EXE` files. Be very careful to use binary mode when
|
|
|
|
reading and writing such files.
|
2007-08-15 22:28:22 +08:00
|
|
|
|
|
|
|
|
|
|
|
.. _tut-filemethods:
|
|
|
|
|
|
|
|
Methods of File Objects
|
|
|
|
-----------------------
|
|
|
|
|
|
|
|
The rest of the examples in this section will assume that a file object called
|
|
|
|
``f`` has already been created.
|
|
|
|
|
|
|
|
To read a file's contents, call ``f.read(size)``, which reads some quantity of
|
2008-08-08 15:04:38 +08:00
|
|
|
data and returns it as a string or bytes object. *size* is an optional numeric
|
|
|
|
argument. When *size* is omitted or negative, the entire contents of the file
|
|
|
|
will be read and returned; it's your problem if the file is twice as large as
|
|
|
|
your machine's memory. Otherwise, at most *size* bytes are read and returned.
|
|
|
|
If the end of the file has been reached, ``f.read()`` will return an empty
|
|
|
|
string (``''``). ::
|
2007-08-15 22:28:22 +08:00
|
|
|
|
|
|
|
>>> f.read()
|
|
|
|
'This is the entire file.\n'
|
|
|
|
>>> f.read()
|
|
|
|
''
|
|
|
|
|
|
|
|
``f.readline()`` reads a single line from the file; a newline character (``\n``)
|
|
|
|
is left at the end of the string, and is only omitted on the last line of the
|
|
|
|
file if the file doesn't end in a newline. This makes the return value
|
|
|
|
unambiguous; if ``f.readline()`` returns an empty string, the end of the file
|
|
|
|
has been reached, while a blank line is represented by ``'\n'``, a string
|
2008-08-08 15:04:38 +08:00
|
|
|
containing only a single newline. ::
|
2007-08-15 22:28:22 +08:00
|
|
|
|
|
|
|
>>> f.readline()
|
|
|
|
'This is the first line of the file.\n'
|
|
|
|
>>> f.readline()
|
|
|
|
'Second line of the file\n'
|
|
|
|
>>> f.readline()
|
|
|
|
''
|
|
|
|
|
|
|
|
``f.readlines()`` returns a list containing all the lines of data in the file.
|
|
|
|
If given an optional parameter *sizehint*, it reads that many bytes from the
|
|
|
|
file and enough more to complete a line, and returns the lines from that. This
|
|
|
|
is often used to allow efficient reading of a large file by lines, but without
|
|
|
|
having to load the entire file in memory. Only complete lines will be returned.
|
|
|
|
::
|
|
|
|
|
|
|
|
>>> f.readlines()
|
|
|
|
['This is the first line of the file.\n', 'Second line of the file\n']
|
|
|
|
|
2007-09-21 02:22:40 +08:00
|
|
|
An alternative approach to reading lines is to loop over the file object. This is
|
2007-08-15 22:28:22 +08:00
|
|
|
memory efficient, fast, and leads to simpler code::
|
|
|
|
|
|
|
|
>>> for line in f:
|
2008-08-08 15:04:38 +08:00
|
|
|
... print(line, end='')
|
|
|
|
...
|
2007-08-15 22:28:22 +08:00
|
|
|
This is the first line of the file.
|
|
|
|
Second line of the file
|
|
|
|
|
|
|
|
The alternative approach is simpler but does not provide as fine-grained
|
|
|
|
control. Since the two approaches manage line buffering differently, they
|
|
|
|
should not be mixed.
|
|
|
|
|
|
|
|
``f.write(string)`` writes the contents of *string* to the file, returning
|
2008-08-08 15:04:38 +08:00
|
|
|
the number of characters written. ::
|
2007-08-15 22:28:22 +08:00
|
|
|
|
|
|
|
>>> f.write('This is a test\n')
|
2008-08-08 15:04:38 +08:00
|
|
|
15
|
2007-08-15 22:28:22 +08:00
|
|
|
|
|
|
|
To write something other than a string, it needs to be converted to a string
|
|
|
|
first::
|
|
|
|
|
|
|
|
>>> value = ('the answer', 42)
|
|
|
|
>>> s = str(value)
|
|
|
|
>>> f.write(s)
|
2008-08-08 15:04:38 +08:00
|
|
|
18
|
2007-08-15 22:28:22 +08:00
|
|
|
|
|
|
|
``f.tell()`` returns an integer giving the file object's current position in the
|
|
|
|
file, measured in bytes from the beginning of the file. To change the file
|
|
|
|
object's position, use ``f.seek(offset, from_what)``. The position is computed
|
|
|
|
from adding *offset* to a reference point; the reference point is selected by
|
|
|
|
the *from_what* argument. A *from_what* value of 0 measures from the beginning
|
|
|
|
of the file, 1 uses the current file position, and 2 uses the end of the file as
|
|
|
|
the reference point. *from_what* can be omitted and defaults to 0, using the
|
|
|
|
beginning of the file as the reference point. ::
|
|
|
|
|
2008-08-08 15:04:38 +08:00
|
|
|
>>> f = open('/tmp/workfile', 'rb+')
|
|
|
|
>>> f.write(b'0123456789abcdef')
|
|
|
|
16
|
2007-08-15 22:28:22 +08:00
|
|
|
>>> f.seek(5) # Go to the 6th byte in the file
|
2008-08-08 15:04:38 +08:00
|
|
|
5
|
2009-01-04 05:18:54 +08:00
|
|
|
>>> f.read(1)
|
2008-08-08 15:04:38 +08:00
|
|
|
b'5'
|
2007-08-15 22:28:22 +08:00
|
|
|
>>> f.seek(-3, 2) # Go to the 3rd byte before the end
|
2008-08-08 15:04:38 +08:00
|
|
|
13
|
2007-08-15 22:28:22 +08:00
|
|
|
>>> f.read(1)
|
2008-08-08 15:04:38 +08:00
|
|
|
b'd'
|
2007-08-15 22:28:22 +08:00
|
|
|
|
2008-08-08 15:04:38 +08:00
|
|
|
In text files (those opened without a ``b`` in the mode string), only seeks
|
|
|
|
relative to the beginning of the file are allowed (the exception being seeking
|
|
|
|
to the very file end with ``seek(0, 2)``).
|
2009-01-04 05:18:54 +08:00
|
|
|
|
2007-08-15 22:28:22 +08:00
|
|
|
When you're done with a file, call ``f.close()`` to close it and free up any
|
|
|
|
system resources taken up by the open file. After calling ``f.close()``,
|
|
|
|
attempts to use the file object will automatically fail. ::
|
|
|
|
|
|
|
|
>>> f.close()
|
|
|
|
>>> f.read()
|
|
|
|
Traceback (most recent call last):
|
|
|
|
File "<stdin>", line 1, in ?
|
|
|
|
ValueError: I/O operation on closed file
|
|
|
|
|
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
svn+ssh://pythondev@svn.python.org/python/trunk
........
r65012 | jesse.noller | 2008-07-16 15:24:06 +0200 (Wed, 16 Jul 2008) | 2 lines
Apply patch for issue 3090: ARCHFLAGS parsing incorrect
........
r65035 | georg.brandl | 2008-07-16 23:19:28 +0200 (Wed, 16 Jul 2008) | 2 lines
#3045: fix pydoc behavior for TEMP path with spaces.
........
r65037 | georg.brandl | 2008-07-16 23:31:41 +0200 (Wed, 16 Jul 2008) | 2 lines
#1608818: errno can get set by every call to readdir().
........
r65038 | georg.brandl | 2008-07-17 00:04:20 +0200 (Thu, 17 Jul 2008) | 2 lines
#3305: self->stream can be NULL.
........
r65039 | georg.brandl | 2008-07-17 00:09:17 +0200 (Thu, 17 Jul 2008) | 2 lines
#3345: fix docstring.
........
r65040 | georg.brandl | 2008-07-17 00:33:18 +0200 (Thu, 17 Jul 2008) | 2 lines
#3312: fix two sqlite3 crashes.
........
r65048 | georg.brandl | 2008-07-17 01:35:54 +0200 (Thu, 17 Jul 2008) | 2 lines
#3388: add a paragraph about using "with" for file objects.
........
r65057 | gregory.p.smith | 2008-07-17 05:13:05 +0200 (Thu, 17 Jul 2008) | 2 lines
news note for r63052
........
r65077 | jesse.noller | 2008-07-17 23:01:05 +0200 (Thu, 17 Jul 2008) | 3 lines
Fix issue 3395, update _debugInfo to be _debug_info
........
r65091 | ronald.oussoren | 2008-07-18 07:48:03 +0200 (Fri, 18 Jul 2008) | 2 lines
Last bit of a fix for issue3381 (addon for my patch in r65061)
........
r65092 | vinay.sajip | 2008-07-18 10:59:06 +0200 (Fri, 18 Jul 2008) | 1 line
Issue #3389: Allow resolving dotted names for handlers in logging configuration files. Thanks to Philip Jenvey for the patch.
........
r65093 | vinay.sajip | 2008-07-18 11:00:00 +0200 (Fri, 18 Jul 2008) | 1 line
Issue #3389: Allow resolving dotted names for handlers in logging configuration files. Thanks to Philip Jenvey for the patch.
........
r65094 | vinay.sajip | 2008-07-18 11:00:35 +0200 (Fri, 18 Jul 2008) | 1 line
Issue #3389: Allow resolving dotted names for handlers in logging configuration files. Thanks to Philip Jenvey for the patch.
........
r65095 | vinay.sajip | 2008-07-18 11:01:10 +0200 (Fri, 18 Jul 2008) | 1 line
Issue #3389: Allow resolving dotted names for handlers in logging configuration files. Thanks to Philip Jenvey for the patch.
........
r65097 | georg.brandl | 2008-07-18 12:20:59 +0200 (Fri, 18 Jul 2008) | 2 lines
Remove duplicate entry in __all__.
........
r65098 | georg.brandl | 2008-07-18 12:29:30 +0200 (Fri, 18 Jul 2008) | 2 lines
Correct attribute name.
........
r65099 | georg.brandl | 2008-07-18 13:15:06 +0200 (Fri, 18 Jul 2008) | 3 lines
Document the different meaning of precision for {:f} and {:g}.
Also document how inf and nan are formatted. #3404.
........
r65127 | raymond.hettinger | 2008-07-19 02:42:03 +0200 (Sat, 19 Jul 2008) | 1 line
Improve accuracy of gamma test function
........
r65128 | raymond.hettinger | 2008-07-19 02:43:00 +0200 (Sat, 19 Jul 2008) | 1 line
Add recipe to the itertools docs.
........
r65131 | georg.brandl | 2008-07-19 12:08:55 +0200 (Sat, 19 Jul 2008) | 2 lines
#3378: in case of no memory, don't leak even more memory. :)
........
r65133 | georg.brandl | 2008-07-19 14:39:10 +0200 (Sat, 19 Jul 2008) | 3 lines
#3302: fix segfaults when passing None for arguments that can't
be NULL for the C functions.
........
r65134 | georg.brandl | 2008-07-19 14:46:12 +0200 (Sat, 19 Jul 2008) | 2 lines
#3303: fix crash with invalid Py_DECREF in strcoll().
........
r65135 | georg.brandl | 2008-07-19 15:00:22 +0200 (Sat, 19 Jul 2008) | 3 lines
#3319: don't raise ZeroDivisionError if number of rounds is so
low that benchtime is zero.
........
r65136 | georg.brandl | 2008-07-19 15:09:42 +0200 (Sat, 19 Jul 2008) | 3 lines
#3323: mention that if inheriting from a class without __slots__,
the subclass will have a __dict__ available too.
........
r65139 | georg.brandl | 2008-07-19 15:48:44 +0200 (Sat, 19 Jul 2008) | 2 lines
Add ordering info for findall and finditer.
........
r65149 | raymond.hettinger | 2008-07-20 01:21:57 +0200 (Sun, 20 Jul 2008) | 1 line
Fix compress() recipe in docs to use itertools.
........
r65150 | raymond.hettinger | 2008-07-20 01:58:47 +0200 (Sun, 20 Jul 2008) | 1 line
Clean-up itertools docs and recipes.
........
r65151 | gregory.p.smith | 2008-07-20 02:22:08 +0200 (Sun, 20 Jul 2008) | 9 lines
fix issue3120 - don't truncate handles on 64-bit Windows.
This is still messy, realistically PC/_subprocess.c should never cast pointers
to python numbers and back at all.
I don't have a 64-bit windows build environment because microsoft apparently
thinks that should cost money. Time to watch the buildbots. It builds and
passes tests on 32-bit windows.
........
r65155 | georg.brandl | 2008-07-20 13:50:29 +0200 (Sun, 20 Jul 2008) | 2 lines
#926501: add info where to put the docstring.
........
r65158 | neal.norwitz | 2008-07-20 21:35:23 +0200 (Sun, 20 Jul 2008) | 1 line
Fix a couple of names in error messages that were wrong
........
r65159 | neal.norwitz | 2008-07-20 22:39:36 +0200 (Sun, 20 Jul 2008) | 1 line
Fix misspeeld method name (negative)
........
r65176 | amaury.forgeotdarc | 2008-07-21 23:36:24 +0200 (Mon, 21 Jul 2008) | 4 lines
Increment version number in NEWS file, and move items that were added after 2.6b2.
(I thought there was a script to automate this kind of updates)
........
r65177 | amaury.forgeotdarc | 2008-07-22 00:00:38 +0200 (Tue, 22 Jul 2008) | 5 lines
Issue2378: pdb would delete free variables when stepping into a class statement.
The problem was introduced by r53954, the correction is to restore the symmetry between
PyFrame_FastToLocals and PyFrame_LocalsToFast
........
r65178 | benjamin.peterson | 2008-07-22 00:05:34 +0200 (Tue, 22 Jul 2008) | 1 line
don't use assert statement
........
r65183 | ronald.oussoren | 2008-07-22 09:06:00 +0200 (Tue, 22 Jul 2008) | 2 lines
Fix buglet in fix for issue3381
........
r65184 | ronald.oussoren | 2008-07-22 09:06:33 +0200 (Tue, 22 Jul 2008) | 2 lines
Fix build issue on OSX 10.4, somehow this wasn't committed before.
........
r65187 | raymond.hettinger | 2008-07-22 20:54:02 +0200 (Tue, 22 Jul 2008) | 1 line
Remove out-of-date section on Exact/Inexact.
........
r65188 | raymond.hettinger | 2008-07-22 21:00:47 +0200 (Tue, 22 Jul 2008) | 1 line
Tuples now have both count() and index().
........
r65189 | raymond.hettinger | 2008-07-22 21:03:05 +0200 (Tue, 22 Jul 2008) | 1 line
Fix credits for math.sum()
........
r65190 | raymond.hettinger | 2008-07-22 21:18:50 +0200 (Tue, 22 Jul 2008) | 1 line
One more attribution.
........
r65192 | benjamin.peterson | 2008-07-23 01:44:37 +0200 (Wed, 23 Jul 2008) | 1 line
remove unneeded import
........
r65194 | benjamin.peterson | 2008-07-23 15:25:06 +0200 (Wed, 23 Jul 2008) | 1 line
use isinstance
........
2008-07-24 00:10:53 +08:00
|
|
|
It is good practice to use the :keyword:`with` keyword when dealing with file
|
|
|
|
objects. This has the advantage that the file is properly closed after its
|
|
|
|
suite finishes, even if an exception is raised on the way. It is also much
|
|
|
|
shorter than writing equivalent :keyword:`try`\ -\ :keyword:`finally` blocks::
|
|
|
|
|
|
|
|
>>> with open('/tmp/workfile', 'r') as f:
|
|
|
|
... read_data = f.read()
|
|
|
|
>>> f.closed
|
|
|
|
True
|
|
|
|
|
Merged revisions 74074,74077,74111,74188,74192-74193,74200,74252-74253,74258-74261 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r74074 | georg.brandl | 2009-07-18 05:03:10 -0400 (Sat, 18 Jul 2009) | 1 line
#6513: fix example code: warning categories are classes, not instances.
........
r74077 | georg.brandl | 2009-07-18 05:43:40 -0400 (Sat, 18 Jul 2009) | 1 line
#6489: fix an ambiguity in getiterator() documentation.
........
r74111 | benjamin.peterson | 2009-07-20 09:30:10 -0400 (Mon, 20 Jul 2009) | 1 line
remove docs for deprecated -p option
........
r74188 | benjamin.peterson | 2009-07-23 10:25:31 -0400 (Thu, 23 Jul 2009) | 1 line
use bools
........
r74192 | georg.brandl | 2009-07-24 12:28:38 -0400 (Fri, 24 Jul 2009) | 1 line
Fix arg types of et#.
........
r74193 | georg.brandl | 2009-07-24 12:46:38 -0400 (Fri, 24 Jul 2009) | 1 line
Dont put "void" in signature for nullary functions.
........
r74200 | georg.brandl | 2009-07-25 09:02:15 -0400 (Sat, 25 Jul 2009) | 1 line
#6571: add index entries for more operators.
........
r74252 | georg.brandl | 2009-07-29 12:06:31 -0400 (Wed, 29 Jul 2009) | 1 line
#6593: fix link targets.
........
r74253 | georg.brandl | 2009-07-29 12:09:17 -0400 (Wed, 29 Jul 2009) | 1 line
#6591: add reference to ioctl in fcntl module for platforms other than Windows.
........
r74258 | georg.brandl | 2009-07-29 12:57:05 -0400 (Wed, 29 Jul 2009) | 1 line
Add a link to readline, and mention IPython and bpython.
........
r74259 | georg.brandl | 2009-07-29 13:07:21 -0400 (Wed, 29 Jul 2009) | 1 line
Fix some markup and small factual glitches found by M. Markert.
........
r74260 | georg.brandl | 2009-07-29 13:15:20 -0400 (Wed, 29 Jul 2009) | 1 line
Fix a few markup glitches.
........
r74261 | georg.brandl | 2009-07-29 13:50:25 -0400 (Wed, 29 Jul 2009) | 1 line
Rewrite the section about classes a bit; mostly tidbits, and a larger update to the section about "private" variables to reflect the Pythonic consensus better.
........
2009-07-30 03:54:39 +08:00
|
|
|
File objects have some additional methods, such as :meth:`~file.isatty` and
|
|
|
|
:meth:`~file.truncate` which are less frequently used; consult the Library
|
|
|
|
Reference for a complete guide to file objects.
|
2007-08-15 22:28:22 +08:00
|
|
|
|
|
|
|
|
|
|
|
.. _tut-pickle:
|
|
|
|
|
|
|
|
The :mod:`pickle` Module
|
|
|
|
------------------------
|
|
|
|
|
|
|
|
.. index:: module: pickle
|
|
|
|
|
|
|
|
Strings can easily be written to and read from a file. Numbers take a bit more
|
|
|
|
effort, since the :meth:`read` method only returns strings, which will have to
|
|
|
|
be passed to a function like :func:`int`, which takes a string like ``'123'``
|
|
|
|
and returns its numeric value 123. However, when you want to save more complex
|
|
|
|
data types like lists, dictionaries, or class instances, things get a lot more
|
|
|
|
complicated.
|
|
|
|
|
|
|
|
Rather than have users be constantly writing and debugging code to save
|
|
|
|
complicated data types, Python provides a standard module called :mod:`pickle`.
|
|
|
|
This is an amazing module that can take almost any Python object (even some
|
|
|
|
forms of Python code!), and convert it to a string representation; this process
|
|
|
|
is called :dfn:`pickling`. Reconstructing the object from the string
|
|
|
|
representation is called :dfn:`unpickling`. Between pickling and unpickling,
|
|
|
|
the string representing the object may have been stored in a file or data, or
|
|
|
|
sent over a network connection to some distant machine.
|
|
|
|
|
|
|
|
If you have an object ``x``, and a file object ``f`` that's been opened for
|
|
|
|
writing, the simplest way to pickle the object takes only one line of code::
|
|
|
|
|
|
|
|
pickle.dump(x, f)
|
|
|
|
|
|
|
|
To unpickle the object again, if ``f`` is a file object which has been opened
|
|
|
|
for reading::
|
|
|
|
|
|
|
|
x = pickle.load(f)
|
|
|
|
|
|
|
|
(There are other variants of this, used when pickling many objects or when you
|
|
|
|
don't want to write the pickled data to a file; consult the complete
|
|
|
|
documentation for :mod:`pickle` in the Python Library Reference.)
|
|
|
|
|
|
|
|
:mod:`pickle` is the standard way to make Python objects which can be stored and
|
|
|
|
reused by other programs or by a future invocation of the same program; the
|
|
|
|
technical term for this is a :dfn:`persistent` object. Because :mod:`pickle` is
|
|
|
|
so widely used, many authors who write Python extensions take care to ensure
|
|
|
|
that new data types such as matrices can be properly pickled and unpickled.
|
|
|
|
|
|
|
|
|