refactor(python): wrap the compiled classes in typed, documented python classes

.github/workflows/docs.yml

@@ -7,6 +7,8 @@ on:
     paths:
       - docs/**
       - zensical.toml
+      # The Python API reference is generated from these docstrings.
+      - python/python/lance_csr/**
       # Pages include this example with --8<--.
       - crates/lance-csr/examples/**
       - .github/workflows/docs.yml

.github/workflows/python-test.yml

@@ -51,7 +51,7 @@ jobs:
         run: uv run --no-sync maturin develop
       - name: Run tests
         working-directory: python
-        run: uv run --no-sync pytest python/tests/ -v
+        run: uv run --no-sync pytest python/tests/ --doctest-modules python/lance_csr -v
 
   lint:
     runs-on: ubuntu-24.04

AGENTS.md

@@ -8,7 +8,7 @@
 - `python/python/tests/` stores functional tests; mirror new features with targeted cases here and in the corresponding Rust module.
 - `examples/` demonstrates Cypher usage; update or add examples when introducing new public APIs.
 - `docs/` is the Zensical documentation site (configured by `zensical.toml`); follow `docs/AGENTS.md`.
-- Keep the docs in step with the code. Any substantial code change (a new or changed Python method, parameter, return type, exception or Cypher feature, or a change in behaviour users can observe) updates the affected guide pages in the same pull request, and `docs/api-reference.md` whenever the Python API changes. That page is written by hand from `crates/lance-csr-python/src/`, so check every signature and statement against the code. Then run `uv run --project docs --locked zensical build --strict` and `uvx typos@1.26.0 .` (the spell check CI runs).
+- Keep the docs in step with the code. Any substantial code change (a new or changed Python method, parameter, return type, exception or Cypher feature, or a change in behaviour users can observe) updates the affected guide pages in the same pull request. The Python API reference (`docs/api-reference.md`) is generated from the docstrings and type hints of the public classes in `python/python/lance_csr/`, so a Python API change updates those docstrings, checked against the behaviour in `crates/lance-csr-python/src/`. Document Python behaviour there, not in Rust `///` comments on the bindings. Then run `uv run --project docs --locked zensical build --strict` and `uvx typos@1.26.0 .` (the spell check CI runs).
 
 ## Build, Test, and Development Commands
 - `cargo test --workspace` (from the repository root) runs the Rust tests; building needs `protoc`.

CONTRIBUTING.md

@@ -210,8 +210,9 @@ cargo fmt --all --check
 cd python && make test && make lint
 ```
 
-When you change user-facing behaviour or the Python API, update the affected guide pages and
-`docs/api-reference.md` in the same pull request, then run
+When you change user-facing behaviour or the Python API, update the affected guide pages and the docstrings
+of the Python classes in `python/python/lance_csr/` (which generate `docs/api-reference.md`) in the same
+pull request, then run
 `uv run --project docs --locked zensical build --strict` and `uvx typos@1.26.0 .`.
 
 ## Report a bug or suggest an improvement