Reference

Core

ActionTree.execute(action, cpu_cores=None, keep_going=False, do_raise=True, hooks=None)

Recursively execute an Action’s dependencies then the action.

Parameters
  • action (Action) – the action to execute.

  • cpu_cores (int or None or UNLIMITED) – number of CPU cores to use in parallel. Pass None (the default value) to let ActionTree choose. Pass UNLIMITED to execute an unlimited number of actions in parallel (make sure your system has the necessary resources). Note: CPU cores are managed like any other Resource, and this parameter sets the availability of CPU_CORE for this execution.

  • keep_going (bool) – if True, then execution does not stop on first failure, but executes as many dependencies as possible.

  • do_raise (bool) – if False, then exceptions are not re-raised as CompoundException but only included in the ExecutionReport.

  • hooks (Hooks) – its methods will be called when execution progresses.

Raises

CompoundException – when do_raise is True and dependencies raise exceptions.

Return type

ExecutionReport

ActionTree.UNLIMITED = <object object>

The availability of an infinite Resource.

class ActionTree.Action(label, dependencies=[], resources_required={}, accept_failed_dependencies=False)

The main class of ActionTree. An action to be started after all its dependencies are finished. Pass it to execute().

This is a base class for your custom actions. You must define a do_execute(self, dependency_statuses) method that performs the action. The dependency_statuses argument is a dictionary whose keys are self.dependencies and values are their ActionStatus. Outputs and side-effects describes how its return values, the exceptions it may raise and what it may print is handled.

Actions, return values and exceptions raised must be picklable.

Parameters
property label

The label passed to the constructor.

add_dependency(dependency)

Add a dependency to be executed before this action. Order of insertion of dependencies is not important.

Parameters

dependency (Action) –

Raises

DependencyCycleException – when adding the new dependency would create a cycle.

property dependencies

The list of this action’s direct dependencies.

require_resource(resource, quantity=1)

Set the quantity of a certain Resource required to run this action.

Note that an action that requires more than a resource’s availability will be executed anyway. It will just not be executed in parallel with any other action that requires the same resource.

Parameters
property resources_required

The list of this action’s required resources and quantities required.

Return type

list(tuple(Resource, int))

property accept_failed_dependencies

True if the action will execute even if some of its dependencies failed.

Return type

bool

get_possible_execution_order(seen_actions=None)

Return the list of all this action’s dependencies (recursively), in an order that is suitable for linear execution. Note that this order is not unique. The order chosen is not specified.

class ActionTree.Resource(availability)

A resource that an Action can require for its execution. You can use resources to protect stuff that must not be used by more than N actions at the same time, à la semaphore. Like semaphorees, with an availability of 1, they become mutexes.

Resources Describes how to use this class.

Parameters

availability (int or UNLIMITED) – the number of instances available for this resource

ActionTree.CPU_CORE = <ActionTree._CpuCoreResource object>

A special Resource representing a processing unit. You can pass it to Action.require_resource() if your action will execute on more than one core.

Type

Resource

class ActionTree.Hooks

Base class to derive from when defining your hooks. execute() will call its methods when execution progresses.

action_pending(time, action)

Called when an action is considered for execution, i.e. at the beginning of execute().

Parameters
  • time (datetime.datetime) – the time at which the action was considered for execution.

  • action (Action) – the action.

action_ready(time, action)

Called when an action is ready to be executed, i.e. when all its dependencies have succeeded.

Parameters
action_canceled(time, action)

Called when an action’s execution is canceled, i.e. when some of its dependencies has failed.

Parameters
action_started(time, action)

Called when an action’s execution starts.

Parameters
action_printed(time, action, data)

Called when an action prints something.

Parameters
  • time (datetime.datetime) – the time at which the action printed the data.

  • action (Action) – the action.

  • data (str) – the data printed.

action_successful(time, action, return_value)

Called when an action completes without error.

Parameters
  • time (datetime.datetime) – the time at which the action completed.

  • action (Action) – the action.

  • return_value – the value returned by the action.

action_failed(time, action, exception)

Called when an action completes with an exception.

Parameters
  • time (datetime.datetime) – the time at which the action completed.

  • action (Action) – the action.

  • exception – the exception raised by the action

exception ActionTree.DependencyCycleException

Exception thrown by Action.add_dependency() when adding the new dependency would create a cycle.

exception ActionTree.CompoundException(exceptions, execution_report)

Exception thrown by execute() when dependencies raise exceptions.

property exceptions

The list of exceptions raised.

property execution_report

The ExecutionReport of the failed execution.

class ActionTree.ExecutionReport

Execution report, returned by execute().

class ActionStatus(pending_time)

Status of a single Action.

property status

