Python Interfacing

In this tutorial we will work through creating a workflow for a project called mango. The files will be added gradually as we build up our understanding of SANE workflows.

We will be recreating the workflow created in the JSON Interface tutorial, however you do not need to go through that tutorial first.

Hint

SANE workflows tries to keep the python usage and JSON representation as as similar as possible. What you learn in one tutorial will translate smoothly to the other.

Additionally, the JSON and python interfaces can be used in tandem within workflows.

Preface

The python interface of SANE workflows offers a well documented API with type hints if your development environment supports it.

Starting within the python interface opens up a world of possibilities in complex workflow design, but we shall keep it simple for now until the later Advanced Topics.

Attention

Before we begin, it is important to understand that to get the Orchestrator to interact with our python code, we should use @sane.register decorator.

If you are unfamiliar with decorators, that is okay - it is not critically necessary to understand them make use of SANE.

Orchestrator

We should only use the the Orchestrator orch.ui to interact with the instance we are handed in by the @sane.register decorator.

The same advice of using the User Interface generally goes for all classes, but especially the Orchestrator.

Hint

We only need @sane.register on the calls that we want the Orchestrator to directly call. Any other helper functions or classes we need can be written normally.

Let’s take a look at the @sane.register to see how to use it.

Quick Reference (click to open/close)

As we can see, our main interaction with SANE will be via functions with this @sane.register syntax above the function itself, where the function takes a single required positional argument (this will be the Orchestrator)

import sane

@sane.register
def workflow( orch ):
  # hmmm.. what now..?

Hosts

To begin our workflow, let’s create the .sane/mango/hosts/forest.py file and make a host in this file.

.sane/
└── mango
    └── hosts
        └── forest.py

We will start by creating a Host object and adding it to the Orchestrator.

.sane/mango/hosts/forest.py

import sane

@sane.register
def create_forest_host( orch ):
  forest = sane.Host( "forest" )
  orch.add_host( forest )

Important

For objects to show up in the workflow you MUST add them to the Orchestrator instance provided (orch). Otherwise, your function will just create an object and “leave” it there doing nothing after returning from the function call.

You can add to the orch at any time, before or after configuring your Host or Action, but the object must be added eventually. It is recommended to add your object just after creation so that any internal logic (i.e. logging) can be setup immediately.

As far as creating a host we are basically done… Well, not really. It is a valid host, but it does not provided much. Additionally, when running a workflow, the expectation is that any Action will always run in an Environment, even if one is not needed. Thus, hosts must provide at least one Environment to even be somewhat useful.

Let’s continue to flesh out this Host.

If you click on the class name you will be taken to the API reference documentation, or alternatively click this Host host.ui link to see the API calls we care about. There are quite a few, so to start simple we will focus on Host.add_resources() and Host.add_environment().

Resources & Environments

Take a quick look at the API documentation for Host.add_resources():

Quick Reference (click to open/close):

We see that it takes a dict that uses sane.resources.Resource syntax. The simple explanation is that the resource must be a non-negative integer followed by optional binary scaling ( ‘k’ : 1024, ‘m’ : 1024 ², and so on), and an optional unit designator.

The simple explanation is that the resource must be a non-negative integer followed by optional binary scaling ( ‘k’ : 1024, ‘m’ : 1024 ², and so on), and an optional unit designator.

So we have a forest Host and want to add resources for our mango project workflow… Let’s add "trees" (these could nominally be "cpus" or whatever resource your Action would take to run):

.sane/mango/hosts/forest.py

import sane

@sane.register
def create_forest_host( orch ):
  forest = sane.Host( "forest" )
  orch.add_host( forest )

  forest.add_resources( { "trees" : 12 } )

Next, we need an Environment to work with.

Important

Currently, actions ALWAYS need to run with an Environment set up. Therefore, hosts must have at least one Environment declared that isn’t the base_env

If we look at the Environment env.ui we can see what function calls are available to use.

Quick Reference (click to open/close)

For demonstrative purposes, we will say that our environments have different GROWTH_RATE values can be used within the workflow.

Once again, keeping things simple, we will focus only on the necessary functions to get this workflow going. We will be using the Environment.setup_env_vars() method, then after Host.add_environment().

