[WIP] gh-106592: Add PyResource API

Doc/c-api/abstract.rst

@@ -24,3 +24,4 @@ but whose items have not been set to some non-\ ``NULL`` value yet.
    mapping.rst
    iter.rst
    buffer.rst
+   resource.rst

Doc/c-api/bytes.rst

@@ -151,6 +151,13 @@ called with a non-bytes parameter.
    Similar to :c:func:`PyBytes_AsString`, but without error checking.
 
 
+.. c:function:: char* PyBytes_AsStringRes(PyObject *o, PyResource *res)
+
+   Similar to :c:func:`PyBytes_AsString`, but the returning string remains
+   valid until :c:func:`PyResource_Close(res) <PyResource_Close>` is called.
+
+   .. versionadded:: 3.13
+
 .. c:function:: int PyBytes_AsStringAndSize(PyObject *obj, char **buffer, Py_ssize_t *length)
 
    Return the null-terminated contents of the object *obj*

Doc/c-api/resource.rst

@@ -0,0 +1,25 @@
+.. highlight:: c
+
+PyResource
+==========
+
+.. versionadded:: 3.13
+
+API using a callback function to close a resource.
+
+
+.. c:type:: PyResource
+
+   .. c:member:: void (*close_func) (void *data)
+
+      Callback function called by :c:func:`PyResource_Close`.
+
+   .. c:member:: void *data
+
+      Argument passed to :c:member:`close_func` by :c:func:`PyResource_Close`.
+
+
+.. c:function:: void PyResource_Close(PyResource *res)
+
+   Close a resource: call :c:member:`PyResource.close_func` with
+   :c:member:`PyResource.data`.

Doc/whatsnew/3.13.rst

@@ -802,6 +802,12 @@ New Features
   not needed.
   (Contributed by Victor Stinner in :gh:`106004`.)
 
+* Added the :c:func:`PyResource_Close` function.
+  (Contributed by Victor Stinner in :gh:`106592`.)
+
+* Added the :c:func:`PyBytes_AsStringRes` function.
+  (Contributed by Victor Stinner in :gh:`106592`.)
+
 Porting to Python 3.13
 ----------------------
 

Include/Python.h

@@ -39,6 +39,7 @@
 #include "pymacro.h"
 #include "pymath.h"
 #include "pymem.h"
+#include "pyresource.h"
 #include "pytypedefs.h"
 #include "pybuffer.h"
 #include "object.h"

Include/bytesobject.h

@@ -39,7 +39,8 @@ PyAPI_FUNC(PyObject *) PyBytes_FromFormatV(const char*, va_list)
 PyAPI_FUNC(PyObject *) PyBytes_FromFormat(const char*, ...)
                                 Py_GCC_ATTRIBUTE((format(printf, 1, 2)));
 PyAPI_FUNC(Py_ssize_t) PyBytes_Size(PyObject *);
-PyAPI_FUNC(char *) PyBytes_AsString(PyObject *);
+PyAPI_FUNC(char*) PyBytes_AsString(PyObject *op);
+PyAPI_FUNC(const char*) PyBytes_AsStringRes(PyObject *op, PyResource *res);
 PyAPI_FUNC(PyObject *) PyBytes_Repr(PyObject *, int);
 PyAPI_FUNC(void) PyBytes_Concat(PyObject **, PyObject *);
 PyAPI_FUNC(void) PyBytes_ConcatAndDel(PyObject **, PyObject *);

Include/pyresource.h

@@ -0,0 +1,21 @@
+#ifndef Py_RESOURCE_H
+#define Py_RESOURCE_H
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef struct {
+    void (*close_func) (void *data);
+    void *data;
+} PyResource;
+
+PyAPI_FUNC(void) PyResource_Close(PyResource *res);
+
+#ifdef Py_BUILD_CORE
+extern void _PyResource_DECREF(void *data);
+#endif
+
+#ifdef __cplusplus
+}
+#endif
+#endif  // !Py_RESOURCE_H

Makefile.pre.in

@@ -1658,6 +1658,7 @@ PYTHON_HEADERS= \
 		$(srcdir)/Include/pymath.h \
 		$(srcdir)/Include/pymem.h \
 		$(srcdir)/Include/pyport.h \
+		$(srcdir)/Include/pyresource.h \
 		$(srcdir)/Include/pystate.h \
 		$(srcdir)/Include/pystats.h \
 		$(srcdir)/Include/pystrcmp.h \

Misc/NEWS.d/next/C API/2023-07-24-22-30-00.gh-issue-106592.0UN_B6.rst

@@ -0,0 +1 @@
+Added the :c:func:`PyResource_Close` function. Patch by Victor Stinner.

Misc/NEWS.d/next/C API/2023-07-24-22-30-22.gh-issue-106592.V8PaNO.rst

