Function Reference#

Scopes#

GTlab integrates a Python interpreter that can be accessed in different ways, such as through the Python Console, Python Tasks, Python Script Calculators, or Nodes. Depending on how Python is accessed, different predefined functions and classes are available.

GTlab organizes this concept by introducing scopes. A scope corresponds to a separate execution environment with its own predefined functions, classes, and variables. Variables or functions defined in one scope (e.g., the Console) are not accessible in another scope (e.g., a Task). Each instance of a Python Task, Script Calculator, or Node has its own scope, meaning that variables or functions defined in one instance are isolated and cannot be accessed from another instance.

GTlab defines the following scopes:

`console`#

Provides functions for interacting with and controlling the application itself (e.g., switching sessions, opening projects).

`task`#

Provides functions for building and controlling workflows dynamically inside Python Tasks.

`calculator`#

Provides functions for performing calculations within Python Script Calculators, including access to project data models.

`node`#

Provides functions that are available when scripting inside GTlab nodes.

All documented Python functions indicate the scopes in which they are available.

Logging#

To interact with GTlab’s integrated logging system via Python, the GtLogging module is provided. It allows logging messages directly from Python scripts and displays them in the Application Console as well as in the Python Console.

Compared to using plain print() statements, GtLogging messages are automatically categorized by log level and integrated into GTlab’s logging infrastructure. For more information on the different log levels, see the logging section.

The logging functions of GtLogging are import into each scope by default.

The following logging functions are provided:

gtDebug(msg: str)#

Logs a debug-level message.

Parameters:: msg (str) – The message to log.
Scope:: console, calculator, task, node

gtInfo(msg: str)#

Logs an info-level message.

Parameters:: msg (str) – The message to log.
Scope:: console, calculator, task, node

gtWarning(msg: str)#

Logs a warning-level message.

Parameters:: msg (str) – The message to log.
Scope:: console, calculator, task, node

gtError(msg: str)#

Logs an error-level message.

Parameters:: msg (str) – The message to log.
Scope:: console, calculator, task, node

gtFatal(msg: str)#

Logs a fatal-level message.

Parameters:: msg (str) – The message to log.
Scope:: console, calculator, task, node

Introspecting GTlab#

projectPath() → str#

Returns the filesystem path of the currently opened project.

Returns:: The path of the current project.
Return type:: str
Raises:: Warning if no project is currently open.
Scope:: console, calculator, task, node

envVars() → dict#

Returns a dictionary of GTlab environment variables.

Returns:: A dictionary mapping environment variable names to their values.
Return type:: dict
Scope:: console, calculator, task, node

footprint(only_active: bool = True) → dict#

Returns a dictionary of module names and their versions. By default, it returns the application footprint, which includes all available modules in GTlab. If only_active is True, only the modules that are part of the data model of the current project are included.

Parameters:: only_active (bool) – If True, only the currently active modules in the project are included. Otherwise, all available modules in GTlab are returned.
Returns:: A dictionary mapping module names to their version strings.
Return type:: dict
Scope:: console, calculator, task, node

Controlling GTlab#

switchSession(name: str)#

Switches to the session with the specified name.

Parameters:: name (str) – The name of the session to switch to.
Scope:: console

openProject(projectIdOrPath: str) → GtProject#

Opens a project either by its filesystem path or by its project ID. Note that opening by project ID only works if the project is already part of the current session.

Parameters:: projectIdOrPath (str) – The filesystem path or the project ID of the project to be opened.
Returns:: The opened project, or None if the project could not be opened.
Return type:: GtProject
Scope:: console

currentProject() → GtProject#

Returns the currently opened project.

Returns:: The currently opened project, or None if no project is open.
Return type:: GtProject
Scope:: console

Managing Data#

class GtObject#

className() → str#

Returns the class name (type name) of the object.

Returns:: The class name of the object.
Return type:: str

calcHash() → str#

Returns the hash value of the current object.

The hash value is a fingerprint of the object state, including all property values and child objects. Thus, if an object changes, the hash will change too.

Returns:: The hash value of the object.
Return type:: str

clone() → GtObject#

Creates a clone of the object. Note, that the new object is a free object and thus does not belong to any parent.

Returns:: A cloned instance of the object.
Return type:: GtObject

findGtChild(childName: str) → GtObject#

Returns the first child element matching the object name of childName. If no element was found, it returns None.

Parameters:: childName – The object name of the the child to search for.
Returns:: The first matching child object, or None if not found.
Return type:: GtObject or None

