💾 Archived View for tris.fyi › pydoc › pickle captured on 2023-01-29 at 03:26:16. Gemini links have been rewritten to link to archived content

View Raw

More Information

⬅️ Previous capture (2022-07-16)

🚧 View Differences

-=-=-=-=-=-=-

Back to module index

Go to module by name

pickle

Create portable serialized representations of Python objects.

See module copyreg for a mechanism for registering custom picklers.
See module pickletools source for extensive comments.

Classes:

    Pickler
    Unpickler

Functions:

    dump(object, file)
    dumps(object) -> string
    load(file) -> object
    loads(bytes) -> object

Misc variables:

    __version__
    format_version
    compatible_formats


Classes

function

Create a function object.

  code
    a code object
  globals
    the globals dictionary
  name
    a string that overrides the name from the code object
  argdefs
    a tuple that specifies the default argument values
  closure
    a tuple that supplies the bindings for free variables

PickleBuffer

Wrapper for potentially out-of-band buffers
raw(self, /)

  Return a memoryview of the raw memory underlying this buffer.
  Will raise BufferError is the buffer isn't contiguous.
release(self, /)

  Release the underlying buffer exposed by the PickleBuffer object.

PickleError

with_traceback(...)

  Exception.with_traceback(tb) --
      set self.__traceback__ to tb and return self.
args = <attribute 'args' of 'BaseException' objects>

Pickler

This takes a binary file for writing a pickle data stream.

The optional *protocol* argument tells the pickler to use the given
protocol; supported protocols are 0, 1, 2, 3, 4 and 5.  The default
protocol is 4. It was introduced in Python 3.4, and is incompatible
with previous versions.

Specifying a negative protocol version selects the highest protocol
version supported.  The higher the protocol used, the more recent the
version of Python needed to read the pickle produced.

The *file* argument must have a write() method that accepts a single
bytes argument. It can thus be a file object opened for binary
writing, an io.BytesIO instance, or any other custom object that meets
this interface.

If *fix_imports* is True and protocol is less than 3, pickle will try
to map the new Python 3 names to the old module names used in Python
2, so that the pickle data stream is readable with Python 2.

If *buffer_callback* is None (the default), buffer views are
serialized into *file* as part of the pickle stream.

If *buffer_callback* is not None, then it can be called any number
of times with a buffer view.  If the callback returns a false value
(such as None), the given buffer is out-of-band; otherwise the
buffer is serialized in-band, i.e. inside the pickle stream.

It is an error if *buffer_callback* is not None and *protocol*
is None or smaller than 5.
clear_memo(self, /)

  Clears the pickler's "memo".

  The memo is the data structure that remembers which objects the
  pickler has already seen, so that shared or recursive objects are
  pickled by reference and not by value.  This method is useful when
  re-using picklers.
dump(self, obj, /)

  Write a pickled representation of the given object to the open file.
bin = <member 'bin' of '_pickle.Pickler' objects>
dispatch_table = <member 'dispatch_table' of '_pickle.Pickler' objects>
fast = <member 'fast' of '_pickle.Pickler' objects>
memo = <attribute 'memo' of '_pickle.Pickler' objects>
persistent_id = <attribute 'persistent_id' of '_pickle.Pickler' objects>

PicklingError

with_traceback(...)

  Exception.with_traceback(tb) --
      set self.__traceback__ to tb and return self.
args = <attribute 'args' of 'BaseException' objects>

Unpickler

This takes a binary file for reading a pickle data stream.

The protocol version of the pickle is detected automatically, so no
protocol argument is needed.  Bytes past the pickled object's
representation are ignored.

The argument *file* must have two methods, a read() method that takes
an integer argument, and a readline() method that requires no
arguments.  Both methods should return bytes.  Thus *file* can be a
binary file object opened for reading, an io.BytesIO object, or any
other custom object that meets this interface.

Optional keyword arguments are *fix_imports*, *encoding* and *errors*,
which are used to control compatibility support for pickle stream
generated by Python 2.  If *fix_imports* is True, pickle will try to
map the old Python 2 names to the new names used in Python 3.  The

instances pickled by Python 2; these default to 'ASCII' and 'strict',
respectively.  The *encoding* can be 'bytes' to read these 8-bit
string instances as bytes objects.
find_class(self, module_name, global_name, /)

  Return an object from a specified module.

  If necessary, the module will be imported. Subclasses may override
  this method (e.g. to restrict unpickling of arbitrary classes and
  functions).

  This method is called whenever a class or a function object is
  needed.  Both arguments passed are str objects.
load(self, /)

  Load a pickle.

  Read a pickled object representation from the open file object given
  in the constructor, and return the reconstituted object hierarchy
  specified therein.
