# 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 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

class `pygrass.messages.``Messenger`(raise_on_error=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!

  `debug`(level, message)

    Send a debug message to stderr

    Parameters: | message – the text of message

  `error`(message)

    Send an error message to stderr

    Parameters: | message – the text of message

  `fatal`(message)

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

    Parameters: | message – the text of message

  `get_raise_on_error`()

    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)

    Send an important message to stderr

    Parameters: | message – the text of message

  `message`(message)

    Send a message to stderr

    Parameters: | message – the text of message

  `percent`(n, d, s)

    Send a percentage to stderr

    Parameters: | message – the text of message

  `set_raise_on_error`(raise_on_error=True)

    Set the fatal error behavior

    Parameters: | raise_on_error (bool) – 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`()

    Start the messenger server and open the pipe

  `stop`()

    Stop the messenger server and close the pipe

  `test_fatal_error`(message)

    Force the messenger server to call G_fatal_error()

  `verbose`(message)

    Send a verbose message to stderr

    Parameters: | message – the text of message

  `warning`(message)

    Send a warning message to stderr

    Parameters: | message – the text of message

`pygrass.messages.``get_msgr`(_instance=[None], *args, **kwargs)

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

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

  Parameters: | lock – A multiprocessing.Lock conn – A 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 send 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 that is end through the pipe must be a list of values:

  - Messages: [“INFO|VERBOSE|WARNING|ERROR|FATAL”, “MESSAGE”]
  - Debug: [“DEBUG”, level, “MESSAGE”]
  - Percent: [“PERCENT”, n, d, s]

Help Index | Topics Index | Keywords Index | Full Index

© 2003-2023 GRASS Development Team, GRASS GIS 8.2.1dev Reference Manual