Our final file setup should look something like so:

.sane/mango/hosts/forest.py

import sane

@sane.register
def create_forest_host( orch ):
  forest = sane.Host( "forest" )
  orch.add_host( forest )

  forest.add_resources( { "trees" : 12 } )

  valley = sane.Environment( "valley" )
  river = sane.Environment( "river" )

  valley.setup_env_vars( "set", "GROWTH_RATE", 85 )
  river.setup_env_vars( "set", "GROWTH_RATE", 65 )

  forest.add_environment( valley )
  forest.add_environment( river )

We now have a functional host. However, it can’t do a whole lot without an Action to exercise the host and its environments. If we were to run this host, we would get some lackluster output:

sane_runner -p .sane/ --run

2025-12-07 20:36:10 INFO     [sane_runner]            Logging output to /home/aislas/mango/log/runner.log
2025-12-07 20:36:10 INFO     [orchestrator]           Searching for workflow files...
2025-12-07 20:36:10 INFO     [orchestrator]             Searching .sane/ for *.json
2025-12-07 20:36:10 INFO     [orchestrator]             Searching .sane/ for *.jsonc
2025-12-07 20:36:10 INFO     [orchestrator]             Searching .sane/ for *.py
2025-12-07 20:36:10 INFO     [orchestrator]               Found .sane/mango/hosts/forest.py
2025-12-07 20:36:10 INFO     [orchestrator]           Loading python file .sane/mango/hosts/forest.py as 'mango.hosts.forest'
2025-12-07 20:36:10 INFO     [sane_runner]            No actions selected
...help info...

Tip

This output can be reproduced by using the source repo example found at /home/aislas/frameflow/docs/examples/mango/python_basic_host/.sane

The default search patterns found our file and loaded it, but nothing was done since no actions were found.

Actions

Let’s now try to create our first python-based Action!

We will create the .sane/mango/actions/grow.py file, as well as create a helper script at .sane/mango/scripts/grow.sh:

.sane/
└── mango
    ├── actions
    │   └── grow.py
    ├── hosts
    │   └── forest.py
    └── scripts
        └── grow.sh

We will start by creating our .sane/mango/actions/grow.py file:

.sane/mango/actions/grow.py

import sane

@sane.register
def create_grow_action( orch ):
  grow = sane.Action( "grow_action" )
  orch.add_action( grow )

  #...

Similar to the Host creation, take a look at the Action action.ui to get an idea of the API available to use. Most important to us will be:

config (config["command"] and config["arguments"] since we are using the default Action.run())
environment
add_dependencies()
add_resource_requirements()

We shall go over the relevance of each of these.

`config`

Arguably the most versatile field in the default Action, this generic dict is meant to hold anything picklable that your action may need in running. Later (during Attribute Dereferencing) we will learn to more effectively use this general data container.

For now, the main use is in the config["command"] and config["arguments"] keys which are used by the default Action.run(). As their names imply, during Action execution, the config["command"] and config["arguments"] will be used as the command and arguments to execute for that action, respectively.

We are going to use the helper script located at .sane/mango/scripts.grow.sh to perform our main logic. This thereby allows us to have an Action with customizable execution without needing to write Custom Actions. The path we use to the script should be a relative path from the working directory, in this case ./. Only use absolute paths for scripts that will always be in the same place (e.g. host scripts)!

Let’s quickly modify our .sane/mango/actions/grow.py:

.sane/mango/actions/grow.py

import sane

@sane.register
def create_grow_action( orch ):
  grow = sane.Action( "grow_action" )
  orch.add_action( grow )

  grow.config["command"]   = ".sane/mango/scripts/grow.sh"
  grow.config["arguments"] = [ 4 ] # this must be a list

As for the contents of .sane/mango/scripts/grow.sh let’s use:

.sane/mango/scripts/grow.sh

#!/usr/bin/bash
NTREES=$1
echo "Growing with $NTREES trees with $GROWTH_RATE% growth rate..."

for i in $(seq 1 $NTREES ); do
  NMANGOS=$(( ($RANDOM % 10) * $GROWTH_RATE / 100 + 1 ))
  echo "  Tree $i grew $NMANGOS mangos!"
  echo $NMANGOS > mango_tree_$i.txt