The status of the action: SUCCESSFUL if the action succeeded, FAILED if the action failed, and CANCELED if the action was canceled because some of its dependencies failed.

property pending_time

The time when this action was considered for execution.

Return type

datetime.datetime

property ready_time

The time when this action was ready to execute. (None if it was canceled before being ready).

Return type

datetime.datetime or None

property cancel_time

The time when this action was canceled. (None if it was started).

Return type

datetime.datetime or None

property start_time

The time at the beginning of the execution of this action. (None if it was never started).

Return type

datetime.datetime or None

property success_time

The time at the successful end of the execution of this action. (None if it was never started or if it failed).

Return type

datetime.datetime or None

property return_value

The value returned by this action (None if it failed or was never started).

property failure_time

The time at the successful end of the execution of this action. (None if it was never started or if it succeeded).

Return type

datetime.datetime or None

property exception

The exception raised by this action (None if it succeeded or was never started).

property output

Everything printed (and flushed in time) by this action. (None if it never started, "" it if didn’t print anything)

Return type

str or None

property is_success

True if the execution finished without error.

Return type

bool

get_action_status(action)

Get the ActionStatus of an action.

Parameters

action (Action) –

Return type

ActionStatus

get_actions_and_statuses()

Get a list of actions and their statuses.

Return type

list(tuple(Action, ActionStatus))

ActionTree.SUCCESSFUL = 'SUCCESSFUL'

The ActionStatus.status after a successful execution.

ActionTree.FAILED = 'FAILED'

The ActionStatus.status after a failed execution where this action raised an exception.

ActionTree.CANCELED = 'CANCELED'

The ActionStatus.status after a failed execution where a dependency raised an exception.

class ActionTree.DependencyGraph(action)

A visual representation of the dependency graph, using Graphviz.

write_to_png(filename)

Write the graph as a PNG image to the specified file.

See also get_graphviz_graph() if you want to draw the graph somewhere else.

get_graphviz_graph()

Return a graphviz.Digraph of this dependency graph.

See also write_to_png() for the simplest use-case.

class ActionTree.GanttChart(report)

A visual representation of the timing of an execution.

write_to_png(filename)

Write the Gantt chart as a PNG image to the specified file.

See also get_mpl_figure() and plot_on_mpl_axes() if you want to draw the report somewhere else.

get_mpl_figure()

Return a matplotlib.figure.Figure of this Gantt chart.

See also plot_on_mpl_axes() if you want to draw the Gantt chart on your own matplotlib figure.

See also write_to_png() for the simplest use-case.

plot_on_mpl_axes(ax)

Plot this Gantt chart on the provided matplotlib.axes.Axes.

See also write_to_png() and get_mpl_figure() for the simpler use-cases.

Stock actions

Stock actions are predefined common tasks (manipulating the filesystem, calling an external program, etc.) They all specialize Action.

class ActionTree.stock.NullAction(label=None, *args, **kwds)

A stock action that does nothing. Useful as a placeholder for several dependencies.

@todoc

class ActionTree.stock.CallSubprocess(command, kwargs={}, label=<object object>, *args, **kwds)

A stock action that calls a subprocess.

@todoc

class ActionTree.stock.CreateDirectory(name, label=<object object>, *args, **kwds)

A stock action that creates a directory. No error will be raised if the directory already exists. If the directory to create is nested, intermediate directories will be created as well.

Parameters

name (str) – the directory to create, passed to os.makedirs().

@todoc

class ActionTree.stock.DeleteFile(name, label=<object object>, *args, **kwds)

A stock action that deletes a file. No error will be raise if the file doesn’t exist.

Parameters

name (str) – the name of the file to delete, passed to os.unlink().

@todoc

class ActionTree.stock.DeleteDirectory(name, label=<object object>, *args, **kwds)

A stock action that deletes a directory (recursively). No error will be raise if the directory doesn’t exist.

Parameters

name (str) – the name of the directory to delete, passed to shutil.rmtree().

@todoc

class ActionTree.stock.CopyFile(src, dst, label=<object object>, *args, **kwds)

A stock action that copies a file. Arguments are passed to shutil.copy().

Parameters
  • src (str) – the file to copy

  • dst (str) – the destination

@todoc

class ActionTree.stock.TouchFile(name, label=<object object>, *args, **kwds)

A stock action that touches a file. If the file already exists, its modification time will be modified. Else, it will be created, empty.

Note that the containing directory must exist. You might want to ensure that by adding a CreateDirectory as a dependency.

Parameters

name (str) – the name of the file to touch. Passed to open() and/or os.utime().

@todoc

class ActionTree.stock.Sleep(secs, label=<object object>, *args, **kwds)

A stock action that sleeps for a certain duration.

Parameters

secs (float) – seconds to sleep, passed to time.sleep().

@todoc