7.1. Scripting Introduction

7.1.1. Prerequisites to Scripting

Before you start reading this guide and using the Python scripting features, please make sure you have executed the steps explained in the Installation chapter of the documentation in order to obtain a working installation of Python.

Note

For scripting to work, you need a 64-bit Python 3.14, 3.13, 3.12, 3.11, or 3.10 installation on your machine.

If for some reason Python installation directories are not correctly picked up, there are two environment variables that can modify sys.path.

PYTHONHOME sets an alternative value for the prefix of the Python installation. See https://docs.python.org/3/using/cmdline.html#envvar-PYTHONHOME for details.

The PYTHONPATH variable can be set to a list of paths that will be added to the beginning of sys.path. For example, if PYTHONPATH is set to /www/python:/opt/py, the search path will begin with [’/www/python’, ’/opt/py’]. (Note that directories must exist in order to be added to sys.path; the site module removes paths that don’t exist.)

Note

Normally, you should not have to modify those environment variables.

7.1.2. Executing Scripts

One can run scripts from within the GUI of gravis or in batch processing mode using rfgscript.

Note

It is possible to write scripts that run both in the GUI of gravis and from the console, see Section Executing Scripts from the Command Line and from the GUI.

7.1.2.1. Executing Scripts from the Command Line via rfgscript

The Python interpreter is available as stand-alone tool rfgscript. The tool rfgscript enables both embedding of Python scripts into daily build environments (in batch processing mode) and interactive work with the Python interpreter.

Usage of rfgscript is basically the same as a Python 3 interpreter itself, as rfgscript just redirects to the Python 3 interpreter. By default this Python interpreter will be the one included in the Axivion Suite, but it is also possible to set BAUHAUS_PYTHON and chose a different one.

The Python interpreter is started interactively when no script file is specified on the command line. To leave the interpreter session, press Ctrl + D on GNU/Linux and Ctrl + Z followed by Enter on Windows.

Option -c <command> executes just command within the Python interpreter and then terminates. Further command line options behind this option are not processed.

Passing the option -u to the rfgscript interpreter (or alternatively setting the environment variable PYTHONUNBUFFERED to any value) instructs the interpreter to use unbuffered stdout instead. This can be necessary in environments if stdout redirection does not work otherwise.

Tracing import statements is possible by specifying the option -v when invoking the rfgscript interpreter.

By specifying the environment variable PYTHONSTARTUP to point to a readable file, this is automatically read in and executed by the rfgscript interpreter each time it starts.

If a script filename is passed as first parameter to rfgscript, the variable sys.argv is filled according to what would happen if you started the Python interpreter itself.

All other command line switches of the Python 3 interpreter are available as well as the switches are just passed on from rfgscript to the actual Python 3 interpreter.

The following example rfgscript_params.py shown in Listing Parameter passing to a script illustrates the parameter passing to the executed script.

Parameter passing to a script
#!/usr/bin/env rfgscript
# Copyright (C) 2025 Axivion GmbH
# Copyright (C) 2025 The Qt Company GmbH, a subsidiary of The Qt Group
# https://www.qt.io

import sys

# sys.argv contains the (uninterpreted) command line arguments
# of the script
for count, arg in enumerate(sys.argv):
    print("parameter %s: %s" % (count, arg))

Calling it like shown below will produce the following output:

C:\> rfgscript rfgscript_params.py 1 "hi world" file name.rfg
parameter 0: rfgscript_params.py
parameter 1: 1
parameter 2: hi world
parameter 3: file
parameter 4: name.rfg

7.1.2.2. Executing Scripts from within gravis

The Python scripting support in gravis is accessible via a command line parameter for batch use and via menus for interactive use.

Calling gravis with the command line switch --script <file> executes the Python script found in <file> after startup of gravis. Only one --script switch is allowed. If you also specify an input file argument at the end of the command line (i. e. an RFG file), then that file is loaded before the script is executed. Extra parameters can be passed to the script using one or more --script-param <parameter> switches. After the script has terminated, gravis stays in interactive mode. You can make gravis quit after executing the script by also specifying the --quit option.

In contrast to rfgscript, gravis does not call the Python 3 executable. Instead, it uses the shared Python interpreter library. This library is also part of the official Python distribution.

To find the shared Python interpreter library, gravis will search for the interpreter in the same way rfgscript does, described in Section Executing Scripts from the Command Line via rfgscript, and use that base directory to find the shared library. gravis will look for the Python library (python313.dll/python312.dll/python311.dll/python310.dll on Windows and libpython3.13.so/libpython3.12.so/libpython3.11.so/libpython3.10.so on GNU/Linux) in the Python installation base directory.

If this approach does not choose the correct Python 3 interpreter for you, you can force gravis to use a specific one by setting the variable BAUHAUS_PYTHON_LIB to the full pathname of the alternative Python interpreter library to use. This is the gravis equivalent of the BAUHAUS_PYTHON variable used for rfgscript.

7.1.2.3. Executing Scripts from the Command Line and from the GUI

The code snippet of Listing Importing module gravis conditionally tests if the script runs in the GUI of gravis. If not, the module name gravis is set to ’None’.

Importing module gravis conditionally
try:
    from bauhaus import gravis
except ImportError:
    gravis = None

All sections of code that must distinguish whether the script runs in the GUI or the console can then be coded in the way demonstrated in Listing Using module gravis conditionally.

Using module gravis conditionally
# variable 'view' is the view the script is to operate on
view = None
graph = None

if gravis:
    # example of code using gravis
    graph = gravis.get_graph()
    if graph:
        view = gravis.get_clicked_view()
else:
    if len(sys.argv) != 3:
        print "Usage information here"
        sys.exit(1)
    graph = rfg.Graph(sys.argv[1])
    if not graph.is_view_name(sys.argv[2]):
        print "View %s not found in RFG" % sys.argv[2]
        sys.exit(1)
    view = graph.view(sys.argv[2])
# view can be used from here on

This snippet uses the currently loaded RFG and the currently selected view when called from within gravis. In batch mode called from rfgscript it loads the graph from the file given as first command line argument and the view given as second command line argument.

7.1.3. Learning Python

The following chapters imply that you have a basic knowledge of the Python programming language. If you do not yet know the basics of Python, please refer e.g. to https://docs.python.org/3/ (we are not affiliated with Python itself).