Add Python (pybind11) bindings + hello_search.py example

[DenisRaskovalov]

Summary

Optional CPython extension module that exposes the SearchPlusPlus core
to Python via pybind11, plus a Python example that mirrors
examples/hello_search/main.cpp line-for-line.

• Binding (python/src/searchplusplus.cpp) covers the v0.1 surface — Schema, Document, IndexWriter, IndexReader, Searcher, SearchResult, Hit. Python-side methods are snake_case. Status / Expected<T> failures raise ValueError / KeyError / IndexError / RuntimeError based on the underlying StatusCode, so callers get normal raise semantics instead of having to check .ok().

• Example (examples/python/hello_search.py) reproduces the C++ example's output exactly:

  inverted index           total=1
      b   score=1.9253
  bm25                     total=1
      c   score=1.3863
  title:tokenizer          total=1
      e   score=1.3863
  

• Off by default — SPP_BUILD_PYTHON=OFF. The regular build stays self-contained; no Python dev-header dependency unless you opt in.

• pybind11 added under a vcpkg python feature so vcpkg install only pulls it in when the bindings are actually requested. Justified in DESIGN.md against principle 2: header-only, ~200 KB, single-purpose, alternative is hand-rolling every method against the raw CPython C API.

Build

# macOS:  brew install pybind11
# Ubuntu: apt-get install python3-dev pybind11-dev
cmake --preset release -DSPP_BUILD_PYTHON=ON
cmake --build --preset release --target searchplusplus -j
PYTHONPATH=build/release/python python3 examples/python/hello_search.py

The README documents the one gotcha: don't build the bindings under the default (ASan) preset — ASan can't initialize when the .so is dlopen'd into a non-instrumented Python interpreter.

Test plan

• Local: extension module builds clean under the release preset (macOS, Apple Clang 21.0.0)
• Local: hello_search.py runs end-to-end and produces output byte-identical to the C++ example
• CI lanes stay green (bindings are off in CI; the only files exercised by CI here are the CMake option plumbing and the docs)

🤖 Generated with Claude Code