Add custom iterator class for BFS successors return

[mtreinish]

This commit changes the return type of the bfs_successors function to be
a custom class BFSSuccessors. This new return class implements both the
sequence protocol and iterator protocol. This means that aside from
explicit type checking it should be backwards compatible with the list
being previously returned. It can be used with either index based access
or iterated over.

This should be more efficient for large graphs because instead of doing
the copy and type conversion and iterating over the entire nested Vec of
results it instead does it per access (either via __getitem__ or
__next__). It does add a small amount of overhead for smaller graphs but
it is minimal since the function returns in microseconds in such cases
so a 10-20% overhead is not a big dea).

It's worth noting while this defers the type conversion, it does not
defer execution like most python iterators normally do. When
bfs_successors is called it will still always fully traverse the graph.
However, in practice the bottleneck for the bfs_successor function
wasn't actually the graph traversal, but instead the type conversion.

Related to #71

[coveralls]

Pull Request Test Coverage Report for Build 358619898

• 18 of 18 (100.0%) changed or added relevant lines in 2 files are covered.
• No unchanged relevant lines lost coverage.
• Overall coverage increased (+0.03%) to 94.46%

---

Totals
Change from base Build 356454191:	0.03%
Covered Lines:	2660
Relevant Lines:	2816

---

💛 - Coveralls

[kdk]

This looks good. Out of curiosity, would it be more natural to implement either the sequence protocol (keeping the lazy copy and type conversion) or the iterator protocol? Implementing both seems better for backwards compatibility, but it seems like the differences in the two protocols might lead non-obvious behavior (see one comment below.)

[mtreinish]

This looks good. Out of curiosity, would it be more natural to implement either the sequence protocol (keeping the lazy copy and type conversion) or the iterator protocol? Implementing both seems better for backwards compatibility, but it seems like the differences in the two protocols might lead non-obvious behavior (see one comment below.)

That was my first thought on this PR too, and I started with just that. But IIRC the issue wass that just the sequence protocol doesn't actually work with iter(BFSSuccessors). But I was trying a couple of different things at once, and I might be misremembering. Let me try dropping the iter protocol and see what happens.

[mtreinish]

Ok, yeah I took a look at this locally and yeah we can remove the iter protocol implementation and it will still work. You'll need to call iter() around the return to use it as an iterator (which is probably where I got confused before). With that it works fine. I'll make this change in a sec (just need to clean up the docs).