perf: replace KeyError exception with dict.get() in BoundStatement.bind()

[mykaul]

Summary

Replace try/except KeyError with dict.get() + sentinel pattern in the per-column binding loop of BoundStatement.bind(). This loop runs once per column per execute() call for dict-style bindings, making it a hot path. Using dict.get() avoids the overhead of raising and catching KeyError for every missing/optional column.

The sentinel object (_BIND_SENTINEL) is necessary to distinguish a missing key from an explicit None value in the bound dict.

A type(values_dict) is dict check gates the fast path so that dict subclasses with custom __missing__ methods continue to work via the original try/except fallback.

Benchmark results

Column-lookup loop (10 columns, bind() hot path, protocol v4):

Scenario	Before (try/except)	After (dict.get())	Change
All 10 keys present	244 ns	366 ns	1.50x slower
50% keys missing (5/10)	605 ns	395 ns	1.53x faster
All keys missing (0/10)	1,049 ns	413 ns	2.54x faster

Note: When all keys are present (common case), try/except is faster because no exceptions are raised and the overhead is minimal. The dict.get() path adds overhead from the method call and sentinel comparison. The benefit materializes when columns are missing (partial binds with protocol v4+ UNSET_VALUE), where avoiding exception creation/handling gives a significant speedup.

Testing

• Added test_dict_subclass_missing_value tests for both v3 and v4 protocol versions to verify dict subclass __missing__ semantics are preserved
• All 665 unit tests pass (38 skips)

[Copilot]

Pull request overview

Improves the performance of dict-style parameter binding in BoundStatement.bind() by avoiding KeyError exception handling in the per-column binding loop, which is on a hot path during execute() for prepared statements.

Changes:

• Introduces a private sentinel (_BIND_SENTINEL) to distinguish “missing key” from an explicit None.
• Replaces try/except KeyError with dict.get(..., sentinel) in the dict-binding loop to avoid exception overhead.

---

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

[mykaul]

Review of Copilot's Comments

Comment 1: Module-level _BIND_SENTINEL exposure

Copilot's concern: The sentinel could be accidentally used by callers.

Assessment: Low severity, mostly noise. The _ prefix is the standard Python convention for private objects. Moving it inside bind() would create a new object() on every call to a hot path — counterproductive for a performance PR. The suggestion to use UNSET_VALUE instead would complicate the logic with separate v3/v4 code paths for marginal benefit.

Comment 2: dict.get() doesn't call __missing__

Copilot's concern: Switching from values_dict[col.name] (which triggers __missing__ for subclasses like defaultdict) to values_dict.get() is a behavior change.

Assessment: Technically correct, but negligible practical impact. Using a defaultdict for binding parameters would be unusual and arguably a misuse — it would silently provide defaults for missing columns instead of raising errors. No evidence in the codebase or tests that __missing__-implementing subclasses are used here.

Additional Observations

1. The optimization is sound — avoiding try/except KeyError on a hot path is a reasonable micro-optimization.
2. No bugs introduced — the new logic correctly handles all three cases (key present, key missing on v4+, key missing on v3). Existing unit tests cover these paths.
3. _BIND_SENTINEL export is a non-issue — no __all__ in the module, and the _ prefix excludes it from wildcard imports.
4. Missing benchmark data — the PR would be strengthened by including before/after timings, though this isn't blocking.

[mykaul]

Closing in favor of PR #749, which replaces the entire Python bind loop with a Cython serializer fast path — making this Python-level dict.get() optimization largely moot. Benchmarks also showed a 1.5x regression in the most common case (all keys present), which further reduces the value of this change.