Add bfs-search

[georgios-ts]

This commit implements a breadth_first_search that provides
the ability to insert callback functions at specified event points.
Python users should subclass retworkx.visit.BFSVisitor and overwrite
the appropriate callback functions.

Similar to #456

[mtreinish]

Overall this LGTM I'm looking forward to getting this and the dfs in retworkx. I just have a few questions and suggestions inline.

Also, sorry this has taken me so long to look at, I've been heads down on some qiskit-terra functionality and haven't had much time for retworkx reviews.

[coveralls]

Pull Request Test Coverage Report for Build 1472802387

• 139 of 141 (98.58%) changed or added relevant lines in 4 files are covered.
• No unchanged relevant lines lost coverage.
• Overall coverage decreased (-0.004%) to 98.413%

---

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
retworkx-core/src/traversal/bfs_visit.rs	73	75	97.33%

Totals
Change from base Build 1436778676:	-0.004%
Covered Lines:	10477
Relevant Lines:	10646

---

💛 - Coveralls

[mtreinish]

Thanks for the fast updates, I think this is basically ready now. Before approving I just have one inline question/comment before I'm ready to approve.

Also I was looking at coverage and I noticed a bunch of continue lines don't have coverage, for example: https://coveralls.io/builds/44296139/source?filename=retworkx-core%2Fsrc%2Ftraversal%2Fbfs_visit.rs#L247 is that an issue with the coverage collection or are we missing a path in the tests so that's not getting triggered.

[georgios-ts]

Also I was looking at coverage and I noticed a bunch of continue lines don't have coverage, for example: https://coveralls.io/builds/44296139/source?filename=retworkx-core%2Fsrc%2Ftraversal%2Fbfs_visit.rs#L247 is that an issue with the coverage collection or are we missing a path in the tests so that's not getting triggered.

Yeah, we miss some test paths, let me add some extra tests to cover these lines.

[georgios-ts]

@mtreinish
Actually thinking about this a bit more, to cover these lines we would need to raise PruneSearch in events where this would not really have any meaningful outcome (i.e the rest of the search will not be affected). So, I'm wondering if it's best to keep the continue statement and just add some dummy tests that will not really assert anything but will satisfy the coverage report or if we should replace continue with a panic as in Finish event.

[mtreinish]

I think having a test case that just runs like normal when PruneSearch is raised in those edge cases make sense to me. We just make it explicit the test is expected to work fine and we're just testing pathological edge cases. I don't think we need to panic there too.

[mtreinish]

LGTM thanks for updating this. The dispatch function is just missing the example from it's docstring after that's added I think this is ready to merge.

[mtreinish]

The example here is missing

[georgios-ts]

Oops, good catch! Added in e6123aa.