graphlib — Functionality to operate with graph-like structures

Código fuente: Lib/graphlib.py

---

class graphlib.TopologicalSorter(graph=None)

Provides functionality to topologically sort a graph of hashable nodes.

Un ordenamiento topológico es un ordenamiento lineal de los vértices en un grafo de modo que para cada arista dirigida u -> v desde el vértice u al vértice v, el vértice u viene antes del vértice v en el ordenamiento. Por ejemplo, los vértices del grafo pueden representar tareas a realizar y las aristas pueden representar restricciones de que una tarea debe realizarse antes que otra; en este ejemplo, un ordenamiento topológico es solo una secuencia válida para las tareas. Es posible un ordenamiento topológico completo si y solo si el grafo no tiene ciclos dirigidos, es decir, si es un grafo acíclico dirigido.

Si se proporciona el argumento opcional graph, este debe ser un diccionario que represente un grafo acíclico dirigido donde las claves son nodos y los valores son iterables de todos los predecesores de ese nodo en el grafo (los nodos que tienen las aristas que apuntan al valor clave). Se pueden agregar nodos adicionales al grafo utilizando el add() method.

En el caso general, los pasos necesarios para realizar el ordenamiento de un grafo son los siguientes:

• Cree una instancia TopologicalSorter con un grafo inicial opcional.

• Agregue nodos adicionales al grafo.

• Llame a prepare() en el grafo.

• Mientras is_active() is True, itere sobre los nodos retornados por get_ready() y procéselos . Llame a done() en cada nodo a medida que finaliza el procesamiento.

En caso de que sólo se requiera una ordenación inmediata de los nodos del grafo y no haya paralelismo, se puede utilizar directamente el método de conveniencia TopologicalSorter.static_order()

>>> graph = {"D": {"B", "C"}, "C": {"A"}, "B": {"A"}}
>>> ts = TopologicalSorter(graph)
>>> tuple(ts.static_order())
('A', 'C', 'B', 'D')

La clase está diseñada para soportar fácilmente el procesamiento en paralelo de los nodos a medida que estén listos. Para la instancia:

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.

Si se llama varias veces con el mismo argumento del nodo, el conjunto de dependencias será la unión de todas las dependencias pasadas.

Es posible añadir un nodo sin dependencias (no se proporciona predecessors) o proporcionar una dependencia dos veces. Si un nodo que no se ha proporcionado antes se incluye entre los predecessors, se añadirá automáticamente al grafo sin predecesores propios.

Provoca ValueError si se llama después de prepare().

prepare()

Marca el grafo como terminado y comprueba si existen ciclos en el grafo. Si se detecta algún ciclo, se lanzará CycleError, pero se puede seguir utilizando get_ready() para obtener tantos nodos como sea posible hasta que los ciclos bloqueen más el progreso. Después de una llamada a esta función, el grafo no puede ser modificado, y por lo tanto no se pueden añadir más nodos utilizando add().

is_active()

Retorna True si se puede avanzar más y False en caso contrario. Se puede avanzar si los ciclos no bloquean la resolución y, o bien todavía existen nodos listos que aún no han sido retornados por TopologicalSorter.get_ready() o el número de nodos marcados con TopologicalSorter.done() es menor que el número que han sido retornados por TopologicalSorter.get_ready().

The __bool__() method of this class defers to this function, so instead of:

if ts.is_active():
    ...

es posible hacer simplemente:

if ts:
    ...

Lanzar ValueError si se llama sin llamar previamente a prepare().

done(*nodes)

Marca un conjunto de nodos retornados por TopologicalSorter.get_ready() como procesados, desbloqueando cualquier sucesor de cada nodo en nodes para ser retornado en el futuro por una llamada a TopologicalSorter.get_ready().

Lanza ValueError si algún nodo de nodes ya ha sido marcado como procesado por una llamada anterior a este método o si un nodo no fue añadido al grafo usando TopologicalSorter.add(), si se llama sin llamar a prepare() o si el nodo aún no ha sido retornado por get_ready().

get_ready()

Retorna una tupla con todos los nodos que están listos. Inicialmente retorna todos los nodos sin predecesores, y una vez que éstos se marcan como procesados llamando a TopologicalSorter.done(), las llamadas posteriores devolverán todos los nuevos nodos que tengan todos sus predecesores ya procesados. Una vez que no se puede avanzar más, se retornan tuplas vacías.

Lanzar ValueError si se llama sin llamar previamente a prepare().

static_order()

Retorna un iterable de nodos en un ordenamiento topológico. El uso de este método no requiere llamar a TopologicalSorter.prepare() o TopologicalSorter.done(). Este método es equivalente a:

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

El orden concreto que se retorna puede depender del orden específico en que se insertaron los elementos en el grafo. Por ejemplo:

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

Esto se debe a que «0» y «2» están en el mismo nivel en el gráfico (habrían sido retornados en la misma llamada a get_ready()) y el orden entre ellos está determinado por el orden de inserción.

Si se detecta algún ciclo, se lanzará CycleError.

Added in version 3.9.

Excepciones

El módulo graphlib define las siguientes clases de excepción:

exception graphlib.CycleError

Subclase de ValueError planteada por TopologicalSorter.prepare() si existen ciclos en el grafo de trabajo. Si existen múltiples ciclos, sólo se informará de una elección indefinida entre ellos y se incluirá en la excepción.

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.