Change the name of the new buffer_info member function to item_type_is_equivalent_to. Add comment defining "equivalent" by example.

Author: rwgk

include/pybind11/buffer_info.h

@@ -153,8 +153,14 @@ struct buffer_info {
     Py_buffer *view() const { return m_view; }
     Py_buffer *&view() { return m_view; }
 
+    /* True if the buffer item type is equivalent to `T`. */
+    // To define "equivalent" by example:
+    // `buffer_info::item_type_is_equivalent_to<int>(b)` and
+    // `buffer_info::item_type_is_equivalent_to<long>(b)` may both be true
+    // on some platforms, but `int` and `unsigned` will never be equivalent.
+    // For the ground truth, please inspect `detail::compare_buffer_info<>`.
     template <typename T>
-    static bool compare(const buffer_info &b) {
+    static bool item_type_is_equivalent_to(const buffer_info &b) {
         return detail::compare_buffer_info<T>::compare(b);
     }
 

tests/test_buffers.cpp

@@ -16,16 +16,16 @@
 TEST_SUBMODULE(buffers, m) {
     m.attr("long_double_and_double_have_same_size") = (sizeof(long double) == sizeof(double));
 
-    m.def("format_descriptor_format_buffer_info_compare",
+    m.def("format_descriptor_format_buffer_info_equiv",
           [](const std::string &cpp_name, const py::buffer &buffer) {
               // https://google.github.io/styleguide/cppguide.html#Static_and_Global_Variables
               static auto *format_table = new std::map<std::string, std::string>;
-              static auto *compare_table
+              static auto *equiv_table
                   = new std::map<std::string, bool (*)(const py::buffer_info &)>;
               if (format_table->empty()) {
 #define PYBIND11_ASSIGN_HELPER(...)                                                               \
     (*format_table)[#__VA_ARGS__] = py::format_descriptor<__VA_ARGS__>::format();                 \
-    (*compare_table)[#__VA_ARGS__] = py::buffer_info::compare<__VA_ARGS__>;
+    (*equiv_table)[#__VA_ARGS__] = py::buffer_info::item_type_is_equivalent_to<__VA_ARGS__>;
                   PYBIND11_ASSIGN_HELPER(PyObject *)
                   PYBIND11_ASSIGN_HELPER(bool)
                   PYBIND11_ASSIGN_HELPER(std::int8_t)
@@ -45,7 +45,7 @@ TEST_SUBMODULE(buffers, m) {
 #undef PYBIND11_ASSIGN_HELPER
               }
               return std::pair<std::string, bool>((*format_table)[cpp_name],
-                                                  (*compare_table)[cpp_name](buffer.request()));
+                                                  (*equiv_table)[cpp_name](buffer.request()));
           });
 
     // test_from_python / test_to_python:

tests/test_buffers.py

@@ -49,7 +49,7 @@
 
 
 @pytest.mark.parametrize(("cpp_name", "np_dtype"), CPP_NAME_NP_DTYPE_TABLE)
-def test_format_descriptor_format_buffer_info_compare(cpp_name, np_dtype):
+def test_format_descriptor_format_buffer_info_equiv(cpp_name, np_dtype):
     if np_dtype is None:
         pytest.skip(
             f"cpp_name=`{cpp_name}`: `long double` and `double` have same size."
@@ -58,7 +58,7 @@ def test_format_descriptor_format_buffer_info_compare(cpp_name, np_dtype):
         pytest.skip(f"np.{np_dtype} does not exist.")
     np_array = np.array([], dtype=np_dtype)
     for other_cpp_name, expected_format in CPP_NAME_FORMAT_TABLE:
-        format, np_array_is_matching = m.format_descriptor_format_buffer_info_compare(
+        format, np_array_is_matching = m.format_descriptor_format_buffer_info_equiv(
             other_cpp_name, np_array
         )
         assert format == expected_format