GH-143948: Explain graphlib's cycle-finding code

[tim-one]

gh-143948: Explain graphlib's cycle-finding code

Long overdue comments explaining what's going on, and why. No code changes, just comments.

[tim-one]

@picnixz, I reworded things to address some of your comments (& thanks!). I'm not inclined to "do something" about the others, though: this is intended to record what actually happened and the decisions actually made. The time for rethinking those ended when the code shipped and users appeared happy with it. If you would like to, .e..g,, see a WCC detector instead, that belongs in a different PR.

[picnixz]

Thanks! those changes look good enough for me. As for WCC I only wanted to mention them in case you wanted to have this distinction somewhere but I am also fine with not mentioning them at all!

For more general graph algorithms I think we should rather suggest using networkx in the docs.

[tim-one]

Thanks! Your review was appreciated, and I think the comments are better for it.

We're agreed that there was no ambition here to compete with networkx. At the time, multiple long-time Python users seemed simultaneously to stumble into a need for an "incrementaal" topsort to drive long-running multiprocessing programs. Nothing really suitable seemed to exist, and "how do you write a topsort in Python?" is pretty much a FAQ (on, e.g., StackOverflow),.

So we came with a design that can be used easily and safely in a concurrent environment (the top-sorter itself is single-threaded), but can also be used in "give me the whole linear order at once" mode for simple uses.

The problem was that it initially lived in functools. Where nobody would ever find it. So we (at least Pablo and I) created a new module for it. Our ambitions ended then ;-)