GNU Info

(python2.1-tut.info)pickle Module

---

Prev: Methods of File Objects Up: Reading and Writing Files

---

Enter node , (file) or (file)node

The `pickle' Module
-------------------

Strings can easily be written to and read from a file. Numbers take a
bit more effort, since the `read()' method only returns strings, which
will have to be passed to a function like `string.atoi()', 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
`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 "pickling".  Reconstructing the
object from the string representation is called "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 `pickle' in the Library Reference.)

`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 "persistent" object.  Because
`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.