(improvement) query: add Cython-aware serializer path in BoundStatement.bind()

[mykaul]

Summary

• When Cython serializers (cassandra.serializers from PR (improvement) serializers: add Cython-optimized serialization for VectorType #748) are available and no column encryption policy is active, BoundStatement.bind() uses pre-built Serializer objects cached on the PreparedStatement instead of calling cqltype classmethods
• The bind loop is split into three code paths: (1) column encryption policy, (2) Cython serializers (new fast path), (3) plain Python fallback
• The plain Python fallback also benefits by removing the per-value ColDesc construction and ce_policy check that was previously done unconditionally

Dependencies

• PR (improvement) serializers: add Cython-optimized serialization for VectorType #748: Cython serializers module (cassandra/serializers.pyx) — provides make_serializers() and the Serializer classes used by the new fast path
• PR Optimize column_encryption_policy checks in recv_results_rows #630: CE-policy bind split — this PR builds on the same concept of splitting the bind loop by CE policy presence

Performance

End-to-end BoundStatement.bind() benchmarks

Measured on a single CPU core (pinned), Python 3.14, comparing the Cython serializers path vs the plain Python path:

Workload	Cython (μs/op)	Python (μs/op)	Speedup
Vector<float, 128> (1 column)	1.6	14.6	9.4x
Vector<float, 768> (1 column)	3.6	66.1	18.2x
Vector<float, 1536> (1 column)	4.8	122.2	25.7x
10 mixed scalars (5 float + 3 int32 + 2 double)	2.1	2.7	1.3x
1 Vector<float, 1536> + 3 scalars (realistic INSERT)	5.5	145.0	26.1x

Key observations:

• Vector columns get massive speedups (9–26x) because the Cython serializer replaces the per-element io.BytesIO loop with a pre-allocated C buffer and inline byte-swap
• Scalar-only workloads still see a modest 1.3x improvement from eliminating per-value ColDesc namedtuple construction and ce_policy checks
• Speedup scales with vector dimension — higher dimensions save more per-element Python dispatch overhead

Memory savings

The old bind loop created a ColDesc namedtuple (~72 bytes) for every bound value, even when no column encryption policy was set. Both new non-CE paths eliminate this entirely.

Per bind() call, for N columns:

Allocation	Old path	New path (Cython or plain Python)	Eliminated
ColDesc namedtuples	N	0	N
ce_policy and ... evaluations	N	0	N
ce_policy.column_type(...) ternary	N	0	N

Per VectorType column (D-dimensional float/double/int32), additionally:

Allocation	Old VectorType.serialize()	New Cython SerVectorType	Eliminated
io.BytesIO() instance	1	0	1
Intermediate bytes per element	D	0	D
buf.getvalue() final copy	1	0	1
BytesIO internal buffer reallocations	~3–4	0 (exact-size malloc)	~3–4
Python method calls in serialize loop	2D (subtype.serialize + buf.write)	0 (C-level loop)	2D

Concrete example: A prepared INSERT with 5 scalar columns + 1 Vector<float, 1536> column eliminates ~1545 transient Python objects and ~88 KB of transient allocations per bind() call, plus ~3076 Python method calls.

Design

PreparedStatement._serializers (lazy cached property)

On first access, calls make_serializers([col.type for col in self.column_metadata]) which returns a list of Cython Serializer objects (one per bind column). Returns None if:

• Cython serializers module is not compiled/available
• A column encryption policy is set
• No column metadata exists

The cache is safe because column_metadata is immutable after PreparedStatement creation. Thread safety is guaranteed by the benign-race pattern (idempotent computation + atomic attribute assignment).

Three-way bind loop

if ce_policy:
    # Path 1: Column encryption — unchanged behavior, creates ColDesc per value
elif serializers is not None:
    # Path 2: Cython fast path — ser.serialize(value, proto_version)
else:
    # Path 3: Plain Python — col_spec.type.serialize(value, proto_version)

Path 2 uses zip(serializers, values, col_meta) to iterate all three in lockstep without index overhead. Path 3 removes the per-value ColDesc construction and ce_policy check from the original code.

Testing

• All existing unit tests pass (test_query.py, test_types.py)
• Manually verified: Cython path produces identical serialized bytes to pure Python path for Float, Int32, Double types
• Verified None, UNSET_VALUE, short value lists, and dict binding all work correctly across all three paths
• Verified graceful fallback when Cython module is not available (_HAVE_CYTHON_SERIALIZERS = False)

[Copilot]

Pull request overview

This PR introduces an optional, Cython-accelerated serialization path for BoundStatement.bind() to reduce per-value overhead (especially for large VectorType columns) when Cython serializers are available and no column encryption policy is enabled.

Changes:

• Add a new Cython cassandra.serializers extension (with .pyx + .pxd) providing Serializer implementations and a make_serializers() factory.
• Add lazy caching of per-column serializer objects on PreparedStatement via a _serializers property.
• Split the bind loop into three branches: column encryption policy, Cython fast path, and pure-Python fallback (with reduced per-value overhead in the fallback).

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 5 comments.

File	Description
cassandra/serializers.pyx	Adds Cython serializer implementations (scalar + VectorType) and lookup/factory functions.
cassandra/serializers.pxd	Exposes the Serializer cdef interface for Cython usage.
cassandra/query.py	Integrates the optional Cython serializer path into PreparedStatement/BoundStatement.bind() with lazy caching and branch selection.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Adds an optimized parameter binding path that can leverage Cython Serializer objects (when available) to speed up BoundStatement.bind(), while preserving the existing column-encryption behavior and improving the plain-Python fallback.

Changes:

• Add PreparedStatement._serializers lazy cache and a three-way bind loop in BoundStatement.bind() (CE policy / Cython fast path / Python fallback).
• Introduce Cython Serializer implementations for Float/Double/Int32/Vector and a make_serializers() factory.
• Extend unit tests to exercise the Cython-serializer bind branch via injected stub serializers.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.

File	Description
cassandra/query.py	Adds Cython-serializer availability detection, caches serializers on PreparedStatement, and selects the new bind fast path when safe.
cassandra/serializers.pyx	Implements Cython serializers (including optimized VectorType) and factory/lookup helpers.
cassandra/serializers.pxd	Declares the Cython Serializer interface for cross-module typing.
tests/unit/test_parameter_binding.py	Adds tests for the new bind branch and error-wrapping behavior using stub serializers.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Adds a Cython-aware fast path to BoundStatement.bind() so prepared statements can use cached per-column serializer objects (when available and no column encryption policy is active), reducing Python dispatch and per-value overhead during binding.

Changes:

• Add lazy PreparedStatement._serializers cache and split BoundStatement.bind() into CE-policy, Cython-serializer, and pure-Python paths.
• Introduce Cython Serializer implementations (including optimized VectorType serialization) and a make_serializers() factory.
• Expand/adjust unit tests to cover the new Cython bind branch via injected stub serializers.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
cassandra/query.py	Adds serializer caching and a new bind fast path (plus significant formatting-only edits in the same module).
cassandra/serializers.pyx	Introduces Cython serializer implementations and factory/lookup helpers.
cassandra/serializers.pxd	Declares the Cython Serializer interface for cross-module use.
tests/unit/test_parameter_binding.py	Adds tests to exercise the Cython bind path without requiring compiled Cython.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Adds a Cython-aware fast path to BoundStatement.bind() by reworking the bind loop into distinct branches (column encryption vs Cython serializers vs pure-Python), and introduces the Cython serializer module used by the new path.

Changes:

• Add lazy cached PreparedStatement._serializers and update BoundStatement.bind() to use Cython Serializer objects when available and CE policy is not active.
• Factor bind-time serialization error wrapping into a shared helper and extend wrapping to include OverflowError.
• Add unit tests that exercise the new Cython bind branch via injected stub serializers, plus overflow wrapping coverage.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

File	Description
cassandra/query.py	Adds _serializers cache on PreparedStatement, a shared bind error wrapper, and splits BoundStatement.bind() into CE / Cython / Python paths.
cassandra/serializers.pyx	Introduces Cython Serializer implementations (scalar + vector) and serializer factory helpers.
cassandra/serializers.pxd	Exposes the Serializer cdef interface for Cython interop.
tests/unit/test_parameter_binding.py	Adds unit tests to validate the new Cython bind path behavior and error wrapping.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Adds an optimized binding path that leverages Cython-backed per-column Serializer objects (when available) to reduce Python overhead in BoundStatement.bind(), while keeping existing behavior for column encryption policy and providing a streamlined pure-Python fallback.

Changes:

• Add lazy, cached Cython serializer lookup on PreparedStatement and route BoundStatement.bind() through a 3-way path: CE-policy, Cython fast path, pure-Python fallback.
• Introduce Cython serializer implementations (Serializer, scalar serializers, SerVectorType, and factories).
• Extend unit tests to exercise the Cython fast-path behavior (via injected stub serializers) and UNSET handling scenarios.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

File	Description
cassandra/query.py	Adds optional Cython serializer import, caches per-column serializers on PreparedStatement, and refactors BoundStatement.bind() into CE/Cython/Python paths with pre-allocation.
cassandra/serializers.pyx	Introduces Cython-optimized serializers (including VectorType) and factory functions for per-column serializer creation.
cassandra/serializers.pxd	Declares the Cython Serializer interface for cross-module typing/cimports.
tests/unit/test_parameter_binding.py	Adds tests that inject stub serializers to validate the Cython bind path and UNSET behavior across paths.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

SerVectorType’s optimized _serialize_float/_serialize_double/_serialize_int32 paths require getitem (values[i]) even though the pure-Python VectorType.serialize() only requires len + iteration. This means some inputs that currently serialize fine in Python (any iterable with len but without indexing) will fail only when the Cython fast path is selected. Consider using PySequence_Fast/sequence coercion (or falling back to the generic element-iteration path) so accepted input types are consistent across paths.

[Copilot]

In the v4+ UNSET fill loop, the loop variable i is unused (for i in range(idx, col_meta_len):). Consider using while idx < col_meta_len: (or for _ in range(...)) to avoid an unused variable and make the intent clearer.

Suggested change

	for i in range(idx, col_meta_len):
	while idx < col_meta_len:

[Copilot]

_raise_bind_serialize_error() wraps struct.error/OverflowError as well as TypeError, but the emitted message always says "invalid type". For out-of-range numeric values this is misleading (the type may be correct but the value is invalid). Consider adjusting the message (or branching on exception type) to mention an invalid value/range overflow while still including the column context.

Suggested change

	message = (
	'Received an argument of invalid type for column "%s". '
	"Expected: %s, Got: %s; (%s)" % (col_spec.name, col_spec.type, actual_type, exc)
	)
	if isinstance(exc, TypeError):
	# True type mismatch: the Python type of the bound value is not compatible
	message = (
	'Received an argument of invalid type for column "%s". '
	"Expected: %s, Got: %s; (%s)"
	% (col_spec.name, col_spec.type, actual_type, exc)
	)
	elif isinstance(exc, (struct.error, OverflowError)):
	# Value is of the right general type but cannot be represented
	# in the target CQL type (e.g. numeric value out of range).
	message = (
	'Received an out-of-range or otherwise invalid value for column "%s". '
	"Expected CQL type: %s, Got value: %r (Python type: %s); (%s)"
	% (col_spec.name, col_spec.type, value, actual_type, exc)
	)
	else:
	# Fallback for any unexpected exception types that might be passed in
	message = (
	'Error binding value for column "%s". Expected: %s, Got: %s; (%s)'
	% (col_spec.name, col_spec.type, actual_type, exc)
	)