Message382647
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. |
|
Date |
User |
Action |
Args |
2020-12-07 15:13:10 | bluetech | set | recipients:
+ bluetech, docs@python |
2020-12-07 15:13:10 | bluetech | set | messageid: <1607353990.94.0.818492776719.issue42588@roundup.psfhosted.org> |
2020-12-07 15:13:10 | bluetech | link | issue42588 messages |
2020-12-07 15:13:10 | bluetech | create | |
|