New submission from Ran Benita <r...@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@python
components: Documentation
messages: 382647
nosy: bluetech, docs@python
priority: normal
severity: normal
status: open
title: Improvements to graphlib.TopologicalSorter.static_order() documentation
versions: Python 3.10, Python 3.9
_______________________________________
Python tracker <rep...@bugs.python.org>
<https://bugs.python.org/issue42588>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe:
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