memo = <attribute 'memo' of '_pickle.Unpickler' objects>
persistent_load = <attribute 'persistent_load' of '_pickle.Unpickler' objects>

UnpicklingError

with_traceback(...)

  Exception.with_traceback(tb) --
      set self.__traceback__ to tb and return self.
args = <attribute 'args' of 'BaseException' objects>

islice

islice(iterable, stop) --> islice object
islice(iterable, start, stop[, step]) --> islice object

Return an iterator whose next() method returns selected values from an
iterable.  If start is specified, will skip all preceding elements;
otherwise, start defaults to zero.  Step defaults to one.  If
specified as another value, step determines how many values are
skipped between successive calls.  Works like a slice() on a list
but returns an iterator.

partial

partial(func, *args, **keywords) - new function with partial application
    of the given arguments and keywords.

args = <member 'args' of 'functools.partial' objects>
  tuple of arguments to future partial calls
func = <member 'func' of 'functools.partial' objects>
  function object to use in future partial calls
keywords = <member 'keywords' of 'functools.partial' objects>
  dictionary of keyword arguments to future partial calls

Functions

decode_long

decode_long(data)

  Decode a long from a two's complement little-endian binary string.

      >>> decode_long(b'')
      0
      >>> decode_long(b"\xff\x00")
      255
      >>> decode_long(b"\xff\x7f")
      32767
      >>> decode_long(b"\x00\xff")
      -256
      >>> decode_long(b"\x00\x80")
      -32768
      >>> decode_long(b"\x80")
      -128
      >>> decode_long(b"\x7f")
      127
    

dump

dump(obj, file, protocol=None, *, fix_imports=True, buffer_callback=None)

  Write a pickled representation of obj to the open file object file.

  This is equivalent to ``Pickler(file, protocol).dump(obj)``, but may
  be more efficient.

  The optional *protocol* argument tells the pickler to use the given
  protocol; supported protocols are 0, 1, 2, 3, 4 and 5.  The default
  protocol is 4. It was introduced in Python 3.4, and is incompatible
  with previous versions.

  Specifying a negative protocol version selects the highest protocol
  version supported.  The higher the protocol used, the more recent the
  version of Python needed to read the pickle produced.

  The *file* argument must have a write() method that accepts a single
  bytes argument.  It can thus be a file object opened for binary
  writing, an io.BytesIO instance, or any other custom object that meets
  this interface.

  If *fix_imports* is True and protocol is less than 3, pickle will try
  to map the new Python 3 names to the old module names used in Python
  2, so that the pickle data stream is readable with Python 2.

  If *buffer_callback* is None (the default), buffer views are serialized
  into *file* as part of the pickle stream.  It is an error if
  *buffer_callback* is not None and *protocol* is None or smaller than 5.

dumps

dumps(obj, protocol=None, *, fix_imports=True, buffer_callback=None)

  Return the pickled representation of the object as a bytes object.

  The optional *protocol* argument tells the pickler to use the given
  protocol; supported protocols are 0, 1, 2, 3, 4 and 5.  The default
  protocol is 4. It was introduced in Python 3.4, and is incompatible
  with previous versions.

  Specifying a negative protocol version selects the highest protocol
  version supported.  The higher the protocol used, the more recent the
  version of Python needed to read the pickle produced.

  If *fix_imports* is True and *protocol* is less than 3, pickle will
  try to map the new Python 3 names to the old module names used in
  Python 2, so that the pickle data stream is readable with Python 2.

  If *buffer_callback* is None (the default), buffer views are serialized
  into *file* as part of the pickle stream.  It is an error if
  *buffer_callback* is not None and *protocol* is None or smaller than 5.

encode_long

encode_long(x)

  Encode a long to a two's complement little-endian binary string.
      Note that 0 is a special case, returning an empty string, to save a
      byte in the LONG1 pickling context.

      >>> encode_long(0)
      b''
      >>> encode_long(255)
      b'\xff\x00'
      >>> encode_long(32767)
      b'\xff\x7f'
      >>> encode_long(-256)
      b'\x00\xff'
      >>> encode_long(-32768)
      b'\x00\x80'
      >>> encode_long(-128)
      b'\x80'
      >>> encode_long(127)
      b'\x7f'
      >>>
    

load