findGtChildren(childrenName: str = '', objectClassName: str = '') → list[GtObject]#

Returns the direct children matching childrenName and objectClassName. An empty string matches everything.

Parameters:

childrenName (str) – The object name of the the children to search for.
objectClassName (str) – If not empty, only children matching the class name are returned.

Returns:

A list of matching child objects.

Return type:

list[GtObject]

findGtChildrenByClass(objectClassName: str = '') → list[GtObject]#

Returns the direct children matching their class name defined by objectClassName. An empty string matches everything.

Parameters:: objectClassName (str) – If not empty, only children matching the class name are returned.
Returns:: A list of matching child objects.
Return type:: list[GtObject]

findGtParent() → GtObject#: Returns the parent object of the object if it exists. Otherwise, None is returned. :returns: The parent object. :rtype: GtObject or None

findGtProperty(id: str) → GtAbstractProperty#

Returns the property matching id. Returns None, if not found.

Note:: The actual id might differ from the displayed property name!
Parameters:: id (str) – The property id to search for.
Returns:: The matching property, or None if not found.
Return type:: GtAbstractProperty or None

findGtProperties() → list[GtAbstractProperty]#

Returns all properties of the object.

Returns:: A list of all properties of the object.
Return type:: list[GtAbstractProperty]

propertyValue(id: str)#

Returns the value of the property with given id.

Raises:: RuntimeError, if the property does not exist.
Parameters:: id (str) – The property id to search for.
Returns:: The value of the property. The return type depends on the property.

setPropertyValue(id: str, value)#

Sets the value of the property with given id.

Raises:

RuntimeError, if the property does not exist.

Parameters:

id (str) – The property id to search for.
value – The value to set. The value type depends on the property.

getPropertyContainerSize(id: str) → int#

Returns the size of the property container given by id.

Returns:: The size of the container, -1 if id is invalid.
Return type:: int

getPropertyContainerVal(containerId: str, index: int, memberId: str)#

Returns the member of the index-th entry in the container, i.e. something like container[index].memberId .

Example:

Accessing the value member in the 2. entry of the container input_args: getPropertyContainerVal('input_args', 2, 'value')

Parameters:

containerId – The identifier of the container.
index – The index of the entry in the container.
memberId – The id of the member to returns.

Returns:

The value in the container entry. Returns None, if not found.

setPropertyContainerVal(containerId: str, index: int, memberId: str, value) → bool#

Sets the member of the index-th entry in the container, i.e. something like container[index].memberId = value .

Example:

Set the name member in the 2. entry of the container input_args to “myname”: setPropertyContainerVal('input_args', 2, 'name', 'myname')

Parameters:

containerId – The identifier of the container.
index – The index of the entry in the container.
memberId – The id of the member to set.
value – The value to set.

Returns:

True on success, otherwise False.

Return type:

bool

uuid(): str

Returns the UUID of the object.

Returns:: The UUID of the object.
Return type:: str

objectByUUID(uuid: str) → GtObject#

Searches a child object, whose UUID is uuid.

Returns:: The object matching the UUID. None, if not found.
Return type:: GtObject or None

class GtAbstractProperty#

Base class for all properties of GTlab objects. Properties are attributes of objects havaing a value. Properties can be hierarchical, i.e. they can be nested and thus contain child properties.

findGtProperties() → list[GtAbstractProperty]#

Returns all child / sub properties of the property.

Returns:: A list of all child / sub properties.
Return type:: list[GtAbstractProperty]

findGtProperty(id: str) → GtAbstractProperty#

Returns the child property matching id. Returns None, if not found.

Note:: The actual id might differ from the displayed property name!
Parameters:: id (str) – The property id to search for.
Returns:: The matching child property, or None if not found.
Return type:: GtAbstractProperty or None

propertyValue(id: str)#

Returns the value of the sub-property with given id.

Raises:: RuntimeError, if the property does not exist.
Parameters:: id (str) – The property id to search for.
Returns:: The value of the property. The return type depends on the property.

setPropertyValue(id: str, value)#

Sets the value of the sub-property with given id.

Raises:

RuntimeError, if the property does not exist.

Parameters:

id (str) – The property id to search for.
value – The value to set.

isActive() → bool#

Returns, whether the property is active.

Returns:: True if the property is active, False otherwise.
Return type:: bool

setActive(val: bool)#

Sets the property active / inactive.

Parameters:: val (bool) – True to set the property active, False to set it inactive.

