pickle --- Python object serialization — Dokumentasi Python 3.15.2
Navigasi index modul | berikut | sebelum | Python » 3.15.2 documentation » The Python standard library » Persistensi Data » pickle --- Python object serialization | Tema | pickle --- Python object serialization ¶ Source code: Lib/pickle.py The pickle module implements binary protocols for serializing and de-serializing a Python object structure. "Pickling" is the process whereby a Python object hierarchy is converted into a byte stream, and "unpickling" is the inverse operation, whereby a byte stream (from a binary file or bytes-like object ) is converted back into an object hierarchy.
Pickling (and unpickling) is alternatively known as "serialization", "marshalling," [ 1 ] or "flattening"; however, to avoid confusion, the terms used here are "pickling" and "unpickling". Peringatan The pickle module is not secure . Only unpickle data you trust. It is possible to construct malicious pickle data which will execute arbitrary code during unpickling . Never unpickle data that could have come from an untrusted source, or that could have been tampered with.
Consider signing data with hmac if you need to ensure that it has not been tampered with. Safer serialization formats such as json may be more appropriate if you are processing untrusted data. See Comparison with json . Relationship to other Python modules ¶ Comparison with marshal ¶ Python has a more primitive serialization module called marshal , but in general pickle should always be the preferred way to serialize Python objects. marshal exists primarily to support Python's .pyc files.
The pickle module differs from marshal in several significant ways: marshal cannot be used to serialize user-defined classes and their instances. pickle can save and restore class instances transparently, however the class definition must be importable and live in the same module as when the object was pickled. The marshal serialization format is not guaranteed to be portable across Python versions. Because its primary job in life is to support .pyc files, the Python implementers reserve the right to change the serialization format in non-backwards compatible ways should the need arise.
The pickle serialization format is guaranteed to be backwards compatible across Python releases provided a compatible pickle protocol is chosen and pickling and unpickling code deals with Python 2 to Python 3 type differences if your data is crossing that unique breaking change language boundary. Comparison with json ¶ There are fundamental differences between the pickle protocols and JSON (JavaScript Object Notation) : JSON is a text serialization format (it outputs unicode text, although most of the time it is then encoded to utf-8 ), while pickle is a binary serialization format; JSON is human-readable, while pickle is not; JSON is interoperable and widely used outside of the Python ecosystem, while pickle is Python-specific; JSON, by default, can only represent a subset of the Python built-in types, and no custom classes; pickle can represent an extremely large number of Python types (many of them automatically, by clever usage of Python's introspection facilities; complex cases can be tackled by implementing specific object APIs ); Unlike pickle, deserializing untrusted JSON does not in itself create an arbitrary code execution vulnerability.
Lihat juga The json module: a standard library module allowing JSON serialization and deserialization. Data stream format ¶ The data format used by pickle is Python-specific. This has the advantage that there are no restrictions imposed by external standards such as JSON (which can't represent pointer sharing); however it means that non-Python programs may not be able to reconstruct pickled Python objects. By default, the pickle data format uses a relatively compact binary representation.
If you need optimal size characteristics, you can efficiently compress pickled data. The module pickletools contains tools for analyzing data streams generated by pickle . pickletools source code has extensive comments about opcodes used by pickle protocols. There are currently 6 different protocols which can be used for pickling. The higher the protocol used, the more recent the version of Python needed to read the pickle produced.
Protocol version 0 is the original "human-readable" protocol and is backwards compatible with earlier versions of Python. Protocol version 1 is an old binary format which is also compatible with earlier versions of Python. Protocol version 2 was introduced in Python 2.3. It provides much more efficient pickling of new-style classes . Refer to PEP 307 for information about improvements brought by protocol 2. Protocol version 3 was added in Python 3.0.
It has explicit support for bytes objects and cannot be unpickled by Python 2.x. This was the default protocol in Python 3.0--3.7. Protocol version 4 was added in Python 3.4. It adds support for very large objects, pickling more kinds of objects, and some data format optimizations. This was the default protocol in Python 3.8--3.13. Refer to PEP 3154 for information about improvements brought by protocol 4. Protocol version 5 was added in Python 3.8.
It adds support for out-of-band data and speedup for in-band data. It is the default protocol starting with Python 3.14. Refer to PEP 574 for information about improvements brought by protocol 5. Catatan Serialization is a more primitive notion than persistence; although pickle reads and writes file objects, it does not handle the issue of naming persistent objects, nor the (even more complicated) issue of concurrent access to persistent objects.
The pickle module can transform a complex object into a byte stream and it can transform the byte stream into an object with the same internal structure. Perhaps the most obvious thing to do with these byte streams is to write them onto a file, but it is also conceivable to send them across a network or store them in a database. The shelve module provides a simple interface to pickle and unpickle objects on DBM-style database files.
Module Interface ¶ To serialize an object hierarchy, you simply call the dumps() function. Similarly, to de-serialize a data stream, you call the loads() function. However, if you want more control over serialization and de-serialization, you can create a Pickler or an Unpickler object, respectively. The pickle module provides the following constants: pickle. HIGHEST_PROTOCOL ¶ An integer, the highest protocol version available.
This value can be passed as a protocol value to functions dump() and dumps() as well as the Pickler constructor. pickle. DEFAULT_PROTOCOL ¶ An integer, the default protocol version used for pickling. May be less than HIGHEST_PROTOCOL . Currently the default protocol is 5, introduced in Python 3.8 and incompatible with previous versions. This version introduces support for out-of-band buffers, where PEP 3118 -compatible data can be transmitted separately from the main pickle stream.
Berubah pada versi 3.0: The default protocol is 3. Berubah pada versi 3.8: The default protocol is 4. Berubah pada versi 3.14: The default protocol is 5. The pickle module provides the following functions to make the pickling process more convenient: pickle. dump ( obj , file , protocol = None , * , fix_imports = True , buffer_callback = None ) ¶ Write the pickled representation of the object obj to the open file object file .
This is equivalent to Pickler(file, protocol).dump(obj) . Arguments file , protocol , fix_imports and buffer_callback have the same meaning as in the Pickler constructor. Berubah pada versi 3.8: The buffer_callback argument was added. pickle. dumps ( obj , protocol = None , * , fix_imports = True , buffer_callback = None ) ¶ Return the pickled representation of the object obj as a bytes object, instead of writing it to a file.
Arguments protocol , fix_imports and buffer_callback have the same meaning as in the Pickler constructor. Berubah pada versi 3.8: The buffer_callback argum
The rest of this page is on the live site.