Repository navigation
Add a Python API page - #20
Conversation
docs/python.md documents run_lab, make_codec and run_pg with an example on small random vectors. tests/test_docs.py runs its python blocks in order, so the page breaks the build if it drifts from the code; the run_pg block needs a database and is only compiled.
|
Thanks for your first pull request. CI runs ruff, the tests on Python 3.10 to 3.13, the |
ahmad-codex
left a comment
There was a problem hiding this comment.
Checked every name, default and field on the page against lab.py, pg.py, recommend.py and codecs/. All correct, including the LabResult/PgPoint fields and the codec bit ranges. Ran the examples as written and got exactly the output shown. The doc test is a nice touch: no network, no Postgres, fast, and CI already picks it up through -m "not crosscheck". Tests and ruff pass locally.
Two optional nits: a couple of example lines are close to 120 chars (fine, but splitting the long prints would read better), and it might be worth noting in python_blocks that the "not tested" comment has to be on the line right above the fence. Approving.
What and why
Adds
docs/python.md, which documentsrun_lab,make_codecandrun_pgfor notebook use. It has a runnable example on ~2,000 small random vectors, tables of the arguments and result fields, the pipeline syntax (search[>rerank[:candidates]]), andfrom_lab/from_pgfor getting a recommendation. The README links to it, and CHANGELOG has an Unreleased entry.Closes #13
How it was tested
tests/test_docs.pyextracts the page's python blocks and runs them in order, so the page fails the build if it drifts from the code. Therun_pgexample needs a database, so it is marked<!-- not tested: needs Postgres -->and is only compiled. The runnable blocks take about 4 s. I also broke one attribute name in the page to confirm the test fails on drift, then restored it.uv run pytest -m "not crosscheck": 36 passed (34 before)uv run ruff check src tests benchmarksanduv run ruff format --check src tests benchmarks: passOnly run on the pinned Python locally, not the full 3.10-3.13 matrix.
Checklist
uv run ruff check src testsanduv run ruff format --check src testspassuv run pytest -m "not crosscheck"passespytest -m crosscheckpasses when a reference implementation exists (n/a, no codec change)docs/method.mdandCHANGELOG.mdupdated where behavior or numbers change (CHANGELOG entry added; no behavior change)