graphlib
--- グラフ構造を操作する機能¶
ソースコード: Lib/graphlib.py
- class graphlib.TopologicalSorter(graph=None)¶
ハッシュ可能 な頂点のグラフをトポロジカルソートする機能を提供します。
トポロジカル順序はグラフの頂点の線形順序で、頂点 u から 頂点 v への有向辺 u-> v 全てについて、頂点 u が頂点 v よりも前にくるような順序です。例えば、グラフの頂点が実行するタスクを表し、その辺があるタスクが別のタスクよりも前に実行されなければならないという制約を表す場合、トポロジカル順序は制約を満たすタスクの実行順序のシーケンスになります。トポロジカル順序が得られるのは、グラフが有向閉路を持たない、つまり有向非巡回グラフである場合でかつその時に限ります。
もしオプションの graph 引数が与えられた場合、その値は有向非巡回グラフを表す辞書でなければならず、辞書はそのキーがノードで、その値はキーのノードの先行ノードのイテラブルとなります(言い換えると、辞書の値はそのキーのノードを指す辺を持つノードのイテラブルです) 辺
add()
メソッドを使うことで、さらにノードを追加することができます。一般的に、与えられたグラフのソートの実行に必要なステップは以下のようになります:
TopologicalSorter
のインスタンスをオプションの初期グラフで生成します。さらにノードをグラフに追加します。
prepare()
をグラフ上で呼び出します。is_active()
がTrue
の間、get_ready()
によって返されたノード群をイテレートし、それらを処理します。ノードの処理が終わる都度、done()
を呼び出します。
すぐにグラフのノードをソートした結果が必要で、並行性が不要な場合、便利なメソッド
TopologicalSorter.static_order()
を直接呼び出すことができます:>>> graph = {"D": {"B", "C"}, "C": {"A"}, "B": {"A"}} >>> ts = TopologicalSorter(graph) >>> tuple(ts.static_order()) ('A', 'C', 'B', 'D')
このクラスは、簡単に準備が整ったノードの並列処理を行えるよう設計されています。例えば:
topological_sorter = TopologicalSorter() # Add nodes to 'topological_sorter'... topological_sorter.prepare() while topological_sorter.is_active(): for node in topological_sorter.get_ready(): # Worker threads or processes take nodes to work on off the # 'task_queue' queue. task_queue.put(node) # When the work for a node is done, workers put the node in # 'finalized_tasks_queue' so we can get more nodes to work on. # The definition of 'is_active()' guarantees that, at this point, at # least one node has been placed on 'task_queue' that hasn't yet # been passed to 'done()', so this blocking 'get()' must (eventually) # succeed. After calling 'done()', we loop back to call 'get_ready()' # again, so put newly freed nodes on 'task_queue' as soon as # logically possible. node = finalized_tasks_queue.get() topological_sorter.done(node)
- add(node, *predecessors)¶
新しいノードとその先行ノードをグラフに追加します。 node と predecessors のすべての要素は ハッシュ可能 でなければなりません。
同じ node 引数で複数回呼び出した場合、依存関係の集合は、それまでに指定した依存関係の和集合になります。
Можна додати вузол без залежностей (попередники не надаються) або надати залежність двічі. Якщо вузол, який не було надано раніше, включено до попередників, він буде автоматично доданий до графу без власних попередників.
prepare()
を呼び出した後にこのメソッドを呼び出すと、ValueError
を送出します。
- prepare()¶
Позначте графік як готовий і перевірте наявність циклів у ньому. Якщо буде виявлено будь-який цикл,
CycleError
буде викликано, алеget_ready()
все ще можна використовувати для отримання якомога більшої кількості вузлів, доки цикли не заблокують подальший прогрес. Після виклику цієї функції граф не можна змінити, і тому більше вузлів не можна додавати за допомогоюadd()
.
- is_active()¶
Повертає
True
, якщо можна досягти більшого прогресу, іFalse
в іншому випадку. Прогрес може бути досягнутий, якщо цикли не блокують розв’язку та або ще є готові вузли, які ще не повернувTopologicalSorter.get_ready()
, або кількість вузлів, позначенихTopologicalSorter.done()
, менша ніж число, яке повернувTopologicalSorter.get_ready()
.The
__bool__()
method of this class defers to this function, so instead of:if ts.is_active(): ...
このように簡単に記述できます:
if ts: ...
前もって
prepare()
を呼び出さずにこの関数を呼び出すとValueError
を送出します。
- done(*nodes)¶
Позначає набір вузлів, повернутий
TopologicalSorter.get_ready()
, як оброблений, розблоковуючи будь-якого наступника кожного вузла в nodes для повернення в майбутньому за допомогою викликуTopologicalSorter.get_ready()
.Викликає
ValueError
, якщо будь-який вузол у nodes вже було позначено як оброблений попереднім викликом цього методу або якщо вузол не було додано до графіка за допомогоюTopologicalSorter.add()
, якщо він викликається без викликуprepare()
або якщо вузол ще не повернутоget_ready()
.
- get_ready()¶
Повертає
кортеж
з усіма готовими вузлами. Спочатку він повертає всі вузли без попередників, і коли вони позначаються як оброблені за допомогою викликуTopologicalSorter.done()
, подальші виклики повертатимуть усі нові вузли, усі їхні попередники вже оброблені. Якщо неможливо більше досягти прогресу, повертаються порожні кортежі.前もって
prepare()
を呼び出さずにこの関数を呼び出すとValueError
を送出します。
- static_order()¶
Повертає об’єкт-ітератор, який виконуватиме ітерацію по вузлах у топологічному порядку. Під час використання цього методу не слід викликати
prepare()
іdone()
. Цей метод еквівалентний:def static_order(self): self.prepare() while self.is_active(): node_group = self.get_ready() yield from node_group self.done(*node_group)
Конкретний порядок, який повертається, може залежати від конкретного порядку, у якому елементи були вставлені в графік. Наприклад:
>>> ts = TopologicalSorter() >>> ts.add(3, 2, 1) >>> ts.add(1, 0) >>> print([*ts.static_order()]) [2, 0, 1, 3] >>> ts2 = TopologicalSorter() >>> ts2.add(1, 0) >>> ts2.add(3, 2, 1) >>> print([*ts2.static_order()]) [0, 2, 1, 3]
Це пов’язано з тим, що "0" і "2" знаходяться на одному рівні графіка (вони були б повернені під час того самого виклику
get_ready()
), і порядок між ними визначається за порядком вставлення.Якщо буде виявлено будь-який цикл, буде викликано
CycleError
.
Added in version 3.9.
例外¶
graphlib
モジュールは以下の例外クラスを定義します:
- exception graphlib.CycleError¶
Підклас
ValueError
, створенийTopologicalSorter.prepare()
, якщо в робочому графі існують цикли. Якщо існує кілька циклів, лише один невизначений вибір серед них буде повідомлено та включено до винятку.The detected cycle can be accessed via the second element in the
args
attribute of the exception instance and consists in a list of nodes, such that each node is, in the graph, an immediate predecessor of the next node in the list. In the reported list, the first and the last node will be the same, to make it clear that it is cyclic.