Raise RuntimeError instead of PanicException when pruning on finish_vertex

[JuanPBedoya (juan52878911)]

Fixes #1383.

Raising PruneSearch from the finish_vertex event reached rustworkx-core, which panics because there is nothing left to prune once a vertex is finished. The resulting PanicException derives from BaseException, so it was not caught by a plain except Exception, and a panic message was printed to stderr next to the Python traceback:

thread '<unnamed>' panicked at rustworkx-core/src/traversal/dfs_visit.rs:270:25:
Pruning on the `DfsEvent::Finish` is not supported!
pyo3_runtime.PanicException: Pruning on the `DfsEvent::Finish` is not supported!

The issue proposes raising a RuntimeError instead, which is what this does. The event is checked in the PyO3 handlers, before the control flow value reaches the core, so the core never panics and the stderr message is gone as well. rustworkx-core is left untouched: its panic! stays as an assertion for Rust callers, where returning Prune on Finish really is a programming error.

The panic was reachable from all three traversals, not just DFS (dfs_visit.rs:270, bfs_visit.rs:243, dijkstra_visit.rs:283), so all three handlers are fixed.

I checked the whole event surface to make sure the change is neither too narrow nor too wide: every event of the three traversals, with both PruneSearch and StopSearch, on PyGraph and PyDiGraph. PruneSearch on finish_vertex is the only combination that panicked, pruning on every other event still prunes, and StopSearch is unaffected. DFS propagating StopSearch back to the caller is existing documented behaviour and is left alone.

Documentation

The docstrings for the three searches already noted that an exception was raised in that event but did not name the type, which is now RuntimeError. That note is duplicated in rustworkx/__init__.py, which is what help() and the published docs show, so both copies are updated. Those lines also referred to finish_vertex with :class: rather than :meth:, fixed in passing since they were being rewritten anyway.

Tests

24 tests across the six test_{bfs,dfs,dijkstra}_search.py files, in tests/graph/ and tests/digraph/:

• prune_finish_vertex — a RuntimeError is raised.
• prune_finish_vertex_mid_traversal — the visitor prunes on its second finish_vertex, which pins the exact finish order up to that point and shows the error is not raised eagerly.
• prune_finish_vertex_no_starting_point — same with source=None, so more than one component is walked.
• stop_search_finish_vertex — a guard that StopSearch in the same event is unaffected.

Reverting only the three handler files to main and rebuilding, 18 of the 24 fail with the old PanicException; the 6 stop_search_finish_vertex tests pass either way, which is what makes them useful as guards.

cargo test --workspace is 524 passed and the Python suite is 2418 passed / 32 skipped, with cargo fmt, cargo clippy --workspace --all-targets -- -D warnings, ruff format, ruff check, find_stray_release_notes.py and cargo doc -p rustworkx-core with -D warnings all clean.

[Coveralls (coveralls)]

Coverage Report for CI Build 33434805102

Coverage increased (+0.01%) to 94.702%

Details

• Coverage increased (+0.01%) from the base build.
• Patch coverage: 18 of 18 lines across 3 files are fully covered (100%).
• No coverage regressions found.

Uncovered Changes

No uncovered changes found.

Coverage Regressions

No coverage regressions found.

---

Coverage Stats

Relevant Lines:	20311
Covered Lines:	19235
Line Coverage:	94.7%
Coverage Strength:	961274.34 hits per line

---

💛 - Coveralls