The Script Handler

The zoti_graph.script module is meant to help getting started with building an own transformation-based code synthesis flow following the ZOTI methodologies or principles. It contains some function drivers that may (or may not) be used when describing transformation scripts.

Script Handler

class Script(G: AppGraph, T=None, dump_prefix='.')

Transformation script handler. It storgit ses an application graph and (possibly) a data type handler and contains utilities for executing rules.

Parameters:

• G – a fully-constructed application graph

• T – (optional) a data type handler

• dump_prefix – path where intermediate results will be written to

Apart from altering the application graph as side effects, transformation rules are able to return byproducts. These byproducts are gradually stored and are accessible as class members baring the name of the applied rule. E.g., after applying a transformation TransSpec(foo) where:

def foo(G, **kwargs):
    # do something on G
    return 'bar'

the current script will have a new member foo containing the string 'bar'. Existing members with the same name are overriden.

classmethod from_pickle(path)

Loads a binary object containing a previously pickled script handler.

pickle(path)

Dumps the current state of the handler into a binary object.

sanity(rules: List[Callable])

Utility for checking a batch of sanity rules on different elements of the stored graph (see zoti_graph.appgraph.AppGraph.sanity()) based on their name formation:

• port_[name] are applied only on ports;

• edge_[name] are applied only on edges;

• node_[name] are applied only on regular nodes;

• in all other cases it applies the rule on the entire graph (i.e., the root node).

transform(rules: List[TransSpec])

Applies a sequence of graph transformation rules, each wrapped in a TransSpec container, upon an application graph. Each transformation function might generate byproduct results which will be stored in the handlers’s state (see class documentation above).

Whenever calling a transformation rule, the Script handler passes its entire state as keyword arguments, including the graph and all previous byproducts. This has two major implications:

• any transformation rule should be prepared to be called with unknown arguments (by padlocking it with **kwargs);

• data can be passed between transformations as byproducts;

• dependencies on previous transformations can be specified as aguments, e.g.:

  def foo(G, baz, **kwargs):
      # will fail if rule 'baz' has not been called before
      # or has not returned anything
  

OBS: graph alterations are permanent. If you want to store intermediate graphs this should be done in the transformation function by deep-copying the entire graph and returning it as a byproduct.

class TransSpec(func: ~typing.Callable, clean: ~typing.List[str] = <factory>, dump_tree: ~typing.Dict | None = None, dump_graphviz: ~typing.Dict | None = None, dump_nodes: bool = False, dump_prefix: str | None = None, dump_title: str | None = None)

Transformation specification wrapper. Extends the transformatiion with some control flags and arguments, e.g., useful when debugging.

func: Callable

the transformation function

clean: List[str]

list of names of previous transformations, whose byproducts should be completely removed from the handler’s state.

dump_tree: Dict | None = None

keyword-arguments sent to zoti_graph.io.draw_tree(). If left None, the tree structure will not be dumped.

dump_graphviz: Dict | None = None

keyword-arguments sent to zoti_graph.io.draw_graph(). If left None, the graph structure will not be dumped.

dump_nodes: bool = False

dump node info as text after transformation for debugging

dump_prefix: str | None = None

overrides the Script member with the same name.

dump_title: str | None = None

optional title for the dumped file. If left None it will be replaced by the function name.

Useful Exceptions

class ScriptError(what, obj=None, rule=None)

Exception handler for pretty errors, possibly containing positional information as provided by ZOTI-YAML and rule documentation.

Parameters:

• what – error message

• obj – object causing the error. Will be scanned for positional info.

• rule – the rule (i.e., function itself) where error was caused. Will be scanned for docstring.

class ContextError(what, obj=None, context='', context_obj=None)

Exception handler for pretty errors that happened within a context of another object, possibly containing positional information as provided by ZOTI-YAML.

Parameters:

• what – error message

• obj – object causing the error. Will be scanned for positional info.

• context – context message

• context_obj – object constituting the context of the error. Will be scanned for positional info.

class EntryError(what, obj=None)

Exception thrown when the information in a graph entry is not as expected