[issue46071] Graphlib documentation (edge direction)

[David Mc Dougall]

David Mc Dougall <dam1784 at g.rit.edu> added the comment:

> The argument passed is the predecessor form of the graph B -> A

where graph = {'A' : ['B']}

This is part that I'm objecting to. The form of the graph should be A -> B, not B -> A.

The issue with the current form is that you can not traverse the graph, at least not forwards. When I say traverse forwards I mean that you follow the edges in the direction of the arrows. If you look up 'A' in the current graph you get  all of the nodes that point  *to* A, but that doesn't help you get *from* A to anywhere else.

There are two conventions:
1) Graphs should be traverse-able, by following the arrows.
2) Topological sorting makes the arrows point to the right.

Convention #1 was broken to satisfy convention #2.

What is important about the topo-sort is that it makes all of the edges point in the *same* direction. It doesn't actually matter which direction that is. And credit where due, the library picked the more-useful direction. It was a pragmatic choice, driven by the real use case of dependency resolution.

But having the graph with arrows pointing in the wrong direction is going to cause endless confusion.

For an example of the confusion this causes, look at the API itself. The "add" method explicitly calls out the fact that you can add nodes with no predecessors. This is obviously also possible with the graph argument as it currently is.

> It is possible to add a node with no dependencies (predecessors is not provided)
   https://docs.python.org/3/library/graphlib.html#graphlib.TopologicalSorter.add

----------

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue46071>
_______________________________________