Output Mechanisms

Toast notifications

Toast notifications are small notifications that appear at the bottom of Workbench and fade away after a few seconds. Scripts that are connected to a running application can use them to provide transient output that the user does not need to dismiss.

The following script demonstrates creating toast notifications with different 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 above script:

Messages

Messages are a method of output designed to grab the user’s attention. It makes a small window appear in the workbench containing the output, which will not disappear until the user dismisses it. Additionally, warning and error severity messages play a tone and flash the workbench application orange when they appear to attract the user’s attention.

Because messages are very attention grabbing, they should be used sparingly.

The following script demonstrates creating 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 in the below screenshot:

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, however 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)

What type of output should I use?

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

Standard output

For example:

print("Hello world!")

• The print statement is the easiest way for a script to provide output.

• If a script is run in a popup shell window, the window is closed when the script finishes and the output is lost.

  • This can make the script difficult to debug, because if it encounters an error then the shell window is immediately closed making it difficult to determine what the error was.

• If the script is run in a window embedded in the workbench (or Visual Studio code) the output window will remain after the script ends.

• Writing to standard output when running a script in the Extend Python Script workflow component will cause the workflow to pause after the script finishes and require the user to dismiss the message box, so it should be avoided.

• Standard output is not available for scripts with a .pyw extension. If such scripts are run from the workbench, no popup shell window or embedded window will be opened and thus anything printed will be lost.

  • Saving a script with the .pyw extension instead of .py indicates that the script provides output by other mechanisms.

  • Saving a script with the .pyw extension is a good way to silence the script if opening a shell window or embedded window would be too intrusive.

Raising an error

For example:

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

• Raising an error is appropriate when one of the assumptions or requirements of your script turns out to be false. An unhandled error will end the execution of the script, which is typically preferable to continuing if something unexpected has happened.

• If a function throws an error, the caller can catch it and potentially handle it.

  • A script should never catch an error unless they likely can handle it.

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 appropriate for transient information that does not matter if the user misses it.

Message box

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

For example:

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

• The report window is appropriate for small to medium amounts of information.

• Information written to the report window is kept around until the workbench is closed or the user manually clears the report window, which means the user can come back to it when they want to.

File

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.