GH-51019: [Python] Raise IndexError for out-of-bounds KeyValueMetadata key/value

python/pyarrow/tests/test_types.py

@@ -1193,6 +1193,34 @@ def test_key_value_metadata():
         ], b='BETA')
 
 
+def test_key_value_metadata_index_errors():
+    meta = pa.KeyValueMetadata({'a': 'A', 'b': 'B'})
+
+    # in-bounds accesses still work
+    assert meta.key(0) == b'a'
+    assert meta.key(1) == b'b'
+    assert meta.value(0) == b'A'
+    assert meta.value(1) == b'B'
+
+    # out-of-range indexes raise IndexError instead of segfaulting
+    with pytest.raises(IndexError):
+        meta.key(2)
+    with pytest.raises(IndexError):
+        meta.key(-1)
+    with pytest.raises(IndexError):
+        meta.value(2)
+    with pytest.raises(IndexError):
+        meta.value(-1)
+
+    # empty metadata: index 0 is out of bounds too
+    empty = pa.KeyValueMetadata()
+    assert len(empty) == 0
+    with pytest.raises(IndexError):
+        empty.key(0)
+    with pytest.raises(IndexError):
+        empty.value(0)
+
+
 def test_key_value_metadata_duplicates():
     meta = pa.KeyValueMetadata({'a': '1', 'b': '2'})
 

python/pyarrow/types.pxi

@@ -2386,7 +2386,16 @@ cdef class KeyValueMetadata(_Metadata, Mapping):
         Returns
         -------
         byte
+
+        Raises
+        ------
+        IndexError
+            If `i` is negative or out of bounds.
         """
+        if i < 0 or i >= self.metadata.size():
+            raise IndexError(
+                f"key index {i} is out of bounds for metadata of size "
+                f"{self.metadata.size()}")
         return self.metadata.key(i)
 
     def value(self, i):
@@ -2398,7 +2407,16 @@ cdef class KeyValueMetadata(_Metadata, Mapping):
         Returns
         -------
         byte
+
+        Raises
+        ------
+        IndexError
+            If `i` is negative or out of bounds.
         """
+        if i < 0 or i >= self.metadata.size():
+            raise IndexError(
+                f"value index {i} is out of bounds for metadata of size "
+                f"{self.metadata.size()}")
         return self.metadata.value(i)
 
     def keys(self):