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 (str or None) – A string used to represent the action in GanttChart and DependencyGraph. Can be retrieved by label.
dependencies (list(Action)) – see add_dependency()
resources_required (dict(Resource, int)) – see require_resource()
accept_failed_dependencies (bool) – if True, then the action will execute even after some of its dependencies failed.

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

resource (Resource) –
quantity (int) –

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

time (datetime.datetime) – the time at which the action was ready.
action (Action) – the action.

action_canceled(time, action)¶

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

Parameters

time (datetime.datetime) – the time at which the action was canceled.
action (Action) – the action.

action_started(time, action)¶

Called when an action’s execution starts.

Parameters

time (datetime.datetime) – the time at which the action was started.
action (Action) – the action.

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