pygrass.messages package¶
Module contents¶
@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
pygrass.messages.
Messenger
(raise_on_error: bool = False)[source]¶ 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[source]¶ 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[source]¶ 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[source]¶ 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[source]¶ 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[source]¶ 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[source]¶ 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[source]¶ 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[source]¶ 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
-
-
pygrass.messages.
get_msgr
(instance=[None], *args, **kwargs) → pygrass.messages.Messenger[source]¶ Return a Messenger instance.
- returns
the Messenger instance.
>>> msgr0 = get_msgr() >>> msgr1 = get_msgr() >>> msgr2 = Messenger() >>> msgr0 is msgr1 True >>> msgr0 is msgr2 False
-
pygrass.messages.
message_server
(lock: _LockLike, conn: Connection) → NoReturn[source]¶ 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]