done

Note

The string provided to config["command"] must be an executable. Commands from your PATH will work, but if you use a script it must have the executable property. Try running:

chmod +x <command script>

if you are having issues getting your Action to run your config["command"]

`environment`

Each Action must run within an Environment, however the actual object instance is owned by the Host, as each host is left to implement that specific environment.

The communication from Action to Host about which environment to use is facilitated by a str match between Action.environment and Environment.name (or Environment.aliases) within the Host.environments.

Let’s update our .sane/mango/actions/grow.py again, saying we need a "valley" environment (recall forest.py):

.sane/mango/actions/grow.py

import sane

@sane.register
def create_grow_action( orch ):
  grow = sane.Action( "grow_action" )
  orch.add_action( grow )

  grow.config["command"]   = ".sane/mango/scripts/grow.sh"
  grow.config["arguments"] = [ 4 ] # this must be a list

  grow.environment = "valley"

`add_resource_requirements()`

Quick Reference (click to open/close)

Any Action that makes use of quantifiable resources tracked by Host.resources should ideally note them by calling this function.

These resource requests are how the Orchestrator coordinates tasking with a given Host. This is to ensure the resources that the host does provide are not oversubscribed (keeping usage at or below limit), and that any Action that requires resources that are not provided are caught.

Danger

If an Action does not request resources, regardless of the internal logic and actual resources usage, it will ALWAYS be run. If you use untracked or more resources than requested, you may inadvertently use more resources than the Host provides.

It is generally a good idea to track critical resources needed in both the Action and Host

To grow our mangos we will need "trees" (recall forest.py):

.sane/mango/actions/grow.py

import sane

@sane.register
def create_grow_action( orch ):
  grow = sane.Action( "grow_action" )
  orch.add_action( grow )

  grow.config["command"]   = ".sane/mango/scripts/grow.sh"
  grow.config["arguments"] = [ 4 ] # this must be a list

  grow.environment = "valley"
  grow.add_resource_requirements( { "trees" : 4 } )

`add_dependencies()`

This is the first Action in our workflow, so it will not have any dependencies. See the Adding Action.dependencies for details on adding dependencies.

Final `Action` Result

Our final .sane/mango/actions/grow.py should now look like:

.sane/mango/actions/grow.py

import sane

@sane.register
def create_grow_action( orch ):
  grow = sane.Action( "grow_action" )
  orch.add_action( grow )

  grow.config["command"]   = ".sane/mango/scripts/grow.sh"
  grow.config["arguments"] = [ 4 ] # this must be a list

  grow.environment = "valley"
  grow.add_resource_requirements( { "trees" : 4 } )

Running

Now that we have everything set up, we should be able to run. We will be using the following optional flags:

-sh Specific Host option to ensure our host is selected
-n New Run option to always rerun our workflow entirely
-v Verbose option to get full output in one location rather than split amongst multiple files

sane_runner -p .sane/ -sh forest -n -v -r

