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:
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.
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:
resources_required

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

Return type:list(tuple(Resource, int))
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.

exceptions

The list of exceptions raised.

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.

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.

pending_time

The time when this action was considered for execution.

Return type:datetime.datetime
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
cancel_time

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

Return type:datetime.datetime or None
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
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
return_value

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

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
exception

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

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

Note: if the process fails, check_call() raises a subprocess.CalledProcessError, which cannot be pickled in Python 2. So, in that case, this action catches the original exception and raises a CalledProcessError.

@todoc

exception ActionTree.stock.CalledProcessError

Raised by CallSubprocess

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