(improvement) serializers: address PR review feedback

- Chain original exception in _raise_bind_serialize_error (raise from exc)
- Change _check_int32_range to raise struct.error instead of OverflowError,
  matching the behaviour of struct.pack('>i', value)
- Clarify docstrings for _check_float_range/_check_int32_range
- 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
- Add struct import to serializers.pyx for struct.error
- Fix test_plain_path_overflow_error_wrapped docstring (struct.error, not OverflowError)
- Update OverflowSerializer stub to raise struct.error
- 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,21 @@ 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.  struct.error arises from int32 out-of-range values;
+    OverflowError from float out-of-range values.  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):
@@ -826,7 +834,7 @@ def bind(self, values):
                         else:
                             col_bytes = col_spec.type.serialize(value, proto_version)
                         self.values[idx] = col_bytes
-                    # OverflowError: Cython int32/float casts may raise on out-of-range values
+                    # struct.error: int32 out-of-range; OverflowError: float out-of-range
                     except (TypeError, struct.error, OverflowError) as exc:
                         _raise_bind_serialize_error(col_spec, value, exc)
                 idx += 1
@@ -850,7 +858,7 @@ def bind(self, values):
                         try:
                             col_bytes = ser.serialize(value, proto_version)
                             self.values[idx] = col_bytes
-                        # OverflowError: Cython int32/float casts may raise on out-of-range values
+                        # struct.error: int32 out-of-range; OverflowError: float out-of-range
                         except (TypeError, struct.error, OverflowError) as exc:
                             _raise_bind_serialize_error(col_spec, value, exc)
                     idx += 1
@@ -871,7 +879,7 @@ def bind(self, values):
                         try:
                             col_bytes = col_spec.type.serialize(value, proto_version)
                             self.values[idx] = col_bytes
-                        # OverflowError: Cython int32/float casts may raise on out-of-range values
+                        # struct.error: int32 out-of-range; OverflowError: float out-of-range
                         except (TypeError, struct.error, OverflowError) as exc:
                             _raise_bind_serialize_error(col_spec, value, exc)
                     idx += 1

cassandra/serializers.pyx

@@ -34,6 +34,9 @@ from libc.math cimport isinf, isnan
 from cpython.bytes cimport PyBytes_FromStringAndSize
 
 from cassandra import cqltypes
+import io
+import struct
+from cassandra.marshal import uvint_pack
 
 cdef bint is_little_endian
 from cassandra.util import is_little_endian
@@ -60,9 +63,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.
+    Matches the behaviour of struct.pack('>f', value), which raises
+    OverflowError for values that cannot be represented as a 32-bit
+    IEEE 754 float. 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:
@@ -76,17 +79,16 @@ 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.
+    """Raise struct.error 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.
+    Matches the behaviour of struct.pack('>i', value), which raises
+    struct.error for out-of-range values. 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(
-            "Value %r out of range for int32 "
-            "(must be between -2147483648 and 2147483647)" % (value,)
+        raise struct.error(
+            "'i' format requires -2147483648 <= number <= 2147483647"
         )
 
 
@@ -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:

tests/unit/test_parameter_binding.py

@@ -13,6 +13,7 @@
 # limitations under the License.
 
 import unittest
+import struct
 import pytest
 
 from cassandra.encoder import Encoder
@@ -244,20 +245,20 @@ def serialize(self, value, protocol_version):
 
 
 class OverflowSerializer:
-    """Stub that raises OverflowError, mimicking Cython <int32_t> cast overflow."""
+    """Stub that raises struct.error, mimicking Cython int32 range check."""
 
     def __init__(self, cqltype):
         self.cqltype = cqltype
 
     def serialize(self, value, protocol_version):
-        raise OverflowError("value too large to convert to int32_t")
+        raise struct.error("'i' format requires -2147483648 <= number <= 2147483647")
 
 
 class CythonBindPathTest(unittest.TestCase):
     """Tests for the Cython serializer fast path in BoundStatement.bind().
 
     These tests inject stub serializers via the PreparedStatement's cached
-    __serializers attribute to exercise the Cython bind branch without
+    _cached_serializers attribute to exercise the Cython bind branch without
     requiring compiled Cython.
     """
 
@@ -275,9 +276,9 @@ def _make_prepared(self, column_metadata, serializers=None):
             result_metadata=None,
             result_metadata_id=None,
         )
-        # Inject directly into the name-mangled cache attribute used by
-        # the _serializers property, bypassing the lazy initialization.
-        prepared._PreparedStatement__serializers = serializers
+        # Inject directly into the cache attribute used by the _serializers
+        # property, bypassing the lazy initialization.
+        prepared._cached_serializers = serializers
         return prepared
 
     def test_cython_path_normal_serialization(self):
@@ -321,7 +322,7 @@ def test_cython_path_unset_value(self):
         assert bound.values[1] == UNSET_VALUE
 
     def test_cython_path_overflow_error_wrapped(self):
-        """OverflowError from Cython cast is caught and wrapped with column context."""
+        """struct.error from Cython int32 range check is caught and wrapped with column context."""
         column_metadata = [ColumnMetadata("keyspace", "cf", "v0", Int32Type)]
         serializers = [OverflowSerializer(Int32Type)]
         prepared = self._make_prepared(column_metadata, serializers)
@@ -348,7 +349,8 @@ def test_cython_path_type_error_wrapped(self):
         assert "Int32Type" in msg
 
     def test_plain_path_overflow_error_wrapped(self):
-        """OverflowError in the plain Python path is also caught and wrapped."""
+        """Out-of-range int in the plain Python path raises struct.error (caught
+        alongside OverflowError) and is wrapped with column context."""
         column_metadata = [ColumnMetadata("keyspace", "cf", "v0", Int32Type)]
         # Force the plain Python path (no Cython serializers)
         prepared = self._make_prepared(column_metadata, serializers=None)
@@ -383,7 +385,7 @@ def _make_prepared(
             result_metadata=None,
             result_metadata_id=None,
         )
-        prepared._PreparedStatement__serializers = serializers
+        prepared._cached_serializers = serializers
         return prepared
 
     def _three_column_metadata(self):