2025-12-10 18:41:08 INFO     [sane_runner]            Logging output to /home/aislas/mango/log/runner.log
2025-12-10 18:41:08 INFO     [orchestrator]           Searching for workflow files...
2025-12-10 18:41:08 INFO     [orchestrator]             Searching .sane/ for *.json
2025-12-10 18:41:08 INFO     [orchestrator]             Searching .sane/ for *.jsonc
2025-12-10 18:41:08 INFO     [orchestrator]             Searching .sane/ for *.py
2025-12-10 18:41:08 INFO     [orchestrator]               Found .sane/mango/hosts/forest.py
2025-12-10 18:41:08 INFO     [orchestrator]               Found .sane/mango/actions/grow.py
2025-12-10 18:41:08 INFO     [orchestrator]           Loading python file .sane/mango/hosts/forest.py as 'mango.hosts.forest'
2025-12-10 18:41:08 INFO     [orchestrator]           Loading python file .sane/mango/actions/grow.py as 'mango.actions.grow'
2025-12-10 18:41:08 INFO     [orchestrator]           No previous save file to load
2025-12-10 18:41:08 INFO     [orchestrator]           Requested actions:
2025-12-10 18:41:08 INFO     [orchestrator]             grow_action
2025-12-10 18:41:08 INFO     [orchestrator]           and any necessary dependencies
2025-12-10 18:41:08 INFO     [orchestrator]           Full action set:
2025-12-10 18:41:08 INFO     [orchestrator]           Full action set:
2025-12-10 18:41:08 INFO     [orchestrator]             grow_action
2025-12-10 18:41:08 INFO     [orchestrator]           Checking host "forest"
2025-12-10 18:41:08 INFO     [orchestrator]           Running as 'forest'
2025-12-10 18:41:08 INFO     [orchestrator]           Checking ability to run all actions on 'forest'...
2025-12-10 18:41:08 INFO     [orchestrator]             Checking environments...
2025-12-10 18:41:08 INFO     [orchestrator]             Checking resource availability...
2025-12-10 18:41:08 INFO     [orchestrator]           * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
2025-12-10 18:41:08 INFO     [orchestrator]           * * * * * * * * * *            All prerun checks for 'forest' passed            * * * * * * * * * *
2025-12-10 18:41:08 INFO     [orchestrator]           * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
2025-12-10 18:41:08 INFO     [orchestrator]           Saving host information...
2025-12-10 18:41:08 INFO     [orchestrator]           Setting state of all inactive actions to pending
2025-12-10 18:41:08 INFO     [orchestrator]           No previous save file to load
2025-12-10 18:41:08 INFO     [orchestrator]           Using working directory : '/home/aislas/mango'
2025-12-10 18:41:08 INFO     [orchestrator]           Running actions...
2025-12-10 18:41:08 INFO     [orchestrator]           Running 'grow_action' on 'forest'
2025-12-10 18:41:08 INFO     [thread_0]  [grow_action::launch]      Action logfile captured at /home/aislas/mango/log/grow_action.log
2025-12-10 18:41:08 INFO     [thread_0]  [grow_action::launch]      Saving action information for launch...
2025-12-10 18:41:08 INFO     [thread_0]  [grow_action::launch]      Using working directory : '/home/aislas/mango'
2025-12-10 18:41:08 INFO     [thread_0]  [grow_action::launch]      Running command:
2025-12-10 18:41:08 INFO     [thread_0]  [grow_action::launch]        /home/aislas/frameflow/sane/action_launcher.py /home/aislas/mango /home/aislas/mango/tmp/action_grow_action.json
2025-12-10 18:41:08 INFO     [thread_0]  [grow_action::launch]      Command output will be captured to logfile /home/aislas/mango/log/grow_action.runlog
2025-12-10 18:41:08 INFO     [thread_0]  [grow_action::launch]      Command output will be printed to this terminal
2025-12-10 18:41:08 INFO     [grow_action::launch]    ***************Inside action_launcher.py***************
2025-12-10 18:41:08 INFO     [grow_action::launch]    Current directory: /home/aislas/mango
2025-12-10 18:41:08 INFO     [grow_action::launch]    Loaded Action "grow_action"
2025-12-10 18:41:08 INFO     [grow_action::launch]    Loaded Host "forest"
2025-12-10 18:41:08 INFO     [grow_action::launch]    Using Environment "valley"
2025-12-10 18:41:08 INFO     [valley]                 Running env cmd: 'set' with var: 'GROWTH_RATE' and val: '85'
2025-12-10 18:41:08 INFO     [valley]                   Environment variable GROWTH_RATE=85
2025-12-10 18:41:08 INFO     [grow_action::run]       Running command:
2025-12-10 18:41:08 INFO     [grow_action::run]         .sane/mango/scripts/grow.sh 4
2025-12-10 18:41:08 INFO     [grow_action::run]       Command output will be printed to this terminal
2025-12-10 18:41:08 STDOUT   [grow_action::run]       Growing with 4 trees with 85% growth rate...
2025-12-10 18:41:08 STDOUT   [grow_action::run]         Tree 1 grew 6 mangos!
2025-12-10 18:41:08 STDOUT   [grow_action::run]         Tree 2 grew 6 mangos!
2025-12-10 18:41:08 STDOUT   [grow_action::run]         Tree 3 grew 4 mangos!
2025-12-10 18:41:08 STDOUT   [grow_action::run]         Tree 4 grew 6 mangos!
2025-12-10 18:41:08 INFO     [grow_action::launch]    ***************Finished action_launcher.py***************
2025-12-10 18:41:08 INFO     [orchestrator]           [FINISHED] ** Action 'grow_action'            completed with 'success'
2025-12-10 18:41:08 INFO     [orchestrator]           Finished running queued actions
2025-12-10 18:41:08 INFO     [orchestrator]             grow_action: success
2025-12-10 18:41:08 INFO     [orchestrator]           All actions finished with success
2025-12-10 18:41:08 INFO     [orchestrator]           Finished in 0:00:00.183791
2025-12-10 18:41:08 INFO     [orchestrator]           Logfiles at /home/aislas/mango/log
2025-12-10 18:41:08 INFO     [orchestrator]           Save file at /home/aislas/mango/tmp/orchestrator.json
2025-12-10 18:41:08 INFO     [orchestrator]           JUnit file at /home/aislas/mango/log/results.xml
2025-12-10 18:41:08 INFO     [sane_runner]            Finished

