Merge pull request #1669 from graphistry/docs/fix-docs-ci-polars

ci(docs): install polars in the sphinx doc-test image

Author: lmeyerov

CHANGELOG.md

@@ -15,6 +15,7 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 ### Infrastructure
 
 - **dgx GB10 benchmark safety harness**: `benchmarks/dgx/{safe_run.sh, preflight.py, sitecustomize.py, local_run.sh}` — an RMM device-allocation cap + host-memory watchdog + preflight refusal + hard timeout for running GPU / large-graph benchmarks on the unified-memory GB10 box without OOM-wedging it. Developer/benchmark tooling only; no runtime or library behavior change.
+- **Docs CI: polars in the doc-test image (pinned)**: the Sphinx doc-example runner now installs `polars` (pinned to cooldown-safe versions) so `engine='polars'` documentation examples execute — and are SKIPPED, not failed, where polars is unavailable (e.g. the minimal-deps job, Python 3.14). Doc-build / CI only; no runtime or library change.
 
 ## [0.57.0 - 2026-06-28]
 

docs/docker/Dockerfile

@@ -23,7 +23,13 @@ COPY ../../graphistry /docs/graphistry
 # Install graphistry in editable mode so it's available for notebook execution
 RUN --mount=type=cache,target=/root/.cache/pip \
     python3 -m pip install -e .[docs] && \
-    python3 -m pip install pygraphviz igraph lark pytest && \
+    # Pin doc-test-only deps (not in .[docs]/the RTD lock) to cooldown-safe versions —
+    # uv-resolved at the repo's supply-chain anchor (exclude-newer 2026-05-14, matches
+    # requirements/rtd-py3.12.lock), so a plain pip build never pulls an unpinned latest
+    # (0-day) release. Regenerate: uv pip compile <(printf 'pygraphviz\nigraph\nlark\npytest\npolars')
+    #   --python-version 3.12 --exclude-newer <rtd-lock-anchor> --no-deps
+    # Follow-up (#1669): fold into a single hashed lock like RTD for transitive+hash pinning.
+    python3 -m pip install pygraphviz==1.14 igraph==1.0.0 lark==1.3.1 pytest==9.0.3 polars==1.40.1 && \
     python3 -m ipykernel install --sys-prefix --name python3
 
 # Step 5: Copy the build script and config files into the container

docs/test_doc_examples.py

@@ -245,10 +245,22 @@ def _extract_code_blocks(path: Path) -> List[Tuple[int, str, Marker]]:
     return blocks
 
 
+try:
+    import polars as _polars_probe  # noqa: F401
+    _POLARS_AVAILABLE = True
+except Exception:
+    _POLARS_AVAILABLE = False
+
+
 def _should_skip(code: str) -> Optional[str]:
     for pat in SKIP_PATTERNS:
         if pat in code:
             return pat
+    # engine='polars' examples run when polars is installed, but must be SKIPPED (not failed)
+    # where it isn't — e.g. the minimal-deps job, or Python 3.14 which has no polars wheel yet.
+    # (cudf examples are already covered by SKIP_PATTERNS above.)
+    if not _POLARS_AVAILABLE and ("engine='polars'" in code or 'engine="polars"' in code):
+        return "polars-not-installed"
     return None