isOptional() → bool#

Returns, whether the property is optional.

Returns:: True if the property is optional, False otherwise.
Return type:: bool

setOptional(val: bool)#

Sets the property optional / required.

Parameters:: val (bool) – True to set the property optional, False to set it required.

class GtProject(GtObject)#

Inherited from GtObject.

This class represents a project.

path() → str#

Returns the path to the project directory on the hard drive.

Returns:: The filesystem path of the project directory.
Return type:: str

isOpen() → bool#

Returns whether the project is currently open.

Returns:: True if the project is open, False otherwise.
Return type:: bool

isValid() → bool#

Returns whether the project data is successfully loaded.

Returns:: True if the project data is valid, False otherwise.
Return type:: bool

runProcess(processId: str, save: bool = False) → bool#

Starts the process with the given ID.

Parameters:

processId (str) – The ID of the process to start.
save (bool) – Whether the results of the process should be saved. Default is False.

Returns:

True if the process executed successfully, False otherwise.

Return type:

bool

findProcess(processId: str) → GtTask#

Returns the process with the specified ID.

Parameters:: processId (str) – The ID of the process to retrieve.
Returns:: The process object with the given ID, or None if not found.
Return type:: GtProcess (or the appropriate Python-wrapped object)

close(save: bool = False) → bool#

Closes the project.

Parameters:: save (bool) – Whether to save results before closing. Default is False.
Returns:: True if the project was closed successfully, False otherwise.
Return type:: bool

Building and Controlling Workflows#

findGtTask(name: str) → GtTask#

Returns a cloned instance of a workflow with the given name from the project’s hub-spoke workflows.

This function can only find workflows that are part of the same workflow group as the Python Task in which it is called. If multiple workflows share the same name, the first match is returned.

The returned workflow object is a clone and exists only within the Python task’s scope.

Important

To safely access its subordinate tasks or calculators, a reference to the cloned workflow must be kept; otherwise, child objects may become invalid if the workflow object is deleted.

Raises:: SystemError – If no workflow with the given name exists.
Parameters:: name (str) – The object name of the workflow to search for.
Returns:: A cloned instance of the matching workflow.
Return type:: GtTask
Scope:: task

class GtTask(GtObject)#

An executable task of the hub-spoke workflow engine.

Inherited from GtObject

run() → bool#

Executes the task.

Returns:: True on success, False otherwise.
Return type:: bool

Note

When called while evaluating a script in the Python Task’s configuration dialog, run() does not execute the task logic. In this case it always returns True to allow syntax and basic semantic checks without running the actual workflow.

deleteAllCalculators()#: Deletes all calculator appended to the given task.

hasWarnings() → bool#

Returns state of warning flag.

Returns:: True, if the task has warnings. False otherwise.
Return type:: bool

class GtPyTask(GtTask)#

This class represents a python task. As such, additional settings like input and output args can be defined via methods.

Inherited from GtTask

inputArgs() → dict#: Returns all input arguments of the python task as a dict. :returns: A dictionary mapping argument names to their values. :rtype: dict

inputArg(argName: str)#

Returns the value of the input argument given by argName.

Raises:: RuntimeError, if the argument does not exist
Parameters:: argName (str) – The name of the input argument.
Returns:: The value of the input argument.

setInputArg(argName: str, value)#

Sets the value of the input argument given by argName.

Raises:

RuntimeError, if the argument does not exist

Parameters:

argName (str) – The name of the input argument.
value – The value to set.

outputArgs() → dict#

Returns all output arguments of the python task as a dict.

Returns:: A dictionary mapping argument names to their values.
Return type:: dict

outputArg(argName: str)#

Returns the value of the output argument given by argName.

Raises:: RuntimeError, if the argument does not exist
Parameters:: argName (str) – The name of the output argument.
Returns:: The value of the output argument.

class GtCalculator(GtObject)#

An executable calculator of the hub-spoke workflow engine.

Inherited from GtObject

run() → bool#

Executes the calculator.

Returns:: True on success, False otherwise.
Return type:: bool

Note

When called while evaluating a script in the Python Task’s configuration dialog, run() does not perform the actual calculation. In this case it always returns True to enable syntax and basic semantic checks without executing the calculator routine.

Function Reference#

Scopes#

console#

task#

calculator#

node#

Logging#

Introspecting GTlab#

Controlling GTlab#

Managing Data#

Building and Controlling Workflows#

`console`#

`task`#

`calculator`#

`node`#