GH-45653: [Python] Scalar subclasses should implement Python protocols (#45818)

### Rationale for this change

Implement dunder methods on Scalar objects

### What changes are included in this PR?

* integer scalars implement `__int__`
* floating-point scalars implement `__float__`
* binary scalars implement [`__bytes__`](https://docs.python.org/3.13/reference/datamodel.html#object.__bytes__)
* binary scalars  implement the [buffer protocol](https://docs.python.org/3.13/reference/datamodel.html#object.__buffer__)
* we explicitly test that Struct scalars implement Sequences
* Map scalar implement mapping

### Are these changes tested?

Yes

### Are there any user-facing changes?

Yes

* GitHub Issue: #45653

Lead-authored-by: Nic Crane <thisisnic@gmail.com>
Co-authored-by: Alenka Frim <AlenkaF@users.noreply.github.com>
Co-authored-by: Antoine Pitrou <pitrou@free.fr>
Signed-off-by: Antoine Pitrou <antoine@python.org>

Author: 3 people

docs/source/python/compute.rst

@@ -63,6 +63,21 @@ Below are a few simple examples::
    >>> pc.multiply(x, y)
    <pyarrow.DoubleScalar: 72.54>
 
+If you are using a compute function which returns more than one value, results
+will be returned as a ``StructScalar``.  You can extract the individual values by
+calling the :meth:`pyarrow.StructScalar.values` method::
+
+   >>> import pyarrow as pa
+   >>> import pyarrow.compute as pc
+   >>> a = pa.array([1, 1, 2, 3])
+   >>> pc.min_max(a)
+   <pyarrow.StructScalar: [('min', 1), ('max', 3)]>
+   >>> a, b = pc.min_max(a).values()
+   >>> a
+   <pyarrow.Int64Scalar: 1>
+   >>> b
+   <pyarrow.Int64Scalar: 3>
+
 These functions can do more than just element-by-element operations.
 Here is an example of sorting a table::
 

python/pyarrow/scalar.pxi

@@ -18,6 +18,7 @@
 import collections
 import warnings
 from uuid import UUID
+from collections.abc import Sequence, Mapping
 
 
 cdef class Scalar(_Weakrefable):
@@ -219,6 +220,8 @@ cdef class BooleanScalar(Scalar):
         cdef CBooleanScalar* sp = <CBooleanScalar*> self.wrapped.get()
         return sp.value if sp.is_valid else None
 
+    def __bool__(self):
+        return self.as_py() or False
 
 cdef class UInt8Scalar(Scalar):
     """
@@ -238,6 +241,9 @@ cdef class UInt8Scalar(Scalar):
         cdef CUInt8Scalar* sp = <CUInt8Scalar*> self.wrapped.get()
         return sp.value if sp.is_valid else None
 
+    def __index__(self):
+        return self.as_py()
+
 
 cdef class Int8Scalar(Scalar):
     """
@@ -257,6 +263,9 @@ cdef class Int8Scalar(Scalar):
         cdef CInt8Scalar* sp = <CInt8Scalar*> self.wrapped.get()
         return sp.value if sp.is_valid else None
 
+    def __index__(self):
+        return self.as_py()
+
 
 cdef class UInt16Scalar(Scalar):
     """
@@ -276,6 +285,9 @@ cdef class UInt16Scalar(Scalar):
         cdef CUInt16Scalar* sp = <CUInt16Scalar*> self.wrapped.get()
         return sp.value if sp.is_valid else None
 
+    def __index__(self):
+        return self.as_py()
+
 
 cdef class Int16Scalar(Scalar):
     """
@@ -295,6 +307,9 @@ cdef class Int16Scalar(Scalar):
         cdef CInt16Scalar* sp = <CInt16Scalar*> self.wrapped.get()
         return sp.value if sp.is_valid else None
 
+    def __index__(self):
+        return self.as_py()
+
 
 cdef class UInt32Scalar(Scalar):
     """
@@ -314,6 +329,9 @@ cdef class UInt32Scalar(Scalar):
         cdef CUInt32Scalar* sp = <CUInt32Scalar*> self.wrapped.get()
         return sp.value if sp.is_valid else None
 
+    def __index__(self):
+        return self.as_py()
+
 
 cdef class Int32Scalar(Scalar):
     """
@@ -333,6 +351,9 @@ cdef class Int32Scalar(Scalar):
         cdef CInt32Scalar* sp = <CInt32Scalar*> self.wrapped.get()
         return sp.value if sp.is_valid else None
 
+    def __index__(self):
+        return self.as_py()
+
 
 cdef class UInt64Scalar(Scalar):
     """
@@ -352,6 +373,9 @@ cdef class UInt64Scalar(Scalar):
         cdef CUInt64Scalar* sp = <CUInt64Scalar*> self.wrapped.get()
         return sp.value if sp.is_valid else None
 
+    def __index__(self):
+        return self.as_py()
+
 
 cdef class Int64Scalar(Scalar):
     """
@@ -371,6 +395,9 @@ cdef class Int64Scalar(Scalar):
         cdef CInt64Scalar* sp = <CInt64Scalar*> self.wrapped.get()
         return sp.value if sp.is_valid else None
 
+    def __index__(self):
+        return self.as_py()
+
 
 cdef class HalfFloatScalar(Scalar):
     """
@@ -390,6 +417,12 @@ cdef class HalfFloatScalar(Scalar):
         cdef CHalfFloatScalar* sp = <CHalfFloatScalar*> self.wrapped.get()
         return PyFloat_FromHalf(sp.value) if sp.is_valid else None
 
+    def __float__(self):
+        return self.as_py()
+
+    def __int__(self):
+        return int(self.as_py())
+
 
 cdef class FloatScalar(Scalar):
     """
@@ -409,6 +442,12 @@ cdef class FloatScalar(Scalar):
         cdef CFloatScalar* sp = <CFloatScalar*> self.wrapped.get()
         return sp.value if sp.is_valid else None
 
+    def __float__(self):
+        return self.as_py()
+
+    def __int__(self):
+        return int(float(self))
+
 
 cdef class DoubleScalar(Scalar):
     """
@@ -428,6 +467,12 @@ cdef class DoubleScalar(Scalar):
         cdef CDoubleScalar* sp = <CDoubleScalar*> self.wrapped.get()
         return sp.value if sp.is_valid else None
 
+    def __float__(self):
+        return self.as_py()
+
+    def __int__(self):
+        return int(float(self))
+
 
 cdef class Decimal32Scalar(Scalar):
     """
@@ -843,6 +888,15 @@ cdef class BinaryScalar(Scalar):
         buffer = self.as_buffer()
         return None if buffer is None else buffer.to_pybytes()
 
+    def __bytes__(self):
+        return self.as_py()
+
+    def __getbuffer__(self, cp.Py_buffer* buffer, int flags):
+        buf = self.as_buffer()
+        if buf is None:
+            raise ValueError("Cannot export buffer from null Arrow Scalar")
+        cp.PyObject_GetBuffer(buf, buffer, flags)
+
 
 cdef class LargeBinaryScalar(BinaryScalar):
     pass
@@ -883,7 +937,7 @@ cdef class StringViewScalar(StringScalar):
     pass
 
 
-cdef class ListScalar(Scalar):
+cdef class ListScalar(Scalar, Sequence):
     """
     Concrete class for list-like scalars.
     """
@@ -952,7 +1006,7 @@ cdef class LargeListViewScalar(ListScalar):
     pass
 
 
-cdef class StructScalar(Scalar, collections.abc.Mapping):
+cdef class StructScalar(Scalar, Mapping):
     """
     Concrete class for struct scalars.
     """
@@ -1051,20 +1105,34 @@ cdef class StructScalar(Scalar, collections.abc.Mapping):
         return str(self._as_py_tuple())
 
 
-cdef class MapScalar(ListScalar):
+cdef class MapScalar(ListScalar, Mapping):
     """
     Concrete class for map scalars.
     """
 
     def __getitem__(self, i):
         """
-        Return the value at the given index.
+        Return the value at the given index or key.
         """
+
         arr = self.values
         if arr is None:
-            raise IndexError(i)
+            raise IndexError(i) if isinstance(i, int) else KeyError(i)
+
+        key_field = self.type.key_field.name
+        item_field = self.type.item_field.name
+
+        if isinstance(i, (bytes, str)):
+            try:
+                key_index = list(self.keys()).index(i)
+            except ValueError:
+                raise KeyError(i)
+
+            dct = arr[_normalize_index(key_index, len(arr))]
+            return dct[item_field]
+
         dct = arr[_normalize_index(i, len(arr))]
-        return (dct[self.type.key_field.name], dct[self.type.item_field.name])
+        return (dct[key_field], dct[item_field])
 
     def __iter__(self):
         """
@@ -1118,6 +1186,16 @@ cdef class MapScalar(ListScalar):
             result_dict[key] = value
         return result_dict
 
+    def keys(self):
+        """
+        Return the keys of the map as a list.
+        """
+        arr = self.values
+        if arr is None:
+            return []
+        key_field = self.type.key_field.name
+        return [k.as_py() for k in arr.field(key_field)]
+
 
 cdef class DictionaryScalar(Scalar):
     """