load(file, *, fix_imports=True, encoding='ASCII', errors='strict', buffers=())

  Read and return an object from the pickle data stored in a file.

  This is equivalent to ``Unpickler(file).load()``, but may be more
  efficient.

  The protocol version of the pickle is detected automatically, so no
  protocol argument is needed.  Bytes past the pickled object's
  representation are ignored.

  The argument *file* must have two methods, a read() method that takes
  an integer argument, and a readline() method that requires no
  arguments.  Both methods should return bytes.  Thus *file* can be a
  binary file object opened for reading, an io.BytesIO object, or any
  other custom object that meets this interface.

  Optional keyword arguments are *fix_imports*, *encoding* and *errors*,
  which are used to control compatibility support for pickle stream
  generated by Python 2.  If *fix_imports* is True, pickle will try to
  map the old Python 2 names to the new names used in Python 3.  The
  *encoding* and *errors* tell pickle how to decode 8-bit string
  instances pickled by Python 2; these default to 'ASCII' and 'strict',
  respectively.  The *encoding* can be 'bytes' to read these 8-bit
  string instances as bytes objects.

loads

loads(data, /, *, fix_imports=True, encoding='ASCII', errors='strict', buffers=())

  Read and return an object from the given pickle data.

  The protocol version of the pickle is detected automatically, so no
  protocol argument is needed.  Bytes past the pickled object's
  representation are ignored.

  Optional keyword arguments are *fix_imports*, *encoding* and *errors*,
  which are used to control compatibility support for pickle stream
  generated by Python 2.  If *fix_imports* is True, pickle will try to
  map the old Python 2 names to the new names used in Python 3.  The
  *encoding* and *errors* tell pickle how to decode 8-bit string
  instances pickled by Python 2; these default to 'ASCII' and 'strict',
  respectively.  The *encoding* can be 'bytes' to read these 8-bit
  string instances as bytes objects.

pack

pack(...)

  pack(format, v1, v2, ...) -> bytes

  Return a bytes object containing the values v1, v2, ... packed according
  to the format string.  See help(struct) for more on format strings.

unpack

unpack(format, buffer, /)

  Return a tuple containing values unpacked according to the format string.

  The buffer's size in bytes must be calcsize(format).

  See help(struct) for more on format strings.

whichmodule

whichmodule(obj, name)

  Find the module an object belong to.

Other members

ADDITEMS = b'\x90'
APPEND = b'a'
APPENDS = b'e'
BINBYTES = b'B'
BINBYTES8 = b'\x8e'
BINFLOAT = b'G'
BINGET = b'h'
BININT = b'J'
BININT1 = b'K'
BININT2 = b'M'
BINPERSID = b'Q'
BINPUT = b'q'
BINSTRING = b'T'
BINUNICODE = b'X'
BINUNICODE8 = b'\x8d'
BUILD = b'b'
BYTEARRAY8 = b'\x96'
DEFAULT_PROTOCOL = 4
DICT = b'd'
DUP = b'2'
EMPTY_DICT = b'}'
EMPTY_LIST = b']'
EMPTY_SET = b'\x8f'
EMPTY_TUPLE = b')'
EXT1 = b'\x82'
EXT2 = b'\x83'
EXT4 = b'\x84'
FALSE = b'I00\n'
FLOAT = b'F'
FRAME = b'\x95'
FROZENSET = b'\x91'
GET = b'g'
GLOBAL = b'c'
HIGHEST_PROTOCOL = 5
INST = b'i'
INT = b'I'
LIST = b'l'
LONG = b'L'
LONG1 = b'\x8a'
LONG4 = b'\x8b'
LONG_BINGET = b'j'
LONG_BINPUT = b'r'
MARK = b'('
MEMOIZE = b'\x94'
NEWFALSE = b'\x89'
NEWOBJ = b'\x81'
NEWOBJ_EX = b'\x92'
NEWTRUE = b'\x88'
NEXT_BUFFER = b'\x97'
NONE = b'N'
OBJ = b'o'
PERSID = b'P'
POP = b'0'
POP_MARK = b'1'
PROTO = b'\x80'
PUT = b'p'
PyStringMap = None
READONLY_BUFFER = b'\x98'
REDUCE = b'R'
SETITEM = b's'
SETITEMS = b'u'
SHORT_BINBYTES = b'C'
SHORT_BINSTRING = b'U'
SHORT_BINUNICODE = b'\x8c'
STACK_GLOBAL = b'\x93'
STOP = b'.'
STRING = b'S'
TRUE = b'I01\n'
TUPLE = b't'
TUPLE1 = b'\x85'
TUPLE2 = b'\x86'
TUPLE3 = b'\x87'
UNICODE = b'V'
bytes_types = (<class 'bytes'>, <class 'bytearray'>)
compatible_formats = ['1.0', '1.1', '1.2', '1.3', '2.0', '3.0', '4.0', '5.0']
dispatch_table = {<class 'complex'>: <function pickle_complex at 0x7f75e3bfed40>, <class 'types.UnionType'>: <function pickle_union at 0x7f75e3bfedd0>, <class 're.Pattern'>: <function _pickle at 0x7f75e3bfea70>}
format_version = '4.0'
maxsize = 9223372036854775807

Modules

codecs

io

re

sys