Output Mechanisms

This page presents the various methods for outputting information from scripts and details their pros and cons.

Toast notifications

Toast notifications are brief alerts that appear at the bottom of Workbench and fade out after a few seconds. They provide transient feedback without requiring user dismissal. The following script demonstrates how to create toast notifications with various severity levels:

from mapteksdk.project import Project
from mapteksdk.operations import show_toast_notification, Severity
 
if __name__ == "__main__":
  with Project() as project:
    show_toast_notification(
      "Default",
      "The default severity is information."
    )
    show_toast_notification(
      "Info",
      "Everything is fine.",
      Severity.INFORMATION)
    show_toast_notification(
      "Warning",
      "Something may have gone wrong.",
      Severity.WARNING)
    show_toast_notification(
      "Error",
      "Something has gone wrong.",
      Severity.ERROR)

The following animation shows the toast notifications generated by the script:

Messages

Messages are designed to capture the user’s attention. They appear in a small window within the Workbench and remain until dismissed by the user. Messages with warning or error severity levels play a tone and cause the Workbench application to flash orange to further attract attention.

Given their attention-grabbing nature, messages should be used sparingly. The following script demonstrates how to create messages with different severity levels:

from mapteksdk.project import Project
from mapteksdk.operations import show_message, Severity
 
if __name__ == "__main__":
  with Project() as project:
    show_message(
      "Default",
      "The default severity is information."
    )
    show_message(
      "Info",
      "Everything is fine.",
      Severity.INFORMATION)
    show_message(
      "Warning",
      "Something may have gone wrong.",
      Severity.WARNING)
    show_message(
      "Error",
      "Something has gone wrong.",
      Severity.ERROR)

The messages generated by this script are shown below.

Template script for message on error

The following script is a template for creating scripts where:

• If the script finishes without encountering an error, a toast notification notifies the user.

• If the script encounters an error, a message notifies the user that something is wrong. This includes the type of error raised and the error message similar to if the script was run from the command line, but it omits the stack trace.

import os
 
from mapteksdk.project import Project
from mapteksdk.operations import show_message, show_toast_notification, Severity
 
SCRIPT_NAME = os.path.basename(__file__)
 
def do_something_useful(project: Project):
  """A function which does something useful.
 
  Parameters
  ----------
  project
    The Project to do something useful with. This can be removed if you
    don't need it when using this template.
  """
  # Remember to rename this function to have a sensible name!
  # Absolutely do not keep the name as "do_something_useful".
 
if __name__ == "__main__":
  with Project() as project:
    try:
      do_something_useful(project)
      show_toast_notification(SCRIPT_NAME, "Completed")
    except Exception as error:
      message = f"{type(error).__name__}: {str(error)}"
      show_message(SCRIPT_NAME, message, Severity.ERROR)

Choosing the appropriate output type

A Python script can deliver output in various ways. This section covers different types of output and the appropriate output to use in those situations.

Standard output

The print() statement is the simplest method for outputting information. It outputs the supplied text to the command window the script is running in.

For example, the following script:

print("Hello, world!")

results in the following output in the terminal window:

Hello, world!

If the script runs in a pop-up shell window, the window closes upon completion, which can make debugging difficult if an error occurs. When running within Workbench or Visual Studio Code, the output window remains visible after the script ends.

Raising an error

Raising an error is appropriate when a script encounters an unexpected condition. An unhandled error terminates the script, which is generally preferable to proceeding with incorrect assumptions. Errors can be caught and handled by the caller.

For example:

raise ValueError("Expected the input to be greater than zero.")

Toast notification

For example:

from mapteksdk.project import Project
from mapteksdk.operations import show_toast_notification
 
with Project() as project:
  show_toast_notification("Toast notification", "Hello world!")

Toast notifications are suitable for transient information where it is acceptable if the user misses the message.

Message box

Message boxes are appropriate for small amounts of critical information that must be acknowledged by the user. They remain visible until dismissed and can include a tone to attract attention.

For example:

from mapteksdk.project import Project
from mapteksdk.operations import show_message
 
with Project() as project:
  show_message("Message", "Hello world!")

• Message boxes are appropriate for small amounts of important information.

• The message box does not disappear until the user dismisses it, so any information reported by a message box cannot be missed by the user.

Report window

The report window is ideal for small to medium amounts of information that users may want to review later. The information remains accessible until the Workbench is closed or the report is manually cleared.

For example:

from mapteksdk.project import Project
from mapteksdk.operations import write_report
 
with Project() as project:
  write_report("Report", "Hello world!")

File

Files are the best choice for handling large volumes of output that users need to retain. Files are persistent and must be stored in a location accessible to the user. The file format (e.g. JSON, CSV) should be chosen based on the intended use of the data.

For examples, see reading and writing files in the Python documentation.

Advanced: logging

For examples, see the Python documentation for logging.

Logging is a special type of output designed for the developer of a script rather than the user of the script. Ideally, the user of the script will never see the log messages. Rather, if something goes wrong with the script they send the log files to the developer of the script who can use the content of the log file to help them fix the issue.

By default, log messages are written to standard output; however, it is often preferable to configure the log to be written to a file in a well-known location. If log messages are written to standard output they have all the same pros and cons as standard output. If log messages are written to a file they have the following pros and cons.

Comparison of output types

Output type	Obtrusiveness	Maximum data quantity	Appropriate uses
Standard output (i.e. print)	Moderate	Large	Inconsequential status updates, small amounts of data the user may want to keep, development and initial testing of scripts
Raising an error (i.e. raise)	High	Small	Notifying the user that something unexpected has happened
Toast notification	Low	Small	Transient information that the user may miss
Message	High	Small	Important information that the user should not be allowed to miss
Report window	Moderate	Medium	Information that the user may want to keep
File	Low	Very large	Information the user will want to keep or persistent information
Logging (file)	Low	Very large	Information useful for fixing bugs in the script