Tip

This output can be reproduced by using the source repo example found at docs/examples/mango/python_grow_action/.sane/

A quick walkthrough of the above output, focusing on the highlighted regions:

The Orchestrator finds and loads our python files
The Orchestrator, after verifying the selected Host, runs our Action on the host
During execution inside our Action (action_launcher.py):
1. The Action loading itself and the Host
2. Sets up the Environment
3. Calls our config["command"] with config["arguments"]
4. Outputs the command output with log tag STDOUT (stderr also goes here)
Final logs and results information is left at the bottom for our convenience

Special notes:

Everything betwwen ***...Inside action_launcher.py...*** and ***...Finished action_launcher.py...*** for a respective Action is actually the direct output of the Action.run()
(3.a) occurs because the action_launcher.py (Action.run()) occurs in a totally separate subprocess
(3.d) captures all command output (stdout and stderr)

Extending the workflow

Now that we have a basis for creating our workflow, let’s harvest our mangos. We will be adding a .sane/mango/actions/harvest.py file and supporting .sane/mango/scripts/harvest.sh script:

.sane/
└── mango
    ├── actions
    │   ├── grow.py
    │   └── harvest.py
    ├── hosts
    │   └── forest.py
    └── scripts
        ├── grow.sh
        └── harvest.sh

Adding `Action.dependencies`

Quick Reference (click to open/close)

Before we create a new Action for our workflow, we should first discuss how it will tie in and depend on our "grow_action".

When running multiple Action in a workflow, it may be beneficial to have them run in a very particular order. This is where the directed acyclic graph (DAG) nature of SANE workflows comes into play.

Dependencies between Action are mapped out based on \(child \rightarrow N parents\) relationships, where each Action lists the parents it is dependent on.

Action can have any number of dependencies, so long as the dependencies never form a closed loop. In other words, an Action CAN NEVER be the ancestor (parent) to any of its own ancestors. If thought of as a family tree, any single Action CAN NEVER reappear earlier in its lineage.

BAD: Dependency Graph with cycles

digraph foo { "bar" -> "baz"; "baz" -> "boo"; "baz" -> "foo"; "foo" -> "bar"; }

OKAY: Dependency Graph with no cycles

digraph foo { "bar" -> "baz"; "baz" -> "boo"; "baz" -> "foo"; "foo" -> "zoo"; }

This is the first Action in our workflow, so it will not have any dependencies.

If we were to add depedencies to an Action, we could do it in one of three ways, using DependencyType:

Quick Reference (click to open/close)

Assuming the following functional basis:

Example Python dependency base

import sane

@sane.register
def foo( orch )
  a = sane.Action( "a" )
  b = sane.Action( "b" )
  c = sane.Action( "c" )
  d = sane.Action( "d" )
  orch.add_action( a )
  orch.add_action( b )
  orch.add_action( c )
  orch.add_action( d )

This method relies on default assignment of DependencyType.AFTEROK:

Example Python dependency using only Action.id

# ...python file excerpt...
b.add_dependencies( "a" )
d.add_dependencies( "b", "c" )

This method relies on the string values of DependencyType:

