Lines Matching +full:style +full:- +full:mod
1 :mod:`pickle` --- Python object serialization
17 The :mod:`pickle` module implements a fundamental, but powerful algorithm for
18 serializing and de-serializing a Python object structure. "Pickling" is the
25 This documentation describes both the :mod:`pickle` module and the
26 :mod:`cPickle` module.
30 The :mod:`pickle` module is not secure against erroneous or maliciously
36 ------------------------------------
38 The :mod:`pickle` module has an optimized cousin called the :mod:`cPickle`
39 module. As its name implies, :mod:`cPickle` is written in C, so it can be up to
40 1000 times faster than :mod:`pickle`. However it does not support subclassing
41 of the :func:`Pickler` and :func:`Unpickler` classes, because in :mod:`cPickle`
43 functionality, and can benefit from the improved performance of :mod:`cPickle`.
47 collectively describe the :mod:`pickle` and :mod:`cPickle` modules.
51 Python has a more primitive serialization module called :mod:`marshal`, but in
52 general :mod:`pickle` should always be the preferred way to serialize Python
53 objects. :mod:`marshal` exists primarily to support Python's :file:`.pyc`
56 The :mod:`pickle` module differs from :mod:`marshal` in several significant ways:
58 * The :mod:`pickle` module keeps track of the objects it has already serialized,
60 :mod:`marshal` doesn't do this.
67 serialized. :mod:`pickle` stores such objects only once, and ensures that all
71 * :mod:`marshal` cannot be used to serialize user-defined classes and their
72 instances. :mod:`pickle` can save and restore class instances transparently,
76 * The :mod:`marshal` serialization format is not guaranteed to be portable
79 serialization format in non-backwards compatible ways should the need arise.
80 The :mod:`pickle` serialization format is guaranteed to be backwards compatible
84 :mod:`pickle` reads and writes file objects, it does not handle the issue of
86 access to persistent objects. The :mod:`pickle` module can transform a complex
91 :mod:`shelve` provides a simple interface to pickle and unpickle objects on
92 DBM-style database files.
96 ------------------
102 The data format used by :mod:`pickle` is Python-specific. This has the
104 XDR (which can't represent pointer sharing); however it means that non-Python
107 By default, the :mod:`pickle` data format uses a printable ASCII representation.
110 :mod:`pickle`'s representation) is that for debugging or recovery purposes it is
122 efficient pickling of :term:`new-style class`\es.
138 -----
141 pickler's :meth:`dump` method. To de-serialize a data stream, you first create
143 :mod:`pickle` module provides the following constant:
156 For the old ASCII-based pickle protocol 0 you can use either text mode or binary
163 The :mod:`pickle` module provides the following functions to make the pickling
180 It can thus be a file object opened for writing, a :mod:`StringIO` object, or
193 reading, a :mod:`StringIO` object, or any other custom object that meets this
218 The :mod:`pickle` module also defines three exceptions:
240 The :mod:`pickle` module also exports two callables [#]_, :class:`Pickler` and
246 This takes a file-like object to which it will write a pickle data stream.
256 It can thus be an open file object, a :mod:`StringIO` object, or any other
273 pickled by reference and not by value. This method is useful when re-using
279 created by :mod:`cPickle`. In the :mod:`pickle` module, picklers have an
281 the memo for a :mod:`pickle` module pickler, you could do the following::
299 This takes a file-like object from which it will read a pickle data stream.
307 reading, a :mod:`StringIO` object, or any other custom object that meets this
328 :ref:`pickle-protocol` below for more details.
331 :class:`Unpickler` objects created with the :mod:`cPickle` module.
332 :mod:`pickle` module :class:`Unpickler`\ s do not have the :meth:`noload`
337 ----------------------------------
351 * built-in functions defined at the top level of a module
356 calling :meth:`__getstate__` is picklable (see section :ref:`pickle-protocol`
366 Note that functions (built-in and user-defined) are pickled by "fully qualified"
390 plan to have long-lived objects that will see many versions of a class, it may
395 .. _pickle-protocol:
398 -------------------
405 your objects are serialized and de-serialized. The description in this section
408 :ref:`pickle-sub` for more details.
411 .. _pickle-inst:
420 be called on unpickling, an old-style class can define a method
429 New-style types can provide a :meth:`__getnewargs__` method that is used for
433 (as it is for tuples and strings). Instances of a :term:`new-style class`
460 For :term:`new-style class`\es, if :meth:`__getstate__` returns a false
479 about --- such as an extension type --- it looks in two places for a hint of
513 :meth:`__setstate__` method as described in section :ref:`pickle-inst`. If
549 pickled, is to register the callable with the :mod:`copy_reg` module. This
551 constructors for user-defined types. Reduction functions have the same
566 For the benefit of object persistence, the :mod:`pickle` module supports the
570 the :mod:`pickle` module; it will delegate this resolution to user defined
637 In the :mod:`cPickle` module, the unpickler's :attr:`~Unpickler.persistent_load`
652 .. _pickle-sub:
655 ----------------------
664 on whether you're using :mod:`pickle` or :mod:`cPickle`. [#]_
666 In the :mod:`pickle` module, you need to derive a subclass from
681 Things are a little cleaner with :mod:`cPickle`, but not by much. To control
694 .. _pickle-example:
697 -------
700 that a self-referencing list is pickled and restored correctly. ::
717 pickle.dump(selfref_list, output, -1)
722 pickle-containing file, you should open the file in binary mode because you
760 line = line[:-1]
773 count = count - 1
790 If you want to see that :mod:`pickle` works across Python processes, start
802 Module :mod:`copy_reg`
805 Module :mod:`shelve`
806 Indexed databases of objects; uses :mod:`pickle`.
808 Module :mod:`copy`
811 Module :mod:`marshal`
812 High-performance serialization of built-in types.
815 :mod:`cPickle` --- A faster :mod:`pickle`
826 The :mod:`cPickle` module supports serialization and de-serialization of Python
828 :mod:`pickle` module. There are several differences, the most important being
831 First, :mod:`cPickle` can be up to 1000 times faster than :mod:`pickle` because
832 the former is implemented in C. Second, in the :mod:`cPickle` module the
836 benefit from the greatly improved performance of the :mod:`cPickle` module.
838 The pickle data stream produced by :mod:`pickle` and :mod:`cPickle` are
839 identical, so it is possible to use :mod:`pickle` and :mod:`cPickle`
842 There are additional minor differences in API between :mod:`cPickle` and
843 :mod:`pickle`, however for most applications, they are interchangeable. More
844 documentation is provided in the :mod:`pickle` module documentation, which
849 .. [#] Don't confuse this with the :mod:`marshal` module
851 .. [#] In the :mod:`pickle` module these callables are classes, which you could
852 subclass to customize the behavior. However, in the :mod:`cPickle` module these
855 :ref:`pickle-sub` for more details.
860 pickled again --- a reference to it is pickled and the :class:`Unpickler` will
871 the :mod:`copy` module.
874 different for :mod:`pickle` and :mod:`cPickle`. The description given here
875 works the same for both implementations. Users of the :mod:`pickle` module
886 work in either :mod:`pickle` or :mod:`cPickle`.
888 .. [#] Since the pickle data format is actually a tiny stack-oriented programming