Closed kevinhartman closed 3 months ago
Changes Missing Coverage | Covered Lines | Changed/Added Lines | % | ||
---|---|---|---|---|---|
src/lib.rs | 13 | 22 | 59.09% | ||
rustworkx-core/src/graph_ext/mod.rs | 3 | 16 | 18.75% | ||
rustworkx-core/src/err.rs | 0 | 16 | 0.0% | ||
rustworkx-core/src/graph_ext/contraction.rs | 177 | 235 | 75.32% | ||
<!-- | Total: | 243 | 339 | 71.68% | --> |
Files with Coverage Reduction | New Missed Lines | % | ||
---|---|---|---|---|
src/shortest_path/all_pairs_bellman_ford.rs | 6 | 95.53% | ||
<!-- | Total: | 6 | --> |
Totals | |
---|---|
Change from base Build 9190944049: | -0.5% |
Covered Lines: | 16973 |
Relevant Lines: | 17680 |
This should be ready for another look. Thanks for the review @mtreinish!
EDIT: On the topic of a prelude
, I think that's a good idea, but not even petgraph
pulls in their visit
stuff via their prelude
, so I think we ought to think that through separately from this PR.
EDIT: On the topic of a prelude, I think that's a good idea, but not even petgraph pulls in their visit stuff via their prelude, so I think we ought to think that through separately from this PR.
Sure, I agree. We can think about a rustworkx core prelude in a follow up for 0.16.0. I'm not sure exactly what we'd want to put it in it.
As part of #1121, this PR is meant as a proposal for a few patterns we might follow to bring
rustworkx-core
up to parity with our Python API.To demonstrate these patterns, I've ported
contract_nodes
andhas_parallel_edges
fromPyGraph
andPyDiGraph
torustworkx-core
, making the functions available for all stablepetgraph
graphs (chosen as "complex" and "simple" examples, respectively).Extension traits
The primary pattern proposed here is to provide traits for the various graph methods of
Py(Di|)Graph
worth porting to core, along with implementations for applicablepetgraph
graph types.To aid in discoverability, we can also expose modules intended for import via
*
that bring all supported extension methods into scope for the graph type. For example, we can import all graph extensions as follows (which, at least in the CLion IDE, adds per-graph compatible methods to code completion):Node contraction
To see how this idea works with a complex example, I've ported
contract_nodes
fromPy(Di|)Graph
. To do this, we introduce 4 different traits:ContractNodesUndirected
,ContractNodesSimpleUndirected
,ContractNodesDirected
, andContractNodesSimpleUndirected
.We need this many because each of the methods between
ContractNodes(Un|Di)rected
andContractNodesSimple(Un|Di)rected
has a different signature and return type (since each has a different set of possible errors).Error interface
In #1124 we started discussing how the core's error interface ought to look. Originally, I proposed that we should aim to have a single error type returned by all core functions which may fail. However, I see now that this would have been somewhat of a Rust anti-pattern: it's generally encouraged to have error types which can indicate multiple failure cases, but it's not proper for functions to return error types with variants that can never happen in the given function's execution.
Instead, we define unique error enum types for each function to encapsulate exactly the error set it may return. For example, we introduce two error types
ContractError
andContractSimpleError
for node contraction, since only simple contractions can fail due to an edge merge issue.For errors, I'd propose putting all error types within
src/err.rs
. These can then be imported internally by extension trait implementations in thegraph
module, as well as by top-level functions outside it.On the Python-side, we can implement
From<...>
forRxPyErr
to automatically map each error type to a Python exception. This is done for bothContractError
andContractSimpleError
. See the docstring forRxPyErr
for more detail.Integration testing
I've added a new folder
tests/graph_ext
which contains amain.rs
file. Any modules registered there get automatically picked up and included in the same integration testing executable. For now, there's a filecontraction.rs
which contains modules for testing againstStableGraph
andGraphMap
(the two stable graph types inpetgraph
). Additional algorithms ported tograph_ext
should be added to this folder.Other
NodeRemovable
, which we've been needing for a while. It's similar to theBuild
trait provided bypetgraph
, but provides node removal.graph
module has been added to house our extension methods. Top-level functions can still make sense, and I don't propose we move existing ones. But perhaps for some, we ought to consider exposing them as extensions in parallel for user convenience.Todo
contract_nodes
andhas_parallel_edges
to core.