gh-112015: Implement ctypes.memoryview_at()

Doc/library/ctypes.rst

@@ -2109,6 +2109,23 @@ Utility functions
    .. audit-event:: ctypes.wstring_at address,size ctypes.wstring_at
 
 
+.. function:: memoryview_at(address, size, readonly=False)
+
+   This function returns a :class:`memoryview` object that references the
+   memory starting at *address* up to (but not including) *address +
+   size*.  If *readonly* is set to a truthy value then the
+   :class:`!memoryview` object is immutable.
+
+   This function is similar to :func:`string_at` with the key
+   difference of not making a copy of the specified memory. It is a
+   semantically equivalent (but more efficient) alternative to
+   ``memoryview((c_byte * size).from_address(address))``
+
+   .. audit-event:: ctypes.memoryview_at address,size,readonly ctypes.buffer_at
+
+   .. versionadded:: 3.13
+
+
 .. _ctypes-data-types:
 
 Data types

Doc/whatsnew/3.13.rst

@@ -168,6 +168,16 @@ copy
   any user classes which define the :meth:`!__replace__` method.
   (Contributed by Serhiy Storchaka in :gh:`108751`.)
 
+ctypes
+------
+
+* :func:`ctypes.memoryview_at` now exists to create a
+  :class:`memoryview` object that refers to the supplied pointer and
+  length. Works just like :func:`ctypes.string_at` except it avoids a
+  buffer copy. Useful when implementing callback functions in Python
+  that are passed dynamically-sized buffers.
+  (Contributed by Rian Hunter in :gh:`112018`.)
+
 dbm
 ---
 

Lib/ctypes/__init__.py

@@ -538,6 +538,14 @@ def wstring_at(ptr, size=-1):
         Return the string at addr."""
         return _wstring_at(ptr, size)
 
+from _ctypes import _memoryview_at_addr
+
+_memoryview_at = PYFUNCTYPE(py_object, c_void_p, c_ssize_t, c_int)(_memoryview_at_addr)
+def memoryview_at(ptr, size, readonly=False):
+    """memoryview_at(addr, size[, readonly]) -> memoryview
+
+    Return a memoryview representing the memory at addr."""
+    return _memoryview_at(ptr, size, bool(readonly))
 
 if _os.name == "nt": # COM stuff
     def DllGetClassObject(rclsid, riid, ppv):

Lib/test/test_ctypes/test_memfunctions.py

@@ -5,6 +5,7 @@
                     create_string_buffer, string_at,
                     create_unicode_buffer, wstring_at,
                     memmove, memset,
+                    memoryview_at, c_void_p,
                     c_char_p, c_byte, c_ubyte, c_wchar)
 
 
@@ -77,6 +78,25 @@ def test_wstring_at(self):
         self.assertEqual(wstring_at(a, 16), "Hello, World\0\0\0\0")
         self.assertEqual(wstring_at(a, 0), "")
 
+    def test_memoryview_at(self):
+        b = (c_byte * 10)()
+
+        foreign_ptr = cast(b, c_void_p)
+        foreign_ptr_size = len(b)
+
+        # memoryview_at() is normally used with pointers given to us
+        # by C APIs. It's an efficient way to get a buffer
+        # representing a dynamically-sized memory region without having
+        # to create an array type first.
+        v = memoryview_at(foreign_ptr, foreign_ptr_size)
+
+        # test that writes to source buffer get reflected in memoryview
+        b[:] = b"0123456789"
+        self.assertEqual(bytes(v), b"0123456789")
+
+        # test that writes to memoryview get reflected in source buffer
+        v[:] = b"9876543210"
+        self.assertEqual(bytes(b), b"9876543210")
 
 if __name__ == "__main__":
     unittest.main()

Misc/NEWS.d/next/Library/2023-11-12-21-53-40.gh-issue-112015.2WPRxE.rst

@@ -0,0 +1,5 @@
+:func:`ctypes.memoryview_at` now exists to create a
+:class:`memoryview` object that refers to the supplied pointer and
+length. Works just like :func:`ctypes.string_at` except it avoids a
+buffer copy. Useful when implementing callback functions in Python
+that are passed dynamically-sized buffers.

Modules/_ctypes/_ctypes.c

@@ -5642,6 +5642,17 @@ wstring_at(const wchar_t *ptr, int size)
     return PyUnicode_FromWideChar(ptr, ssize);
 }
 
+static PyObject *
+memoryview_at(char *ptr, Py_ssize_t size, int readonly)
+{
+    if (PySys_Audit("ctypes.memoryview_at", "nni", (Py_ssize_t)ptr, size,
+                    readonly) < 0) {
+        return NULL;
+    }
+
+    return PyMemoryView_FromMemory(ptr, size,
+                                   readonly ? PyBUF_READ : PyBUF_WRITE);
+}
 
 static struct PyModuleDef _ctypesmodule = {
     PyModuleDef_HEAD_INIT,
@@ -5777,6 +5788,7 @@ _ctypes_add_objects(PyObject *mod)
     MOD_ADD("_string_at_addr", PyLong_FromVoidPtr(string_at));
     MOD_ADD("_cast_addr", PyLong_FromVoidPtr(cast));
     MOD_ADD("_wstring_at_addr", PyLong_FromVoidPtr(wstring_at));
+    MOD_ADD("_memoryview_at_addr", PyLong_FromVoidPtr(memoryview_at));
 
 /* If RTLD_LOCAL is not defined (Windows!), set it to zero. */
 #if !HAVE_DECL_RTLD_LOCAL