From: Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com>
Date: Fri, 2 Jun 2023 08:28:35 +0000 (-0700)
Subject: [3.11] gh-105184: document that marshal functions can fail and need to be checked... 
X-Git-Tag: v3.11.4~9
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=8de607ab1c7605dce0efbb1a5c7148385d9176a6;p=thirdparty%2FPython%2Fcpython.git

[3.11] gh-105184: document that marshal functions can fail and need to be checked with PyErr_Occurred (GH-105185) (#105219)

gh-105184: document that marshal functions can fail and need to be checked with PyErr_Occurred (GH-105185)
(cherry picked from commit ee26ca13a129da8cf549409d0a1b2e892ff2b4ec)

Co-authored-by: Irit Katriel <1055913+iritkatriel@users.noreply.github.com>
---

diff --git a/Doc/c-api/marshal.rst b/Doc/c-api/marshal.rst
index 8e25968c6909..489f1580a414 100644
--- a/Doc/c-api/marshal.rst
+++ b/Doc/c-api/marshal.rst
@@ -25,12 +25,16 @@ unmarshalling.  Version 2 uses a binary format for floating point numbers.
    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.
 
 .. c:function:: void PyMarshal_WriteObjectToFile(PyObject *value, FILE *file, int version)
 
    Marshal a Python object, *value*, to *file*.
    *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.
 
 .. c:function:: PyObject* PyMarshal_WriteObjectToString(PyObject *value, int version)
 
diff --git a/Python/marshal.c b/Python/marshal.c
index 2690f55766c8..bf607cb8ce2d 100644
--- a/Python/marshal.c
+++ b/Python/marshal.c
@@ -624,6 +624,10 @@ w_clear_refs(WFILE *wf)
 }
 
 /* version currently has no effect for writing ints. */
+/* Note that while the documentation states that this function
+ * can error, currently it never does. Setting an exception in
+ * this function should be regarded as an API-breaking change.
+ */
 void
 PyMarshal_WriteLongToFile(long x, FILE *fp, int version)
 {