Example Python dependency using (Action.id : str) tuple

# ...python file excerpt...
b.add_dependencies( ( "a", "afterok" ) )
d.add_dependencies( ( "b", "afterok" ), ( "c", "afternotok" ) )

This method relies on the enum values of DependencyType:

Example Python dependency using (Action.id : DependencyType) tuple

# ...python file excerpt...
b.add_dependencies( ( "a", sane.DependencyType.AFTEROK ) )
d.add_dependencies( ( "b", sane.DependencyType.AFTEROK ), ( "c", sane.DependencyType.AFTERNOTOK ) )

These methods are intermixable, even with the same call:

Example Python dependency using all methods

# ...python file excerpt...
b.add_dependencies( "a" )
d.add_dependencies( "a", ( "b", "afternotok" ), ( "c", sane.DependencyType.AFTERNOTOK ) )

New files

We can model the new "harvest_action" after the grow.py example, but change a few things such as the script we will run and adding a dependency to our initial "grow_action":

.sane/mango/actions/harvest.py

import sane

@sane.register
def create_harvest_action( orch ):
  harvest = sane.Action( "harvest_action" )
  orch.add_action( harvest )

  harvest.config["command"]   = ".sane/mango/scripts/harvest.sh"

  harvest.environment = "valley"
  # no resource requirements listed for this action
  # set dependency to "grow_action" without having access
  # to the sane.Action( "grow_action" ) object itself
  harvest.add_dependencies( "grow_action" )

And our helper script as:

.sane/mango/scripts/harvest.sh

#!/usr/bin/bash
echo "Harvesting mangos..."
echo -ne "Collected : "
awk 'BEGIN { sum=0 } { sum+=$1 } END { print sum }' mango_tree_*.txt

Note that we listed the dependencies using the Action.id string value, and not the Action object created in grow.py directly.

Since the dependency graph is constructed at runtime, there are NO checks on dependency graph validity during Action instantiation. Checks are done ony after all Action are loaded and attempted to be run.

This slight caveat gives us the flexibilty to declare our Action objects across different files and functions in virtually any order we want. We can create workflows without worrying about when an Action is created, and instead focus on proper dependency mapping as the final result.

Let’s run with new action:

sane_runner -p .sane/ -sh forest -n -v -r

