"graphlib" --- Functionality to operate with graph-like structures
******************************************************************

**ソースコード:** Lib/graphlib.py

======================================================================

class graphlib.TopologicalSorter(graph=None)

   Provides functionality to topologically sort a graph of *hashable*
   nodes.

   トポロジカル順序はグラフの頂点の線形順序で、頂点 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)

      Add a new node and its predecessors to the graph. Both the
      *node* and all elements in *predecessors* must be *hashable*.

      同じ node 引数で複数回呼び出した場合、依存関係の集合は、それまで
      に指定した依存関係の和集合になります。

      It is possible to add a node with no dependencies
      (*predecessors* is not provided) or to provide a dependency
      twice. If a node that has not been provided before is included
      among *predecessors* it will be automatically added to the graph
      with no predecessors of its own.

      "prepare()" を呼び出した後にこのメソッドを呼び出すと、
      "ValueError" を送出します。

   prepare()

      Mark the graph as finished and check for cycles in the graph. If
      any cycle is detected, "CycleError" will be raised, but
      "get_ready()" can still be used to obtain as many nodes as
      possible until cycles block more progress. After a call to this
      function, the graph cannot be modified, and therefore no more
      nodes can be added using "add()".

   is_active()

      Returns "True" if more progress can be made and "False"
      otherwise. Progress can be made if cycles do not block the
      resolution and either there are still nodes ready that haven't
      yet been returned by "TopologicalSorter.get_ready()" or the
      number of nodes marked "TopologicalSorter.done()" is less than
      the number that have been returned by
      "TopologicalSorter.get_ready()".

      このクラスの "__bool__()" メソッドはこの関数を呼び出すため、以下
      のようにする代わりに:

         if ts.is_active():
             ...

      このように簡単に記述できます:

         if ts:
             ...

      前もって "prepare()" を呼び出さずにこの関数を呼び出すと
      "ValueError" を送出します。

   done(*nodes)

      Marks a set of nodes returned by "TopologicalSorter.get_ready()"
      as processed, unblocking any successor of each node in *nodes*
      for being returned in the future by a call to
      "TopologicalSorter.get_ready()".

      Raises "ValueError" if any node in *nodes* has already been
      marked as processed by a previous call to this method or if a
      node was not added to the graph by using
      "TopologicalSorter.add()", if called without calling "prepare()"
      or if node has not yet been returned by "get_ready()".

   get_ready()

      Returns a "tuple" with all the nodes that are ready. Initially
      it returns all nodes with no predecessors, and once those are
      marked as processed by calling "TopologicalSorter.done()",
      further calls will return all new nodes that have all their
      predecessors already processed. Once no more progress can be
      made, empty tuples are returned.

      前もって "prepare()" を呼び出さずにこの関数を呼び出すと
      "ValueError" を送出します。

   static_order()

      Returns an iterator object which will iterate over nodes in a
      topological order. When using this method, "prepare()" and
      "done()" should not be called. This method 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)

      The particular order that is returned may depend on the specific
      order in which the items were inserted in the graph. For
      example:

         >>> 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]

      This is due to the fact that "0" and "2" are in the same level
      in the graph (they would have been returned in the same call to
      "get_ready()") and the order between them is determined by the
      order of insertion.

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

   バージョン 3.9 で追加.


例外
====

"graphlib" モジュールは以下の例外クラスを定義します:

exception graphlib.CycleError

   Subclass of "ValueError" raised by "TopologicalSorter.prepare()" if
   cycles exist in the working graph. If multiple cycles exist, only
   one undefined choice among them will be reported and included in
   the exception.

   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.
