grass.jupyter: Add docstrings, f-strings, fix var names, imports (#2200)

* Add missing docstrings.
* Reorder imports (with both pylint and isort).
* Use full-word variable names.
* Use f-strings if possible. Here it replaces smart, but hard to decode, dictionary usage in format, by simple, although longer, direct use of the dictionary.

python/grass/benchmark/runners.py

@@ -14,8 +14,8 @@
 
 """Basic functions for benchmarking modules"""
 
-import shutil
 import random
+import shutil
 from types import SimpleNamespace
 
 import grass.script as gs

python/grass/jupyter/display.py

@@ -11,9 +11,12 @@
 #           License (>=v2). Read the file COPYING that comes with GRASS
 #           for details.
 
+"""2D rendering and display functionality"""
+
 import os
 import shutil
 import tempfile
+
 import grass.script as gs
 
 from .region import RegionManagerFor2D
@@ -160,6 +163,7 @@ def wrapper(**kwargs):
 
     def show(self):
         """Displays a PNG image of map"""
-        from IPython.display import Image
+        # Lazy import to avoid an import-time dependency on IPython.
+        from IPython.display import Image  # pylint: disable=import-outside-toplevel
 
         return Image(self._filename)

python/grass/jupyter/interact_display.py

@@ -15,16 +15,18 @@
 import tempfile
 import weakref
 from pathlib import Path
+
 import grass.script as gs
+
 from .display import GrassRenderer
+from .region import RegionManagerForInteractiveMap
 from .utils import (
     estimate_resolution,
     get_location_proj_string,
     get_region,
     reproject_region,
     setup_location,
 )
-from .region import RegionManagerForInteractiveMap
 
 
 class InteractiveMap:

python/grass/jupyter/region.py

@@ -10,18 +10,22 @@
 #            License (>=v2). Read the file COPYING that comes with GRASS
 #            for details.
 
+"""Manage computational or display region settings for display (render) classes."""
 
 import grass.script as gs
 from grass.exceptions import CalledModuleError
+
 from .utils import (
     get_location_proj_string,
+    get_map_name_from_d_command,
     get_region,
     reproject_region,
-    get_map_name_from_d_command,
 )
 
 
 class RegionManagerForInteractiveMap:
+    """Region manager for an interactive map (gets region from raster and vector)"""
+
     def __init__(self, use_region, saved_region, src_env, tgt_env):
         """Manages region during rendering for interactive map.
 
@@ -40,9 +44,7 @@ def __init__(self, use_region, saved_region, src_env, tgt_env):
 
     @property
     def bbox(self):
-        """Bbox property for accessing maximum
-        bounding box of all rendered layers.
-        """
+        """Bbox property for accessing maximum bounding box of all rendered layers."""
         return self._bbox
 
     def set_region_from_raster(self, raster):
@@ -91,21 +93,23 @@ def set_bbox_vector(self, vector):
 
     def _set_bbox(self, env):
         bbox = gs.parse_command("g.region", flags="bg", env=env)
-        s = float(bbox["ll_s"])
-        w = float(bbox["ll_w"])
-        n = float(bbox["ll_n"])
-        e = float(bbox["ll_e"])
-        if self._bbox[0][0] > s:
-            self._bbox[0][0] = s
-        if self._bbox[0][1] > w:
-            self._bbox[0][1] = w
-        if self._bbox[1][0] < n:
-            self._bbox[1][0] = n
-        if self._bbox[1][1] < e:
-            self._bbox[1][1] = e
+        south = float(bbox["ll_s"])
+        west = float(bbox["ll_w"])
+        north = float(bbox["ll_n"])
+        east = float(bbox["ll_e"])
+        if self._bbox[0][0] > south:
+            self._bbox[0][0] = south
+        if self._bbox[0][1] > west:
+            self._bbox[0][1] = west
+        if self._bbox[1][0] < north:
+            self._bbox[1][0] = north
+        if self._bbox[1][1] < east:
+            self._bbox[1][1] = east
 
 
 class RegionManagerFor2D:
+    """Region manager for 2D displays (gets region from display commands)"""
+
     def __init__(self, use_region, saved_region, env):
         """Manages region during rendering.
 
@@ -176,6 +180,8 @@ def set_region_from_command(self, module, **kwargs):
 
 
 class RegionManagerFor3D:
+    """Region manager for 3D displays (gets region from m.nviz.image command)"""
+
     def __init__(self, use_region, saved_region):
         """Manages region during rendering.
 

python/grass/jupyter/render3d.py

@@ -17,8 +17,8 @@
 import tempfile
 
 import grass.script as gs
-from grass.jupyter import GrassRenderer
 
+from .display import GrassRenderer
 from .region import RegionManagerFor3D
 
 

python/grass/jupyter/setup.py

@@ -129,7 +129,8 @@ def active(self):
         return self._finalizer.alive
 
 
-_global_session_handle = None
+# Pylint 2.12.2 identifies this a constant (although it is not), so it wants uppercase.
+_global_session_handle = None  # pylint: disable=invalid-name
 
 
 def init(path, location=None, mapset=None, grass_path=None):
@@ -158,7 +159,7 @@ def init(path, location=None, mapset=None, grass_path=None):
     :param str location: name of GRASS location within the database
     :param str mapset: name of mapset within location
     """
-    global _global_session_handle  # pylint: disable=global-statement
+    global _global_session_handle  # pylint: disable=global-statement,invalid-name
     if not _global_session_handle or not _global_session_handle.active:
         # Create a GRASS session.
         gsetup.init(path, location=location, mapset=mapset, grass_path=grass_path)

python/grass/jupyter/testsuite/grassrenderer_test.py

@@ -17,9 +17,10 @@
 #############################################################################
 
 import os
-import unittest
 import sys
+import unittest
 from pathlib import Path
+
 import grass.jupyter as gj
 from grass.gunittest.case import TestCase
 from grass.gunittest.main import test

python/grass/jupyter/testsuite/interactivemap_test.py

@@ -18,9 +18,10 @@
 
 
 import os
-import unittest
 import sys
+import unittest
 from pathlib import Path
+
 import grass.jupyter as gj
 from grass.gunittest.case import TestCase
 from grass.gunittest.main import test

python/grass/jupyter/testsuite/test_render3d.py

@@ -19,9 +19,10 @@
 """Test of 3D renderer"""
 
 import os
-import unittest
 import sys
+import unittest
 from pathlib import Path
+
 import grass.jupyter as gj
 from grass.gunittest.case import TestCase
 from grass.gunittest.main import test

python/grass/jupyter/utils.py

@@ -3,19 +3,23 @@
 #
 # PURPOSE:   This module contains utility functions for InteractiveMap.
 #
-# COPYRIGHT: (C) 2021 Caitlin Haedrich, and by the GRASS Development Team
+# COPYRIGHT: (C) 2021-2022 Caitlin Haedrich, and 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.
 
+"""Utility functions warpping existing processes in a suitable way"""
+
 import os
+
 import grass.script as gs
 
 
 def get_region(env=None):
     """Returns current computational region as dictionary.
-    Adds long key names.
+
+    Additionally, it adds long key names.
     """
     region = gs.region(env=env)
     region["east"] = region["e"]
@@ -43,7 +47,9 @@ def reproject_region(region, from_proj, to_proj):
     :return dict region: reprojected region as a dictionary with long key names
     """
     region = region.copy()
-    proj_input = "{east} {north}\n{west} {south}".format(**region)
+    proj_input = (
+        f"{region['east']} {region['north']}\n{region['west']} {region['south']}"
+    )
     proc = gs.start_command(
         "m.proj",
         input="-",