https://github.com/python/cpython/commit/b3714a5fb7a3aadd72134ee0710b22519c1df09a
commit: b3714a5fb7a3aadd72134ee0710b22519c1df09a
branch: main
author: Gregory P. Smith <[email protected]>
committer: gpshead <[email protected]>
date: 2026-10-11T21:51:20Z
summary:
gh-159185: Document that PyMarshal_WriteObjectToFile can silently truncate
before 3.16 (GH-159201)
gh-159185: Document that the PyMarshal file writers can fail silently before
3.16
In Python 3.15 and earlier, PyMarshal_WriteObjectToFile() ignores most
marshalling errors and all I/O errors: it returns without setting the
error indicator after writing only part of the data.
PyMarshal_WriteLongToFile() ignores I/O errors in the same way. That
was fixed in 3.16 by gh-155907, which is not backported. Tell the users
of the older versions so that they can check what was written.
files:
M Doc/c-api/marshal.rst
diff --git a/Doc/c-api/marshal.rst b/Doc/c-api/marshal.rst
index 5bf4757f8ae158..43fc0f2742d5d7 100644
--- a/Doc/c-api/marshal.rst
+++ b/Doc/c-api/marshal.rst
@@ -43,6 +43,12 @@ and :exc:`MemoryError` if memory allocation fails.
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*.
@@ -51,6 +57,17 @@ and :exc:`MemoryError` if memory allocation fails.
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.
+
.. c:function:: PyObject* PyMarshal_WriteObjectToString(PyObject *value, int
version)
Return a bytes object containing the marshalled representation of *value*.
_______________________________________________
Python-checkins mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3//lists/python-checkins.python.org
Member address: [email protected]
