410
412
Pickling and unpickling normal class instances
411
413
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
414
single: __getinitargs__() (copy protocol)
415
single: __init__() (instance constructor)
417
When a pickled class instance is unpickled, its :meth:`__init__` method is
418
normally *not* invoked. If it is desirable that the :meth:`__init__` method be
419
called on unpickling, an old-style class can define a method
420
:meth:`__getinitargs__`, which should return a *tuple* containing the arguments
421
to be passed to the class constructor (:meth:`__init__` for example). The
422
:meth:`__getinitargs__` method is called at pickle time; the tuple it returns is
423
incorporated in the pickle for the instance.
425
.. index:: single: __getnewargs__() (copy protocol)
427
New-style types can provide a :meth:`__getnewargs__` method that is used for
428
protocol 2. Implementing this method is needed if the type establishes some
429
internal invariants when the instance is created, or if the memory allocation is
430
affected by the values passed to the :meth:`__new__` method for the type (as it
431
is for tuples and strings). Instances of a :term:`new-style class` :class:`C`
434
obj = C.__new__(C, *args)
437
where *args* is the result of calling :meth:`__getnewargs__` on the original
438
object; if there is no :meth:`__getnewargs__`, an empty tuple is assumed.
441
single: __getstate__() (copy protocol)
442
single: __setstate__() (copy protocol)
443
single: __dict__ (instance attribute)
445
Classes can further influence how their instances are pickled; if the class
446
defines the method :meth:`__getstate__`, it is called and the return state is
447
pickled as the contents for the instance, instead of the contents of the
448
instance's dictionary. If there is no :meth:`__getstate__` method, the
449
instance's :attr:`__dict__` is pickled.
451
Upon unpickling, if the class also defines the method :meth:`__setstate__`, it
452
is called with the unpickled state. [#]_ If there is no :meth:`__setstate__`
453
method, the pickled state must be a dictionary and its items are assigned to the
454
new instance's dictionary. If a class defines both :meth:`__getstate__` and
455
:meth:`__setstate__`, the state object needn't be a dictionary and these methods
456
can do what they want. [#]_
460
For :term:`new-style class`\es, if :meth:`__getstate__` returns a false
461
value, the :meth:`__setstate__` method will not be called.
415
.. method:: object.__getinitargs__()
417
When a pickled class instance is unpickled, its :meth:`__init__` method is
418
normally *not* invoked. If it is desirable that the :meth:`__init__` method
419
be called on unpickling, an old-style class can define a method
420
:meth:`__getinitargs__`, which should return a *tuple* containing the
421
arguments to be passed to the class constructor (:meth:`__init__` for
422
example). The :meth:`__getinitargs__` method is called at pickle time; the
423
tuple it returns is incorporated in the pickle for the instance.
425
.. method:: object.__getnewargs__()
427
New-style types can provide a :meth:`__getnewargs__` method that is used for
428
protocol 2. Implementing this method is needed if the type establishes some
429
internal invariants when the instance is created, or if the memory allocation
430
is affected by the values passed to the :meth:`__new__` method for the type
431
(as it is for tuples and strings). Instances of a :term:`new-style class`
432
``C`` are created using ::
434
obj = C.__new__(C, *args)
436
where *args* is the result of calling :meth:`__getnewargs__` on the original
437
object; if there is no :meth:`__getnewargs__`, an empty tuple is assumed.
439
.. method:: object.__getstate__()
441
Classes can further influence how their instances are pickled; if the class
442
defines the method :meth:`__getstate__`, it is called and the return state is
443
pickled as the contents for the instance, instead of the contents of the
444
instance's dictionary. If there is no :meth:`__getstate__` method, the
445
instance's :attr:`__dict__` is pickled.
447
.. method:: object.__setstate__()
449
Upon unpickling, if the class also defines the method :meth:`__setstate__`,
450
it is called with the unpickled state. [#]_ If there is no
451
:meth:`__setstate__` method, the pickled state must be a dictionary and its
452
items are assigned to the new instance's dictionary. If a class defines both
453
:meth:`__getstate__` and :meth:`__setstate__`, the state object needn't be a
454
dictionary and these methods can do what they want. [#]_
458
For :term:`new-style class`\es, if :meth:`__getstate__` returns a false
459
value, the :meth:`__setstate__` method will not be called.
464
462
Pickling and unpickling extension types
465
463
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
468
single: __reduce__() (pickle protocol)
469
single: __reduce_ex__() (pickle protocol)
470
single: __safe_for_unpickling__ (pickle protocol)
472
When the :class:`Pickler` encounters an object of a type it knows nothing about
473
--- such as an extension type --- it looks in two places for a hint of how to
474
pickle it. One alternative is for the object to implement a :meth:`__reduce__`
475
method. If provided, at pickling time :meth:`__reduce__` will be called with no
476
arguments, and it must return either a string or a tuple.
478
If a string is returned, it names a global variable whose contents are pickled
479
as normal. The string returned by :meth:`__reduce__` should be the object's
480
local name relative to its module; the pickle module searches the module
481
namespace to determine the object's module.
483
When a tuple is returned, it must be between two and five elements long.
484
Optional elements can either be omitted, or ``None`` can be provided as their
485
value. The contents of this tuple are pickled as normal and used to
486
reconstruct the object at unpickling time. The semantics of each element are:
488
* A callable object that will be called to create the initial version of the
489
object. The next element of the tuple will provide arguments for this callable,
490
and later elements provide additional state information that will subsequently
491
be used to fully reconstruct the pickled data.
493
In the unpickling environment this object must be either a class, a callable
494
registered as a "safe constructor" (see below), or it must have an attribute
495
:attr:`__safe_for_unpickling__` with a true value. Otherwise, an
496
:exc:`UnpicklingError` will be raised in the unpickling environment. Note that
497
as usual, the callable itself is pickled by name.
499
* A tuple of arguments for the callable object.
501
.. versionchanged:: 2.5
502
Formerly, this argument could also be ``None``.
504
* Optionally, the object's state, which will be passed to the object's
505
:meth:`__setstate__` method as described in section :ref:`pickle-inst`. If the
506
object has no :meth:`__setstate__` method, then, as above, the value must be a
507
dictionary and it will be added to the object's :attr:`__dict__`.
509
* Optionally, an iterator (and not a sequence) yielding successive list items.
510
These list items will be pickled, and appended to the object using either
511
``obj.append(item)`` or ``obj.extend(list_of_items)``. This is primarily used
512
for list subclasses, but may be used by other classes as long as they have
513
:meth:`append` and :meth:`extend` methods with the appropriate signature.
514
(Whether :meth:`append` or :meth:`extend` is used depends on which pickle
515
protocol version is used as well as the number of items to append, so both must
518
* Optionally, an iterator (not a sequence) yielding successive dictionary items,
519
which should be tuples of the form ``(key, value)``. These items will be
520
pickled and stored to the object using ``obj[key] = value``. This is primarily
521
used for dictionary subclasses, but may be used by other classes as long as they
522
implement :meth:`__setitem__`.
524
It is sometimes useful to know the protocol version when implementing
525
:meth:`__reduce__`. This can be done by implementing a method named
526
:meth:`__reduce_ex__` instead of :meth:`__reduce__`. :meth:`__reduce_ex__`, when
527
it exists, is called in preference over :meth:`__reduce__` (you may still
528
provide :meth:`__reduce__` for backwards compatibility). The
529
:meth:`__reduce_ex__` method will be called with a single integer argument, the
532
The :class:`object` class implements both :meth:`__reduce__` and
533
:meth:`__reduce_ex__`; however, if a subclass overrides :meth:`__reduce__` but
534
not :meth:`__reduce_ex__`, the :meth:`__reduce_ex__` implementation detects this
535
and calls :meth:`__reduce__`.
465
.. method:: object.__reduce__()
467
When the :class:`Pickler` encounters an object of a type it knows nothing
468
about --- such as an extension type --- it looks in two places for a hint of
469
how to pickle it. One alternative is for the object to implement a
470
:meth:`__reduce__` method. If provided, at pickling time :meth:`__reduce__`
471
will be called with no arguments, and it must return either a string or a
474
If a string is returned, it names a global variable whose contents are
475
pickled as normal. The string returned by :meth:`__reduce__` should be the
476
object's local name relative to its module; the pickle module searches the
477
module namespace to determine the object's module.
479
When a tuple is returned, it must be between two and five elements long.
480
Optional elements can either be omitted, or ``None`` can be provided as their
481
value. The contents of this tuple are pickled as normal and used to
482
reconstruct the object at unpickling time. The semantics of each element
485
* A callable object that will be called to create the initial version of the
486
object. The next element of the tuple will provide arguments for this
487
callable, and later elements provide additional state information that will
488
subsequently be used to fully reconstruct the pickled data.
490
In the unpickling environment this object must be either a class, a
491
callable registered as a "safe constructor" (see below), or it must have an
492
attribute :attr:`__safe_for_unpickling__` with a true value. Otherwise, an
493
:exc:`UnpicklingError` will be raised in the unpickling environment. Note
494
that as usual, the callable itself is pickled by name.
496
* A tuple of arguments for the callable object.
498
.. versionchanged:: 2.5
499
Formerly, this argument could also be ``None``.
501
* Optionally, the object's state, which will be passed to the object's
502
:meth:`__setstate__` method as described in section :ref:`pickle-inst`. If
503
the object has no :meth:`__setstate__` method, then, as above, the value
504
must be a dictionary and it will be added to the object's :attr:`__dict__`.
506
* Optionally, an iterator (and not a sequence) yielding successive list
507
items. These list items will be pickled, and appended to the object using
508
either ``obj.append(item)`` or ``obj.extend(list_of_items)``. This is
509
primarily used for list subclasses, but may be used by other classes as
510
long as they have :meth:`append` and :meth:`extend` methods with the
511
appropriate signature. (Whether :meth:`append` or :meth:`extend` is used
512
depends on which pickle protocol version is used as well as the number of
513
items to append, so both must be supported.)
515
* Optionally, an iterator (not a sequence) yielding successive dictionary
516
items, which should be tuples of the form ``(key, value)``. These items
517
will be pickled and stored to the object using ``obj[key] = value``. This
518
is primarily used for dictionary subclasses, but may be used by other
519
classes as long as they implement :meth:`__setitem__`.
521
.. method:: object.__reduce_ex__(protocol)
523
It is sometimes useful to know the protocol version when implementing
524
:meth:`__reduce__`. This can be done by implementing a method named
525
:meth:`__reduce_ex__` instead of :meth:`__reduce__`. :meth:`__reduce_ex__`,
526
when it exists, is called in preference over :meth:`__reduce__` (you may
527
still provide :meth:`__reduce__` for backwards compatibility). The
528
:meth:`__reduce_ex__` method will be called with a single integer argument,
529
the protocol version.
531
The :class:`object` class implements both :meth:`__reduce__` and
532
:meth:`__reduce_ex__`; however, if a subclass overrides :meth:`__reduce__`
533
but not :meth:`__reduce_ex__`, the :meth:`__reduce_ex__` implementation
534
detects this and calls :meth:`__reduce__`.
537
536
An alternative to implementing a :meth:`__reduce__` method on the object to be
538
537
pickled, is to register the callable with the :mod:`copy_reg` module. This
added
removed
Doc/library/pickle.rst
