(improvement) serializers: address PR review feedback

- Chain original exception in _raise_bind_serialize_error (raise from exc)
- Clarify docstrings for _check_float_range/_check_int32_range (OverflowError vs struct.error)
- Expand _raise_bind_serialize_error docstring with specific exception types
- Document __getitem__ requirement in vector serialize methods
- Move io and uvint_pack imports to module scope in serializers.pyx
- Fix test_plain_path_overflow_error_wrapped docstring (struct.error, not OverflowError)
- Replace name-mangled __serializers with _cached_serializers

Author: mykaul

cassandra/query.py

@@ -552,16 +552,16 @@ def _serializers(self):
         if self.column_encryption_policy:
             return None
         try:
-            return self.__serializers
+            return self._cached_serializers
         except AttributeError:
             pass
         if _HAVE_CYTHON_SERIALIZERS and self.column_metadata:
-            self.__serializers = _cython_make_serializers(
+            self._cached_serializers = _cython_make_serializers(
                 [col.type for col in self.column_metadata]
             )
         else:
-            self.__serializers = None
-        return self.__serializers
+            self._cached_serializers = None
+        return self._cached_serializers
 
     @classmethod
     def from_message(
@@ -663,13 +663,19 @@ def __str__(self):
 
 
 def _raise_bind_serialize_error(col_spec, value, exc):
-    """Wrap serialization errors with column context for all bind loop paths."""
+    """Wrap TypeError, struct.error, or OverflowError with column context.
+
+    Called from all three bind loop paths (CE, Cython, plain Python) to
+    provide a uniform error message that includes the column name and
+    expected type. Other exception types (e.g. ValueError from VectorType
+    dimension mismatch) propagate without wrapping.
+    """
     actual_type = type(value)
     message = (
         'Received an argument of invalid type for column "%s". '
         "Expected: %s, Got: %s; (%s)" % (col_spec.name, col_spec.type, actual_type, exc)
     )
-    raise TypeError(message)
+    raise TypeError(message) from exc
 
 
 class BoundStatement(Statement):

cassandra/serializers.pyx

@@ -34,6 +34,8 @@ from libc.math cimport isinf, isnan
 from cpython.bytes cimport PyBytes_FromStringAndSize
 
 from cassandra import cqltypes
+import io
+from cassandra.marshal import uvint_pack
 
 cdef bint is_little_endian
 from cassandra.util import is_little_endian
@@ -60,9 +62,9 @@ cdef class Serializer:
 cdef inline void _check_float_range(double value) except *:
     """Raise OverflowError for finite values outside float32 range.
 
-    This matches the behavior of struct.pack('>f', value), which raises
-    OverflowError (via struct.error) for values that cannot be represented
-    as a 32-bit IEEE 754 float. inf, -inf, and nan pass through unchanged.
+    Provides equivalent validation to struct.pack('>f', value), but raises
+    OverflowError instead of struct.error. The bind loop in query.py catches
+    both exception types. inf, -inf, and nan pass through unchanged.
     """
     if not isinf(value) and not isnan(value):
         if value > <double>FLT_MAX or value < -<double>FLT_MAX:
@@ -78,10 +80,10 @@ cdef inline void _check_float_range(double value) except *:
 cdef inline void _check_int32_range(object value) except *:
     """Raise OverflowError for values outside the signed int32 range.
 
-    This matches the behavior of struct.pack('>i', value), which raises
-    struct.error for values outside [-2147483648, 2147483647]. The check
-    must be done on the Python int *before* the C-level <int32_t> cast,
-    which would silently truncate.
+    Provides equivalent validation to struct.pack('>i', value), but raises
+    OverflowError instead of struct.error. The bind loop in query.py catches
+    both exception types. The check must be done on the Python int *before*
+    the C-level <int32_t> cast, which would silently truncate.
     """
     if value > 2147483647 or value < -2147483648:
         raise OverflowError(
@@ -222,7 +224,11 @@ cdef class SerVectorType(Serializer):
             return self._serialize_generic(value, protocol_version)
 
     cdef inline bytes _serialize_float(self, object values):
-        """Serialize a list of floats into a contiguous big-endian buffer."""
+        """Serialize a sequence of floats into a contiguous big-endian buffer.
+
+        Note: uses index-based access (values[i]) rather than iteration, so
+        the input must support __getitem__ (e.g. list or tuple).
+        """
         cdef Py_ssize_t i
         cdef Py_ssize_t buf_size = self.vector_size * 4
         if buf_size == 0:
@@ -255,7 +261,11 @@ cdef class SerVectorType(Serializer):
             free(buf)
 
     cdef inline bytes _serialize_double(self, object values):
-        """Serialize a list of doubles into a contiguous big-endian buffer."""
+        """Serialize a sequence of doubles into a contiguous big-endian buffer.
+
+        Note: uses index-based access (values[i]) rather than iteration, so
+        the input must support __getitem__ (e.g. list or tuple).
+        """
         cdef Py_ssize_t i
         cdef Py_ssize_t buf_size = self.vector_size * 8
         if buf_size == 0:
@@ -291,7 +301,11 @@ cdef class SerVectorType(Serializer):
             free(buf)
 
     cdef inline bytes _serialize_int32(self, object values):
-        """Serialize a list of int32 values into a contiguous big-endian buffer."""
+        """Serialize a sequence of int32 values into a contiguous big-endian buffer.
+
+        Note: uses index-based access (values[i]) rather than iteration, so
+        the input must support __getitem__ (e.g. list or tuple).
+        """
         cdef Py_ssize_t i
         cdef Py_ssize_t buf_size = self.vector_size * 4
         if buf_size == 0:
@@ -325,9 +339,6 @@ cdef class SerVectorType(Serializer):
 
     cdef inline bytes _serialize_generic(self, object values, int protocol_version):
         """Fallback: element-by-element Python serialization for non-optimized types."""
-        import io
-        from cassandra.marshal import uvint_pack
-
         serialized_size = self.subtype.serial_size()
         buf = io.BytesIO()
         for item in values: