grass.pygrass.messages package

@package grass.pygrass.messages

@brief PyGRASS message interface

Fast and exit-safe interface to GRASS C-library message functions

(C) 2013-2024 by the GRASS Development Team This program is free software under the GNU General Public License (>=v2). Read the file COPYING that comes with GRASS for details.

@author Soeren Gebbert, Edouard Choinière

class grass.pygrass.messages.Messenger(raise_on_error: bool = False)

Bases: object

Fast and exit-safe interface to GRASS C-library message functions

This class implements a fast and exit-safe interface to the GRASS C-library message functions like: G_message(), G_warning(), G_important_message(), G_verbose_message(), G_percent() and G_debug().

Note:

The C-library message functions a called via ctypes in a subprocess using a pipe (multiprocessing.Pipe) to transfer the text messages. Hence, the process that uses the Messenger interface will not be exited, if a G_fatal_error() was invoked in the subprocess. In this case the Messenger object will simply start a new subprocess and restarts the pipeline.

Usage:

>>> msgr = Messenger()
>>> msgr.debug(0, "debug 0")
>>> msgr.verbose("verbose message")
>>> msgr.message("message")
>>> msgr.important("important message")
>>> msgr.percent(1, 1, 1)
>>> msgr.warning("Ohh")
>>> msgr.error("Ohh no")

>>> msgr = Messenger()
>>> msgr.fatal("Ohh no no no!")
Traceback (most recent call last):
  File "__init__.py", line 239, in fatal
    sys.exit(1)
SystemExit: 1

>>> msgr = Messenger(raise_on_error=True)
>>> msgr.fatal("Ohh no no no!")
Traceback (most recent call last):
  File "__init__.py", line 241, in fatal
    raise FatalError(message)
grass.exceptions.FatalError: Ohh no no no!

>>> msgr = Messenger(raise_on_error=True)
>>> msgr.set_raise_on_error(False)
>>> msgr.fatal("Ohh no no no!")
Traceback (most recent call last):
  File "__init__.py", line 239, in fatal
    sys.exit(1)
SystemExit: 1

>>> msgr = Messenger(raise_on_error=False)
>>> msgr.set_raise_on_error(True)
>>> msgr.fatal("Ohh no no no!")
Traceback (most recent call last):
  File "__init__.py", line 241, in fatal
    raise FatalError(message)
grass.exceptions.FatalError: Ohh no no no!

client_conn: Connection

debug(level: int, message: str) → None

Send a debug message to stderr

Parameters

message –

the text of message

G_debug() will be called in the messenger server process

error(message: str) → None

Send an error message to stderr

Parameters

message –

the text of message

G_important_message() with an additional “ERROR:” string at the start will be called in the messenger server process

fatal(message: str) → NoReturn

Send an error message to stderr, call sys.exit(1) or raise FatalError

Parameters

message –

the text of message

This function emulates the behavior of G_fatal_error(). It prints an error message to stderr and calls sys.exit(1). If raise_on_error is set True while creating the messenger object, a FatalError exception will be raised instead of calling sys.exit(1).

get_raise_on_error() → bool

Get the fatal error behavior

Returns

True if a FatalError exception will be raised or False if sys.exit(1) will be called in case of invoking fatal()

important(message: str) → None

Send an important message to stderr

Parameters

message –

the text of message

G_important_message() will be called in the messenger server process

message(message: str) → None

Send a message to stderr

Parameters

message –

the text of message

G_message() will be called in the messenger server process

percent(n: int, d: int, s: int) → None

Send a percentage to stderr

Parameters

• n – The current element

• d – Total number of elements

• s –

  Increment size

  G_percent() will be called in the messenger server process

server: Process

server_conn: Connection

set_raise_on_error(raise_on_error: bool = True) → None

Set the fatal error behavior

Parameters

raise_on_error – if True a FatalError exception will be raised instead of calling sys.exit(1)

• If raise_on_error == True, a FatalError exception will be raised if fatal() is called

• If raise_on_error == False, sys.exit(1) will be invoked if fatal() is called

start_server() → None

Start the messenger server and open the pipe

stop() → None

Stop the messenger server and close the pipe

test_fatal_error(message: str) → None

Force the messenger server to call G_fatal_error()

verbose(message: str) → None

Send a verbose message to stderr

Parameters

message –

the text of message

G_verbose_message() will be called in the messenger server process

warning(message: str) → None

Send a warning message to stderr

Parameters

message –

the text of message

G_warning() will be called in the messenger server process

grass.pygrass.messages.get_msgr(instance=[None], *args, **kwargs) → grass.pygrass.messages.Messenger

Return a Messenger instance.

returns

the Messenger instance.

>>> msgr0 = get_msgr()
>>> msgr1 = get_msgr()
>>> msgr2 = Messenger()
>>> msgr0 is msgr1
True
>>> msgr0 is msgr2
False

grass.pygrass.messages.message_server(lock: _LockLike, conn: Connection) → NoReturn

The GRASS message server function designed to be a target for multiprocessing.Process

Parameters

• lock – A multiprocessing.Lock

• conn – A multiprocessing.connection.Connection object obtained from multiprocessing.Pipe

This function will use the G_* message C-functions from grass.lib.gis to provide an interface to the GRASS C-library messaging system.

The data that is sent through the pipe must provide an identifier string to specify which C-function should be called.

The following identifiers are supported:

• “INFO” Prints an info message, see G_message() for details

• “IMPORTANT” Prints an important info message,

  see G_important_message() for details

• “VERBOSE” Prints a verbose message if the verbosity level is

  set accordingly, see G_verbose_message() for details

• “WARNING” Prints a warning message, see G_warning() for details

• “ERROR” Prints a message with a leading “ERROR: ” string,

  see G_important_message() for details

• “PERCENT” Prints a percent value based on three integer values: n, d and s

  see G_percent() for details

• “STOP” Stops the server function and closes the pipe

• “FATAL” Calls G_fatal_error(), this functions is only for

  testing purpose

The data that is sent through the pipe must be a list of values:

• Messages: [“INFO|IMPORTANT|VERBOSE|WARNING|ERROR|FATAL”, “MESSAGE”]

• Debug: [“DEBUG”, level, “MESSAGE”]

• Percent: [“PERCENT”, n, d, s]