2025-12-11 16:36:33 INFO     [sane_runner]            Logging output to /home/aislas/mango/log/runner.log
2025-12-11 16:36:33 INFO     [orchestrator]           Searching for workflow files...
2025-12-11 16:36:33 INFO     [orchestrator]             Searching .sane/ for *.json
2025-12-11 16:36:33 INFO     [orchestrator]             Searching .sane/ for *.jsonc
2025-12-11 16:36:33 INFO     [orchestrator]             Searching .sane/ for *.py
2025-12-11 16:36:33 INFO     [orchestrator]               Found .sane/mango/actions/grow.py
2025-12-11 16:36:33 INFO     [orchestrator]               Found .sane/mango/actions/harvest.py
2025-12-11 16:36:33 INFO     [orchestrator]               Found .sane/mango/hosts/forest.py
2025-12-11 16:36:33 INFO     [orchestrator]           Loading python file .sane/mango/actions/grow.py as 'mango.actions.grow'
2025-12-11 16:36:33 INFO     [orchestrator]           Loading python file .sane/mango/actions/harvest.py as 'mango.actions.harvest'
2025-12-11 16:36:33 INFO     [orchestrator]           Loading python file .sane/mango/hosts/forest.py as 'mango.hosts.forest'
2025-12-11 16:36:33 INFO     [orchestrator]           No previous save file to load
2025-12-11 16:36:33 INFO     [orchestrator]           Requested actions:
2025-12-11 16:36:33 INFO     [orchestrator]             grow_action     harvest_action
2025-12-11 16:36:33 INFO     [orchestrator]           and any necessary dependencies
2025-12-11 16:36:33 INFO     [orchestrator]           Full action set:
2025-12-11 16:36:33 INFO     [orchestrator]           Full action set:
2025-12-11 16:36:33 INFO     [orchestrator]             grow_action     harvest_action
2025-12-11 16:36:33 INFO     [orchestrator]           Checking host "forest"
2025-12-11 16:36:33 INFO     [orchestrator]           Running as 'forest'
2025-12-11 16:36:33 INFO     [orchestrator]           Checking ability to run all actions on 'forest'...
2025-12-11 16:36:33 INFO     [orchestrator]             Checking environments...
2025-12-11 16:36:33 INFO     [orchestrator]             Checking resource availability...
2025-12-11 16:36:33 INFO     [orchestrator]           * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
2025-12-11 16:36:33 INFO     [orchestrator]           * * * * * * * * * *            All prerun checks for 'forest' passed            * * * * * * * * * *
2025-12-11 16:36:33 INFO     [orchestrator]           * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
2025-12-11 16:36:33 INFO     [orchestrator]           Saving host information...
2025-12-11 16:36:33 INFO     [orchestrator]           Setting state of all inactive actions to pending
2025-12-11 16:36:33 INFO     [orchestrator]           No previous save file to load
2025-12-11 16:36:33 INFO     [orchestrator]           Using working directory : '/home/aislas/mango'
2025-12-11 16:36:33 INFO     [orchestrator]           Running actions...
2025-12-11 16:36:33 INFO     [orchestrator]           Running 'grow_action' on 'forest'
2025-12-11 16:36:33 INFO     [thread_0]  [grow_action::launch]         Action logfile captured at /home/aislas/mango/log/grow_action.log
2025-12-11 16:36:33 INFO     [thread_0]  [grow_action::launch]         Saving action information for launch...
2025-12-11 16:36:33 INFO     [thread_0]  [grow_action::launch]         Using working directory : '/home/aislas/mango'
2025-12-11 16:36:33 INFO     [thread_0]  [grow_action::launch]         Running command:
2025-12-11 16:36:33 INFO     [thread_0]  [grow_action::launch]           /home/aislas/frameflow/sane/action_launcher.py /home/aislas/mango /home/aislas/mango/tmp/action_grow_action.json
2025-12-11 16:36:33 INFO     [thread_0]  [grow_action::launch]         Command output will be captured to logfile /home/aislas/mango/log/grow_action.runlog
2025-12-11 16:36:33 INFO     [thread_0]  [grow_action::launch]         Command output will be printed to this terminal
2025-12-11 16:36:33 INFO     [grow_action::launch]    ***************Inside action_launcher.py***************
2025-12-11 16:36:33 INFO     [grow_action::launch]    Current directory: /home/aislas/mango
2025-12-11 16:36:33 INFO     [grow_action::launch]    Loaded Action "grow_action"
2025-12-11 16:36:33 INFO     [grow_action::launch]    Loaded Host "forest"
2025-12-11 16:36:33 INFO     [grow_action::launch]    Using Environment "valley"
2025-12-11 16:36:33 INFO     [valley]                 Running env cmd: 'set' with var: 'GROWTH_RATE' and val: '85'
2025-12-11 16:36:33 INFO     [valley]                   Environment variable GROWTH_RATE=85
2025-12-11 16:36:33 INFO     [grow_action::run]       Running command:
2025-12-11 16:36:33 INFO     [grow_action::run]         .sane/mango/scripts/grow.sh 4
2025-12-11 16:36:33 INFO     [grow_action::run]       Command output will be printed to this terminal
2025-12-11 16:36:33 STDOUT   [grow_action::run]       Growing with 4 trees with 85% growth rate...
2025-12-11 16:36:33 STDOUT   [grow_action::run]         Tree 1 grew 2 mangos!
2025-12-11 16:36:33 STDOUT   [grow_action::run]         Tree 2 grew 4 mangos!
2025-12-11 16:36:33 STDOUT   [grow_action::run]         Tree 3 grew 2 mangos!
2025-12-11 16:36:33 STDOUT   [grow_action::run]         Tree 4 grew 8 mangos!
2025-12-11 16:36:33 INFO     [grow_action::launch]    ***************Finished action_launcher.py***************
2025-12-11 16:36:33 INFO     [orchestrator]           [FINISHED] ** Action 'grow_action'            completed with 'success'
2025-12-11 16:36:33 INFO     [orchestrator]           Running 'harvest_action' on 'forest'
2025-12-11 16:36:33 INFO     [thread_0]  [harvest_action::launch]      Action logfile captured at /home/aislas/mango/log/harvest_action.log
2025-12-11 16:36:33 INFO     [thread_0]  [harvest_action::launch]      Saving action information for launch...
2025-12-11 16:36:33 INFO     [thread_0]  [harvest_action::launch]      Using working directory : '/home/aislas/mango'
2025-12-11 16:36:33 INFO     [thread_0]  [harvest_action::launch]      Running command:
2025-12-11 16:36:33 INFO     [thread_0]  [harvest_action::launch]        /home/aislas/frameflow/sane/action_launcher.py /home/aislas/mango /home/aislas/mango/tmp/action_harvest_action.json
2025-12-11 16:36:33 INFO     [thread_0]  [harvest_action::launch]      Command output will be captured to logfile /home/aislas/mango/log/harvest_action.runlog
2025-12-11 16:36:33 INFO     [thread_0]  [harvest_action::launch]      Command output will be printed to this terminal
2025-12-11 16:36:33 INFO     [harvest_action::launch] ***************Inside action_launcher.py***************
2025-12-11 16:36:33 INFO     [harvest_action::launch] Current directory: /home/aislas/mango
2025-12-11 16:36:33 INFO     [harvest_action::launch] Loaded Action "harvest_action"
2025-12-11 16:36:33 INFO     [harvest_action::launch] Loaded Host "forest"
2025-12-11 16:36:33 INFO     [harvest_action::launch] Using Environment "valley"
2025-12-11 16:36:33 INFO     [valley]                 Running env cmd: 'set' with var: 'GROWTH_RATE' and val: '85'
2025-12-11 16:36:33 INFO     [valley]                   Environment variable GROWTH_RATE=85
2025-12-11 16:36:33 INFO     [harvest_action::run]    Running command:
2025-12-11 16:36:33 INFO     [harvest_action::run]      .sane/mango/scripts/harvest.sh
2025-12-11 16:36:33 INFO     [harvest_action::run]    Command output will be printed to this terminal
2025-12-11 16:36:33 STDOUT   [harvest_action::run]    Harvesting mangos...
2025-12-11 16:36:33 STDOUT   [harvest_action::run]    Collected : 16
2025-12-11 16:36:33 INFO     [harvest_action::launch] ***************Finished action_launcher.py***************
2025-12-11 16:36:33 INFO     [orchestrator]           [FINISHED] ** Action 'harvest_action'         completed with 'success'
2025-12-11 16:36:33 INFO     [orchestrator]           Finished running queued actions
2025-12-11 16:36:33 INFO     [orchestrator]             grow_action   : success  harvest_action: success
2025-12-11 16:36:33 INFO     [orchestrator]           All actions finished with success
2025-12-11 16:36:33 INFO     [orchestrator]           Finished in 0:00:00.346601
2025-12-11 16:36:33 INFO     [orchestrator]           Logfiles at /home/aislas/mango/log
2025-12-11 16:36:33 INFO     [orchestrator]           Save file at /home/aislas/mango/tmp/orchestrator.json
2025-12-11 16:36:33 INFO     [orchestrator]           JUnit file at /home/aislas/mango/log/results.xml
2025-12-11 16:36:33 INFO     [sane_runner]            Finished

Tip

This output can be reproduced by using the source repo example found at docs/examples/mango/python_harvest_action/.sane/

Again, reviewing the highlighted regions:

Our "harvest_action" is only executed after the "grow_action" has completed
The config["command"] is executed (this time with no config["arguments"])
The STDOUT shows that we harvested 16 mangos. Quite the haul!

✨ Congratulations! ✨

You’ve gone through the basic python interface tutorial and are ready to make some workflows!

If you’re looking to add more control to your workflows or for an extra challenge, check out the Advanced Topics.

Python Interfacing

Preface

Orchestrator

Hosts

Resources & Environments

Actions

config

environment

add_resource_requirements()

add_dependencies()

Final Action Result

Running

Extending the workflow

Adding Action.dependencies

New files

`config`

`environment`

`add_resource_requirements()`

`add_dependencies()`

Final `Action` Result

Adding `Action.dependencies`