Skip to content

docs(gfql): make every quick-reference example run on pandas and Polars (#2169) - #2170

Open
lmeyerov wants to merge 2 commits into
masterfrom
docs/gfql-cheatsheet-predicates-2169
Open

lmeyerov wants to merge 2 commits into
masterfrom
docs/gfql-cheatsheet-predicates-2169

Conversation

@lmeyerov

Copy link
Copy Markdown
Contributor

Closes #2169. Keeps #967 (restoring local callables) open.

Problem

The GFQL cheatsheet recommended n({"age": lambda x: x > 30}), which validation rejects on pandas and Polars with GFQLTypeError E201. The docs example audit missed it for two reasons:

  • its RST regex only matched .. code-block:: at column zero, so blocks nested under bullets were never extracted: 50 of 56 in quick.rst, 58 of 407 across GFQL docs;
  • bare matchers like n({...}) only construct an AST and never execute.

Changes

  • quick.rst: declarative predicates (gt, lt, between) replace callables; let() examples select bindings with output= (results never had per-binding columns); remote() shown as a let() binding, since a plain-chain remote step raises NotImplementedError; pandas-only .empty replaced with len(...); the engine section states that engine='auto' runs Polars-unsupported features (query= strings, same-path where=) on pandas and returns pandas frames, while engine='polars' raises; stale xfail removed; placeholder and server-dependent blocks marked doc-test: skip.
  • docs/test_doc_examples.py: indent-aware RST extractor. On every other GFQL doc it yields a strict superset of the old blocks with identical markers. New test executes every runnable quick.rst example on a pandas-bound and a Polars-bound graph and requires identical rows, with explicit expected rows for the predicate examples. A pandas result under auto is accepted only when explicit engine='polars' refuses the same matcher.
  • graphistry/tests/compute/test_callable_filter_rejection.py: pins structured E201 rejection of callables in node filters, edge matches and destination matches, on both engines.

No runtime or serialization change.

Validation (dgx-spark, image test-rapids-official:26.02-gfql-polars, polars 1.35.2)

  • pytest docs/test_doc_examples.py: 24 passed, 13 skipped. 31 quick.rst examples execute on both engines with matching rows.
  • Negative control: restoring the lambda example fails the new test on both engines with E201.
  • test_callable_filter_rejection.py: 6 passed.
  • Remote let() examples reach Must call login() first, not NotImplementedError.
  • ruff clean; comment-density and type-hygiene guards OK.

Limits: the first Cypher example (:Person/:FOLLOWS) runs with row parity but returns no rows on the shared fixture. GPU, remote and compute_cugraph examples stay auto-skipped. The same wrong let() access pattern also appears in skip-marked blocks in overview.rst, about.rst and the spec docs; that is tracked separately.

🤖 Generated with Claude Code

…rs (#2169)

The cheatsheet recommended callable predicates (n({"age": lambda x: x > 30}))
that validation rejects on every engine. The docs example audit never caught
it: its RST regex only matched code blocks at column zero, so 50 of 56
quick.rst blocks (58 of 407 across GFQL docs) were never extracted, and bare
matchers only build an AST.

- quick.rst: declarative predicates (gt, lt, between) replace callables;
  let() examples select bindings with output=; remote() shown as a let()
  binding (a plain-chain remote step raises NotImplementedError); pandas-only
  .empty replaced; engine section notes what auto runs on pandas for Polars
  input; stale xfail removed; placeholder/remote blocks marked skip.
- docs/test_doc_examples.py: indent-aware RST extractor (strict superset of
  the old blocks and markers); new test executes every runnable quick.rst
  example on a pandas-bound and a Polars-bound graph, requires identical
  rows, explicit expected rows for the predicate examples, and accepts a
  pandas result under auto only when engine='polars' refuses the matcher.
- Product test pins structured E201 rejection of callables (#967 stays open).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Its polars params need polars, which only test-polars installs; the lane
completeness gate requires the file in POLARS_TEST_FILES.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs(gfql): cheatsheet recommends callable predicates that validation rejects

1 participant