mirror of
https://github.com/python/cpython.git
synced 2026-10-28 18:35:21 +08:00
137 lines
5.2 KiB
ReStructuredText
137 lines
5.2 KiB
ReStructuredText
.. highlight:: c
|
|
|
|
.. _marshalling-utils:
|
|
|
|
Data marshalling support
|
|
========================
|
|
|
|
These routines allow C code to work with serialized objects using the same
|
|
data format as the :mod:`marshal` module. There are functions to write data
|
|
into the serialization format, and additional functions that can be used to
|
|
read the data back. Files used to store marshalled data must be opened in
|
|
binary mode.
|
|
|
|
Numeric values are stored with the least significant byte first.
|
|
|
|
The module supports several versions of the data format; see
|
|
the :py:mod:`Python module documentation <marshal>` for details.
|
|
|
|
The following exceptions can be raised by these functions:
|
|
:exc:`ValueError` if the value cannot be marshalled,
|
|
:exc:`ValueError` or :exc:`TypeError` if the data is malformed,
|
|
:exc:`EOFError` if the end of the data is reached before the value is complete,
|
|
:exc:`OSError` if reading from or writing to a :c:expr:`FILE*` fails,
|
|
:exc:`KeyboardInterrupt` if reading or writing is interrupted by a signal,
|
|
and :exc:`MemoryError` if memory allocation fails.
|
|
|
|
.. versionchanged:: 3.16
|
|
Previously, in functions taking a :c:expr:`FILE*`,
|
|
the reading functions raised :exc:`EOFError`
|
|
instead of :exc:`OSError` and :exc:`KeyboardInterrupt`,
|
|
and the writing functions ignored I/O errors and interruptions.
|
|
|
|
.. c:macro:: Py_MARSHAL_VERSION
|
|
|
|
The current format version. See :py:data:`marshal.version`.
|
|
|
|
.. c:function:: void PyMarshal_WriteLongToFile(long value, FILE *file, int version)
|
|
|
|
Marshal a :c:expr:`long` integer, *value*, to *file*. This will only write
|
|
the least-significant 32 bits of *value*; regardless of the size of the
|
|
native :c:expr:`long` type. *version* indicates the file format.
|
|
|
|
This function can fail, in which case it sets the error indicator.
|
|
Use :c:func:`PyErr_Occurred` to check for that.
|
|
|
|
.. note::
|
|
|
|
In Python 3.15 and earlier, this function does not set the error
|
|
indicator if writing to *file* fails.
|
|
The same caveat applies as for :c:func:`PyMarshal_WriteObjectToFile`.
|
|
|
|
.. c:function:: void PyMarshal_WriteObjectToFile(PyObject *value, FILE *file, int version)
|
|
|
|
Marshal a Python object, *value*, to *file*.
|
|
*version* indicates the file format.
|
|
|
|
The marshalled representation of *value* is built in memory
|
|
and then written to *file*.
|
|
Nothing is written if *value* cannot be marshalled.
|
|
|
|
This function can fail, in which case it sets the error indicator.
|
|
Use :c:func:`PyErr_Occurred` to check for that.
|
|
|
|
.. note::
|
|
|
|
In Python 3.15 and earlier, this function can write only part of the
|
|
data to *file* and return without setting the error indicator, for
|
|
example if *value* contains an object which cannot be marshalled or
|
|
if writing to *file* fails (see :gh:`155907`).
|
|
Code which has to support these versions cannot rely on
|
|
:c:func:`PyErr_Occurred` alone to know that all the data was written.
|
|
It can use :c:func:`PyMarshal_WriteObjectToString` and write the
|
|
result itself, or validate what was written.
|
|
|
|
.. versionchanged:: 3.16
|
|
Previously, the data was written to *file* as it was produced,
|
|
using a buffer of constant size,
|
|
and incomplete data was written if *value* could not be marshalled.
|
|
|
|
.. c:function:: PyObject* PyMarshal_WriteObjectToString(PyObject *value, int version)
|
|
|
|
Return a bytes object containing the marshalled representation of *value*.
|
|
*version* indicates the file format.
|
|
|
|
On error, raises an exception and returns ``NULL``.
|
|
|
|
|
|
The following functions allow marshalled values to be read back in.
|
|
|
|
|
|
.. c:function:: long PyMarshal_ReadLongFromFile(FILE *file)
|
|
|
|
Return a C :c:expr:`long` from the data stream in a :c:expr:`FILE*` opened
|
|
for reading. Only a 32-bit value can be read in using this function,
|
|
regardless of the native size of :c:expr:`long`.
|
|
|
|
On error, raises an exception and returns ``-1``.
|
|
|
|
|
|
.. c:function:: int PyMarshal_ReadShortFromFile(FILE *file)
|
|
|
|
Return a C :c:expr:`short` from the data stream in a :c:expr:`FILE*` opened
|
|
for reading. Only a 16-bit value can be read in using this function,
|
|
regardless of the native size of :c:expr:`short`.
|
|
|
|
On error, raises an exception and returns ``-1``.
|
|
|
|
|
|
.. c:function:: PyObject* PyMarshal_ReadObjectFromFile(FILE *file)
|
|
|
|
Return a Python object from the data stream in a :c:expr:`FILE*` opened for
|
|
reading.
|
|
|
|
On error, raises an exception and returns ``NULL``.
|
|
|
|
|
|
.. c:function:: PyObject* PyMarshal_ReadLastObjectFromFile(FILE *file)
|
|
|
|
Return a Python object from the data stream in a :c:expr:`FILE*` opened for
|
|
reading. Unlike :c:func:`PyMarshal_ReadObjectFromFile`, this function
|
|
assumes that no further objects will be read from the file, allowing it to
|
|
aggressively load file data into memory so that the de-serialization can
|
|
operate from data in memory rather than reading a byte at a time from the
|
|
file. Only use this variant if you are certain that you won't be reading
|
|
anything else from the file.
|
|
|
|
On error, raises an exception and returns ``NULL``.
|
|
|
|
|
|
.. c:function:: PyObject* PyMarshal_ReadObjectFromString(const char *data, Py_ssize_t len)
|
|
|
|
Return a Python object from the data stream in a byte buffer
|
|
containing *len* bytes pointed to by *data*.
|
|
|
|
On error, raises an exception and returns ``NULL``.
|
|
|