init: Simply import grass, try harder if it fails (#6393)

Previously, the path with the package was required to exist (both the hardcoded etc/python under GISBASE and FHS variable one). Now, the code first attempts the import and only when the import fails, it tries to work out the path. The simple import should work when FHS is actually used and the grass package is where Python looks for packages (so no GRASS_PYDIR is needed there). It will also work when a user sets up PYTHONPATH manually expecting it will work the same as when setting it before running Python and importing the grass package there (both PYTHONPATH and GRASS_PYDIR will work, but PYTHONPATH will user the Python native mechanics to make the import work, while GRASS_PYDIR needs to use sys.path.append). If GRASS_PYDIR does not work (either the env variable or the one from the build), the code will attempt to find the GISBASE directory relative to the main executable and expects a non-FHS layout (which is reasonable since import should work without any setup with FHS).

Prepend, not append to sys.path. Remove sys.path manipulations from the rest of grass.py file because the smarter code to do that is already executed by this point.

* Try to import more specific grass.script, not just general grass to avoid having the import work for grass.py (issue on Windows where .py is not removed). If there is something which was imported as grass (grass.py would be the case), but does not have script, we need to convince Python to repeat the import of grass. We do that by removing it from sys.modules cache. This gives us a fresh start for next import with new path at the beginning of sys.path. Use a more specific exception type (available since Python 3.6).

* Apply suggestions from code review

---------

Co-authored-by: Anna Petrasova <[email protected]>

Author: wenzeslaus

lib/init/grass.py

@@ -660,8 +660,6 @@ def create_location(gisdbase, location, geostring) -> None:
     :param location: name of new Location
     :param geostring: path to a georeferenced file or EPSG code
     """
-    if gpath("etc", "python") not in sys.path:
-        sys.path.append(gpath("etc", "python"))
     from grass.script import core as gcore  # pylint: disable=E0611
 
     try:
@@ -1434,8 +1432,6 @@ def start_gui(grass_gui: Literal["wxpython"]):
 
 def close_gui() -> None:
     """Close GUI if running"""
-    if gpath("etc", "python") not in sys.path:
-        sys.path.append(gpath("etc", "python"))
     from grass.script import core as gcore  # pylint: disable=E0611
 
     env = gcore.gisenv()
@@ -2081,25 +2077,89 @@ def validate_cmdline(params: Parameters) -> None:
 
 
 def find_grass_python_package() -> None:
-    """Find path to grass package and add it to path"""
+    """Find path to the grass package and add it to path if needed"""
+    # Whether or not the pre-set path exists, the environment may be just
+    # set up right already. Let's try a basic import first.
+    try:
+        import grass.script as unused_gs  # noqa: F401, ICN001
 
-    # The "@...@" variables are being substituted during build process
+        # The import works without any setup, so there is nothing more to do.
+        return
+    except ModuleNotFoundError:
+        # If the grass package is not on path, we need to add it to path.
+        pass
 
-    if "GRASS_PYDIR" in os.environ and len(os.getenv("GRASS_PYDIR")) > 0:
-        GRASS_PYDIR = os.path.normpath(os.environ["GRASS_PYDIR"])
-    else:
-        GRASS_PYDIR = os.path.normpath(r"@GRASS_PYDIR@")
+    # If we happened to import something else, like our startup script called grass.py,
+    # we need to first remove it from the import cache (this does not truly un-import,
+    # but it should be sufficient for our startup script).
+    if "grass" in sys.modules:
+        del sys.modules["grass"]
 
-    if os.path.exists(GRASS_PYDIR):
-        sys.path.append(GRASS_PYDIR)
-        # now we can import stuff from grass package
+    # Try to find the package.
+    path, exists = find_path_to_grass_python_package()
+    if exists:
+        sys.path.insert(0, path)
+        try:
+            # We don't make assumptions about what should be in the directory
+            # and we simply try the actual import.
+            import grass.script as unused_gs_2nd_attempt  # noqa: F401, ICN001
+
+            # If the import worked, we did our part.
+            return
+        except ModuleNotFoundError as error:
+            # Existing path provided, but there is some issue with the import.
+            # It may be a wrong path or issue in the package itself.
+            # These strings are not translatable because we can't load translations.
+            msg = (
+                f"The grass Python package cannot be imported from {path}. "
+                "Try setting PYTHONPATH or GRASS_PYDIR to where the grass package is."
+            )
+            raise RuntimeError(msg) from error
+    # The path provided by the build or by the user does not exist.
+    msg = (
+        f"{path} with the grass Python package does not exist. "
+        "Is the installation of GRASS complete?"
+    )
+    raise RuntimeError(msg)
+
+
+def find_path_to_grass_python_package() -> tuple[str, bool]:
+    """Returns the most likely path to the grass package.
+
+    It prefers the directory provided by the user in an environmental variable.
+    Otherwise, it uses the build time variable.
+    It falls back to a heuristic based on where this file is located.
+    If that fails, it returns the actual set path
+    (and returns False for existence).
+
+    :return: tuple with path as a string and boolean for existence
+    """
+    env_variable = os.environ.get("GRASS_PYDIR", None)
+    if env_variable:
+        path_from_variable = os.path.normpath(env_variable)
     else:
-        # Not translatable because we don't have translations loaded.
-        msg = (
-            "The grass Python package is missing. "
-            "Is the installation of GRASS complete?"
-        )
-        raise RuntimeError(msg)
+        # The "@...@" variables are being substituted during build process
+        path_from_variable = os.path.normpath(r"@GRASS_PYDIR@")
+    if os.path.exists(path_from_variable):
+        return path_from_variable, True
+
+    base = Path(__file__).parent.parent / "lib"
+    path_from_context = base / "grass" / "etc" / "python"
+    if os.path.exists(path_from_context):
+        return str(path_from_context), True
+
+    major = "@GRASS_VERSION_MAJOR@"
+    minor = "@GRASS_VERSION_MINOR@"
+    # Try a run-together version number for the directory (long-used standard).
+    path_from_context = base / f"grass{major}{minor}" / "etc" / "python"
+    if os.path.exists(path_from_context):
+        return str(path_from_context), True
+    # Try a dotted version number (more common standard).
+    path_from_context = base / f"grass{major}.{minor}" / "etc" / "python"
+    if os.path.exists(path_from_context):
+        return str(path_from_context), True
+
+    return path_from_variable, False
 
 
 def main() -> None: