[New-bugs-announce] [issue42588] Improvements to graphlib.TopologicalSorter.static_order() documentation

[Ran Benita]

New submission from Ran Benita <ran at unusedvar.com>:

One issue and one suggestion.

Issue:

The documentation of prepare() says:

> If any cycle is detected, CycleError will be raised

which is what happens. The documentation of static_order() says that static_order() is equivalent to:

def static_order(self):
    self.prepare()
    while self.is_active():
        node_group = self.get_ready()
        yield from node_group
        self.done(*node_group)

specifically it is said to call self.prepare(), and also says

> If any cycle is detected, CycleError will be raised.

But, this only happens when the result of static_order is *iterated*, not when it's called, unlike what is suggested by the code and the comment.

Ideally, I think the call should raise the CycleError already if possible; this way, only the call can be wrapped in a try/except instead of the entire iteration. But if not, it should be clarified in the documentation.


Suggestion:

The documentation of static_order() says

> Returns an iterable of nodes in a topological order. Using this method does not require to call TopologicalSorter.prepare() or TopologicalSorter.done().

I think the wording "does not require" still implies that they *can* be called, but really they can't. If prepare() is called before static_order(), then when static_order() is iterated, "ValueError: cannot prepare() more than once" is raised.

I suggest this wording:

Returns an iterable of nodes in a topological order. When using this method, TopologicalSorter.prepare() and TopologicalSorter.done() should not be called.

----------
assignee: docs at python
components: Documentation
messages: 382647
nosy: bluetech, docs at python
priority: normal
severity: normal
status: open
title: Improvements to graphlib.TopologicalSorter.static_order() documentation
versions: Python 3.10, Python 3.9

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