(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

@@ -494,15 +494,15 @@ 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(cls, query_id, column_metadata, pk_indexes, cluster_metadata,
@@ -563,11 +563,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.  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):
@@ -698,7 +706,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
@@ -719,7 +727,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
@@ -737,7 +745,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

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
@@ -229,20 +230,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.
     """
 
@@ -258,9 +259,9 @@ def _make_prepared(self, column_metadata, serializers=None):
                                      protocol_version=self.protocol_version,
                                      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):
@@ -298,7 +299,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)
@@ -325,7 +326,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)
@@ -356,7 +358,7 @@ def _make_prepared(self, column_metadata, serializers=None, routing_key_indexes=
                                      protocol_version=self.protocol_version,
                                      result_metadata=None,
                                      result_metadata_id=None)
-        prepared._PreparedStatement__serializers = serializers
+        prepared._cached_serializers = serializers
         return prepared
 
     def _three_column_metadata(self):