fix: address review feedback for Cython serializers

- Support __index__ protocol in int32 serialization (_coerce_int helper)
- Add empty-list guard to deserializers.obj_array() for consistency
- Move test file to tests/unit/cython/test_serializers.py, use shared cythontest
- Skip tuple() copy when value is already list or tuple (perf optimization)
- Add test_index_protocol and test_vector_index_protocol tests
- Update docstrings for obj_array() in both serializers and deserializers

Author: mykaul

cassandra/deserializers.pyx

@@ -481,7 +481,15 @@ cpdef Deserializer find_deserializer(cqltype):
 
 
 def obj_array(list objs):
-    """Create a (Cython) array of objects given a list of objects"""
+    """Create a (Cython) array of objects given a list of objects.
+
+    Returns the plain list for empty input since ``cython_array`` does
+    not support zero-length shapes.  Callers that use
+    ``cdef Deserializer[::1]`` typed memoryviews must guard against
+    empty input before assignment.
+    """
+    if not objs:
+        return objs
     cdef object[:] arr
     cdef Py_ssize_t i
     arr = cython_array(shape=(len(objs),), itemsize=sizeof(void *), format="O")

cassandra/serializers.pyx

@@ -34,6 +34,7 @@ from cpython.bytes cimport PyBytes_FromStringAndSize, PyBytes_AS_STRING
 from cython.view cimport array as cython_array
 
 from cassandra import cqltypes
+from operator import index as _operator_index
 
 cdef bint is_little_endian
 from cassandra.util import is_little_endian
@@ -69,13 +70,26 @@ cdef inline void _check_int32_range(object value) except *:
     struct.pack('>i', ...): [-2147483648, 2147483647]. The check must
     be done on the Python int *before* the C-level <int32_t> cast,
     which would silently truncate.
+
+    The value should already have been coerced via ``_coerce_int()``
+    (i.e. the ``__index__`` protocol) before being passed here.
     """
     if value > 2147483647 or value < -2147483648:
         raise OverflowError(
             "Value %r out of range for int32 "
             "(must be between -2147483648 and 2147483647)" % (value,))
 
 
+cdef inline object _coerce_int(object value):
+    """Coerce *value* to a Python ``int`` via the ``__index__`` protocol.
+
+    This matches ``struct.pack('>i', value)`` semantics, which accepts any
+    object implementing ``__index__`` (e.g. numpy integer scalars).  Raises
+    ``TypeError`` for objects that do not support the protocol.
+    """
+    return _operator_index(value)
+
+
 # ---------------------------------------------------------------------------
 # Base class
 # ---------------------------------------------------------------------------
@@ -141,6 +155,7 @@ cdef class SerInt32Type(Serializer):
     """Serialize a Python int to 4-byte big-endian signed int32."""
 
     cpdef bytes serialize(self, object value, int protocol_version):
+        value = _coerce_int(value)
         _check_int32_range(value)
         cdef int32_t val = <int32_t>value
         cdef char out[4]
@@ -204,10 +219,12 @@ cdef class SerVectorType(Serializer):
             self.type_code = 0
 
     cpdef bytes serialize(self, object value, int protocol_version):
-        # Normalize to tuple so indexing works for any iterable with __len__.
+        # Normalize to tuple/list so indexing works for any iterable.
         # The Python VectorType.serialize() only requires len() + iteration,
-        # so we must accept the same inputs.
-        value = tuple(value)
+        # so we must accept the same inputs.  Avoid a copy if value is
+        # already a list or tuple (common fast path for embeddings).
+        if not isinstance(value, (list, tuple)):
+            value = tuple(value)
         cdef Py_ssize_t v_length = len(value)
         if v_length != self.vector_size:
             raise ValueError(
@@ -315,7 +332,7 @@ cdef class SerVectorType(Serializer):
         cdef char *dst
 
         for i in range(self.vector_size):
-            item = values[i]
+            item = _coerce_int(values[i])
             _check_int32_range(item)
             val = <int32_t>item
             src = <char *>&val
@@ -403,7 +420,9 @@ def obj_array(list objs):
 
     Mirrors ``deserializers.obj_array()`` so both sides share the same
     typed-memoryview convention.  Returns the plain list for empty input
-    since ``cython_array`` does not support zero-length shapes.
+    since ``cython_array`` does not support zero-length shapes.  Callers
+    that use ``cdef Serializer[::1]`` typed memoryviews must guard
+    against empty input before assignment.
     """
     if not objs:
         return objs

tests/unit/test_serializers.py tests/unit/cython/test_serializers.pytests/unit/test_serializers.py renamed to tests/unit/cython/test_serializers.py

@@ -23,6 +23,8 @@
 import struct
 import unittest
 
+from tests.unit.cython.utils import cythontest
+
 from cassandra.cython_deps import HAVE_CYTHON
 
 try:
@@ -40,27 +42,20 @@
     BooleanType,
 )
 
-# Import serializers only if Cython is available (compiled .so present)
+# Import serializers only if Cython is available (compiled .so present).
+# When VERIFY_CYTHON is set (CI mode), let ImportError propagate so build
+# failures are not silently swallowed.
 if HAVE_CYTHON or VERIFY_CYTHON:
-    try:
-        from cassandra.serializers import (
-            Serializer,
-            SerFloatType,
-            SerDoubleType,
-            SerInt32Type,
-            SerVectorType,
-            GenericSerializer,
-            find_serializer,
-            make_serializers,
-        )
-    except ImportError:
-        # .so not built — fall back so @cythontest skips gracefully
-        HAVE_CYTHON = False
-        VERIFY_CYTHON = False
-
-cythontest = unittest.skipUnless(
-    HAVE_CYTHON or VERIFY_CYTHON, "Cython is not available"
-)
+    from cassandra.serializers import (
+        Serializer,
+        SerFloatType,
+        SerDoubleType,
+        SerInt32Type,
+        SerVectorType,
+        GenericSerializer,
+        find_serializer,
+        make_serializers,
+    )
 
 # Protocol version used in tests (value doesn't affect scalar serialization)
 PROTO = 4
@@ -254,6 +249,17 @@ def test_type_error_none(self):
         with self.assertRaises(TypeError):
             self.ser.serialize(None, PROTO)
 
+    def test_index_protocol(self):
+        """Objects implementing __index__ should be accepted, like struct.pack."""
+
+        class MyInt:
+            def __index__(self):
+                return 42
+
+        cython_bytes = self.ser.serialize(MyInt(), PROTO)
+        python_bytes = Int32Type.serialize(42, PROTO)
+        self.assertEqual(cython_bytes, python_bytes)
+
 
 # ---------------------------------------------------------------------------
 # VectorType serializer equivalence tests
@@ -364,6 +370,17 @@ def test_element_overflow_negative(self):
         with self.assertRaises((OverflowError, struct.error)):
             self.ser.serialize([1, -2147483649, 3], PROTO)
 
+    def test_vector_index_protocol(self):
+        """Objects implementing __index__ in vector elements should be accepted."""
+
+        class MyInt:
+            def __index__(self):
+                return 42
+
+        cython_bytes = self.ser.serialize([MyInt(), MyInt(), MyInt()], PROTO)
+        python_bytes = self.vec_type.serialize([42, 42, 42], PROTO)
+        self.assertEqual(cython_bytes, python_bytes)
+
 
 @cythontest
 class TestSerVectorTypeGenericFallback(unittest.TestCase):