@@ -0,0 +1 @@
+Added the :c:func:`PyBytes_AsStringRes` function. Patch by Victor Stinner.

Misc/stable_abi.toml

@@ -2450,3 +2450,10 @@
     added = '3.13'
 [function.PyDict_GetItemStringRef]
     added = '3.13'
+[struct.PyResource]
+    added = '3.13'
+    struct_abi_kind = 'full-abi'
+[function.PyResource_Close]
+    added = '3.13'
+[function.PyBytes_AsStringRes]
+    added = '3.13'

Modules/_testcapimodule.c

@@ -3654,6 +3654,33 @@ test_dict_capi(PyObject *Py_UNUSED(module), PyObject *Py_UNUSED(args))
 }
 
 
+static PyObject *
+test_resource_capi(PyObject *Py_UNUSED(module), PyObject *Py_UNUSED(args))
+{
+    const char *src = "test_resource_capi";
+    PyObject *bytes = PyBytes_FromString(src);
+    if (bytes == NULL) {
+        return NULL;
+    }
+
+    // test PyBytes_AsStringRes()
+    PyResource res;
+    const char *str = PyBytes_AsStringRes(bytes, &res);
+    // delete the bytes object, the resource keeps a strong reference to it
+    Py_CLEAR(bytes);
+
+    // test PyResource_Close()
+    assert(memcmp(str, src, strlen(src)) == 0);
+    PyResource_Close(&res);
+
+    // test PyResource_Close() with NULL callback: must not crash
+    PyResource res2 = {.close_func = NULL, .data = NULL};
+    PyResource_Close(&res2);
+
+    Py_RETURN_NONE;
+}
+
+
 static PyMethodDef TestMethods[] = {
     {"set_errno",               set_errno,                       METH_VARARGS},
     {"test_config",             test_config,                     METH_NOARGS},
@@ -3800,6 +3827,7 @@ static PyMethodDef TestMethods[] = {
     {"check_pyimport_addmodule", check_pyimport_addmodule, METH_VARARGS},
     {"test_weakref_capi", test_weakref_capi, METH_NOARGS},
     {"test_dict_capi", test_dict_capi, METH_NOARGS},
+    {"test_resource_capi", test_resource_capi, METH_NOARGS},
     {NULL, NULL} /* sentinel */
 };
 

Objects/bytesobject.c

@@ -1209,7 +1209,7 @@ PyBytes_Size(PyObject *op)
     return Py_SIZE(op);
 }
 
-char *
+char*
 PyBytes_AsString(PyObject *op)
 {
     if (!PyBytes_Check(op)) {
@@ -1220,6 +1220,19 @@ PyBytes_AsString(PyObject *op)
     return ((PyBytesObject *)op)->ob_sval;
 }
 
+const char*
+PyBytes_AsStringRes(PyObject *op, PyResource *res)
+{
+    if (!PyBytes_Check(op)) {
+        PyErr_Format(PyExc_TypeError,
+             "expected bytes, %.200s found", Py_TYPE(op)->tp_name);
+        return NULL;
+    }
+    res->close_func = _PyResource_DECREF;
+    res->data = Py_NewRef(op);
+    return ((PyBytesObject *)op)->ob_sval;
+}
+
 int
 PyBytes_AsStringAndSize(PyObject *obj,
                          char **s,

Objects/object.c

@@ -2689,6 +2689,22 @@ int Py_IsFalse(PyObject *x)
     return Py_Is(x, Py_False);
 }
 
+void _PyResource_DECREF(void *data)
+{
+    PyObject *obj = _PyObject_CAST(data);
+    Py_DECREF(obj);
+}
+
+void PyResource_Close(PyResource *res)
+{
+    if (res->close_func == NULL) {
+        return;
+    }
+    res->close_func(res->data);
+    res->close_func = NULL;
+    res->data = NULL;
+}
+
 #ifdef __cplusplus
 }
 #endif

PCbuild/pythoncore.vcxproj

@@ -308,6 +308,7 @@
     <ClInclude Include="..\Include\pymath.h" />
     <ClInclude Include="..\Include\pymem.h" />
     <ClInclude Include="..\Include\pyport.h" />
+    <ClInclude Include="..\Include\pyresource.h" />
     <ClInclude Include="..\Include\pystate.h" />
     <ClInclude Include="..\Include\pystats.h" />
     <ClInclude Include="..\Include\pystrcmp.h" />

PCbuild/pythoncore.vcxproj.filters

@@ -171,6 +171,9 @@
     <ClInclude Include="..\Include\pyport.h">
       <Filter>Include</Filter>
     </ClInclude>
+    <ClInclude Include="..\Include\pyresource.h">
+      <Filter>Include</Filter>
+    </ClInclude>
     <ClInclude Include="..\Include\pystate.h">
       <Filter>Include</Filter>
     </ClInclude>