grass.script: Provide env parameter in the g.message API (#3439)

This makes the _message_, _verbose_ and other functions consistent with other wrappers around _run_command_ family calls. While not needed for multiple-mapset situations and parallelization, it is necessary when calls with messages are used without global environment being set and only a custom (local) environment is available which is the case in grass.script.setup (with #3438).

The PR aims at providing the interface, not updating all use cases (it will be applied for grass.script.setup in #3438).

This does not have any test since the current API does not allow for writing these test. This will be tested indirectly in the future (e.g. by #3438).

Additionally, it fixes documentation for couple other function where the parameter documentation was misleading or wrong.

python/grass/script/core.py

@@ -645,7 +645,7 @@ def exec_command(
     :param bool quiet: True to run quietly (<tt>--q</tt>)
     :param bool superquiet: True to run quietly (<tt>--qq</tt>)
     :param bool verbose: True to run verbosely (<tt>--v</tt>)
-    :param env: directory with environmental variables
+    :param env: dictionary with system environment variables (`os.environ` by default)
     :param list kwargs: module's parameters
 
     """
@@ -659,16 +659,17 @@ def exec_command(
 # interface to g.message
 
 
-def message(msg, flag=None):
+def message(msg, flag=None, env=None):
     """Display a message using `g.message`
 
     :param str msg: message to be displayed
     :param str flag: flags (given as string)
+    :param env: dictionary with system environment variables (`os.environ` by default)
     """
-    run_command("g.message", flags=flag, message=msg, errors="ignore")
+    run_command("g.message", flags=flag, message=msg, errors="ignore", env=env)
 
 
-def debug(msg, debug=1):
+def debug(msg, debug=1, env=None):
     """Display a debugging message using `g.message -d`.
 
     The visibility of a debug message at runtime is controlled by
@@ -680,32 +681,35 @@ def debug(msg, debug=1):
         Use 1 for messages generated once of few times,
         3 for messages generated for each raster row or vector line,
         5 for messages generated for each raster cell or vector point.
+    :param env: dictionary with system environment variables (`os.environ` by default)
     """
     if debug_level() >= debug:
         # TODO: quite a random hack here, do we need it somewhere else too?
         if sys.platform == "win32":
             msg = msg.replace("&", "^&")
 
-        run_command("g.message", flags="d", message=msg, debug=debug)
+        run_command("g.message", flags="d", message=msg, debug=debug, env=env)
 
 
-def verbose(msg):
+def verbose(msg, env=None):
     """Display a verbose message using `g.message -v`
 
     :param str msg: verbose message to be displayed
+    :param env: dictionary with system environment variables (`os.environ` by default)
     """
-    message(msg, flag="v")
+    message(msg, flag="v", env=env)
 
 
-def info(msg):
+def info(msg, env=None):
     """Display an informational message using `g.message -i`
 
     :param str msg: informational message to be displayed
+    :param env: dictionary with system environment variables (`os.environ` by default)
     """
-    message(msg, flag="i")
+    message(msg, flag="i", env=env)
 
 
-def percent(i, n, s):
+def percent(i, n, s, env=None):
     """Display a progress info message using `g.message -p`
 
     ::
@@ -719,44 +723,48 @@ def percent(i, n, s):
     :param int i: current item
     :param int n: total number of items
     :param int s: increment size
+    :param env: dictionary with system environment variables (`os.environ` by default)
     """
-    message("%d %d %d" % (i, n, s), flag="p")
+    message("%d %d %d" % (i, n, s), flag="p", env=env)
 
 
-def warning(msg):
+def warning(msg, env=None):
     """Display a warning message using `g.message -w`
 
     :param str msg: warning message to be displayed
+    :param env: dictionary with system environment variables (`os.environ` by default)
     """
-    message(msg, flag="w")
+    message(msg, flag="w", env=env)
 
 
-def error(msg):
+def error(msg, env=None):
     """Display an error message using `g.message -e`
 
     This function does not end the execution of the program.
     The right action after the error is up to the caller.
     For error handling using the standard mechanism use :func:`fatal()`.
 
     :param str msg: error message to be displayed
+    :param env: dictionary with system environment variables (`os.environ` by default)
     """
-    message(msg, flag="e")
+    message(msg, flag="e", env=env)
 
 
-def fatal(msg):
+def fatal(msg, env=None):
     """Display an error message using `g.message -e`, then abort or raise
 
     Raises exception when module global raise_on_error is 'True', abort
     (calls exit) otherwise.
     Use :func:`set_raise_on_error()` to set the behavior.
 
     :param str msg: error message to be displayed
+    :param env: dictionary with system environment variables (`os.environ` by default)
     """
     global raise_on_error
     if raise_on_error:
         raise ScriptError(msg)
 
-    error(msg)
+    error(msg, env=None)
     sys.exit(1)
 
 
@@ -1152,7 +1160,7 @@ def gisenv(env=None):
     >>> print(env['GISDBASE'])  # doctest: +SKIP
     /opt/grass-data
 
-    :param env run with different environment
+    :param env: dictionary with system environment variables (`os.environ` by default)
     :return: list of GRASS variables
     """
     s = read_command("g.gisenv", flags="n", env=env)
@@ -1182,7 +1190,7 @@ def region(region3d=False, complete=False, env=None):
 
     :param bool region3d: True to get 3D region
     :param bool complete:
-    :param env env
+    :param env: dictionary with system environment variables (`os.environ` by default)
 
     >>> curent_region = region()
     >>> # obtain n, s, e and w values
@@ -1232,7 +1240,7 @@ def region_env(region3d=False, flags=None, env=None, **kwargs):
 
     :param bool region3d: True to get 3D region
     :param string flags: for example 'a'
-    :param env: different environment than current
+    :param env: dictionary with system environment variables (`os.environ` by default)
     :param kwargs: g.region's parameters like 'raster', 'vector' or 'region'
 
     ::