Merge branch 'main' into refactor/data_kind

Author: seisman

.github/ISSUE_TEMPLATE/5-bump_gmt_checklist.md

@@ -35,7 +35,7 @@ using the following command:
 **To-Do for bumping the minimum required GMT version**:
 
 - [ ] Bump the minimum required GMT version (1 PR)
-  - [ ] Update `required_version` in `pygmt/clib/session.py`
+  - [ ] Update `required_gmt_version` in `pygmt/clib/__init__.py`
   - [ ] Update `test_get_default` in `pygmt/tests/test_clib.py`
   - [ ] Update minimum required versions in `doc/minversions.md`
   - [ ] Remove unsupported GMT version from `.github/workflows/ci_tests_legacy.yaml`

doc/conf.py

@@ -7,15 +7,14 @@
 
 # ruff: isort: off
 from sphinx_gallery.sorting import ExplicitOrder, ExampleTitleSortKey
-import pygmt
+from pygmt.clib import required_gmt_version
 from pygmt import __commit__, __version__
 from pygmt.sphinx_gallery import PyGMTScraper
 
 # ruff: isort: on
 
 requires_python = metadata("pygmt")["Requires-Python"]
-with pygmt.clib.Session() as lib:
-    requires_gmt = f">={lib.required_version}"
+requires_gmt = f">={required_gmt_version}"
 
 extensions = [
     "myst_parser",

pygmt/clib/__init__.py

@@ -5,7 +5,16 @@
 interface. Access to the C library is done through ctypes.
 """
 
-from pygmt.clib.session import Session
+from packaging.version import Version
+from pygmt.clib.session import Session, __gmt_version__
+from pygmt.exceptions import GMTVersionError
 
-with Session() as lib:
-    __gmt_version__ = lib.info["version"]
+required_gmt_version = "6.3.0"
+
+# Check if the GMT version is older than the required version.
+if Version(__gmt_version__) < Version(required_gmt_version):
+    msg = (
+        f"Using an incompatible GMT version {__gmt_version__}. "
+        f"Must be equal or newer than {required_gmt_version}."
+    )
+    raise GMTVersionError(msg)

pygmt/clib/loading.py

@@ -64,6 +64,33 @@ def load_libgmt(lib_fullnames: Iterator[str] | None = None) -> ctypes.CDLL:
     return libgmt
 
 
+def get_gmt_version(libgmt: ctypes.CDLL) -> str:
+    """
+    Get the GMT version string of the GMT shared library.
+
+    Parameters
+    ----------
+    libgmt
+        The GMT shared library.
+
+    Returns
+    -------
+    The GMT version string in *major.minor.patch* format.
+    """
+    func = libgmt.GMT_Get_Version
+    func.argtypes = (
+        ctypes.c_void_p,  # Unused parameter, so it can be None.
+        ctypes.POINTER(ctypes.c_uint),  # major
+        ctypes.POINTER(ctypes.c_uint),  # minor
+        ctypes.POINTER(ctypes.c_uint),  # patch
+    )
+    # The function return value is the current library version as a float, e.g., 6.5.
+    func.restype = ctypes.c_float
+    major, minor, patch = ctypes.c_uint(0), ctypes.c_uint(0), ctypes.c_uint(0)
+    func(None, major, minor, patch)
+    return f"{major.value}.{minor.value}.{patch.value}"
+
+
 def clib_names(os_name: str) -> list[str]:
     """
     Return the name(s) of GMT's shared library for the current operating system.

pygmt/clib/session.py

@@ -24,14 +24,9 @@
     strings_to_ctypes_array,
     vectors_to_arrays,
 )
-from pygmt.clib.loading import load_libgmt
+from pygmt.clib.loading import get_gmt_version, load_libgmt
 from pygmt.datatypes import _GMT_DATASET, _GMT_GRID, _GMT_IMAGE
-from pygmt.exceptions import (
-    GMTCLibError,
-    GMTCLibNoSessionError,
-    GMTInvalidInput,
-    GMTVersionError,
-)
+from pygmt.exceptions import GMTCLibError, GMTCLibNoSessionError, GMTInvalidInput
 from pygmt.helpers import (
     _validate_data_input,
     data_kind,
@@ -97,6 +92,7 @@
 
 # Load the GMT library outside the Session class to avoid repeated loading.
 _libgmt = load_libgmt()
+__gmt_version__ = get_gmt_version(_libgmt)
 
 
 class Session:
@@ -154,9 +150,6 @@ class Session:
     -55 -47 -24 -10 190 981 1 1 8 14 1 1
     """
 
-    # The minimum supported GMT version.
-    required_version = "6.3.0"
-
     @property
     def session_pointer(self):
         """
@@ -211,27 +204,11 @@ def info(self):
 
     def __enter__(self):
         """
-        Create a GMT API session and check the libgmt version.
+        Create a GMT API session.
 
         Calls :meth:`pygmt.clib.Session.create`.
-
-        Raises
-        ------
-        GMTVersionError
-            If the version reported by libgmt is less than
-            ``Session.required_version``. Will destroy the session before
-            raising the exception.
         """
         self.create("pygmt-session")
-        # Need to store the version info because 'get_default' won't work after
-        # the session is destroyed.
-        version = self.info["version"]
-        if Version(version) < Version(self.required_version):
-            self.destroy()
-            raise GMTVersionError(
-                f"Using an incompatible GMT version {version}. "
-                f"Must be equal or newer than {self.required_version}."
-            )
         return self
 
     def __exit__(self, exc_type, exc_value, traceback):

pygmt/tests/test_clib.py

@@ -577,27 +577,24 @@ def mock_defaults(api, name, value):  # noqa: ARG001
     ses.destroy()
 
 
-def test_fails_for_wrong_version():
+def test_fails_for_wrong_version(monkeypatch):
     """
-    Make sure the clib.Session raises an exception if GMT is too old.
+    Make sure that importing clib raise an exception if GMT is too old.
     """
+    import importlib
 
-    # Mock GMT_Get_Default to return an old version
-    def mock_defaults(api, name, value):  # noqa: ARG001
-        """
-        Return an old version.
-        """
-        if name == b"API_VERSION":
-            value.value = b"5.4.3"
-        else:
-            value.value = b"bla"
-        return 0
+    with monkeypatch.context() as mpatch:
+        # Make sure the current GMT major version is 6.
+        assert clib.__gmt_version__.split(".")[0] == "6"
 
-    lib = clib.Session()
-    with mock(lib, "GMT_Get_Default", mock_func=mock_defaults):
+        # Monkeypatch the version string returned by pygmt.clib.loading.get_gmt_version.
+        mpatch.setattr(clib.loading, "get_gmt_version", lambda libgmt: "5.4.3")  # noqa: ARG005
+
+        # Reload clib.session and check the __gmt_version__ string.
+        importlib.reload(clib.session)
+        assert clib.session.__gmt_version__ == "5.4.3"
+
+        # Should raise an exception when pygmt.clib is loaded/reloaded.
         with pytest.raises(GMTVersionError):
-            with lib:
-                assert lib.info["version"] != "5.4.3"
-    # Make sure the session is closed when the exception is raised.
-    with pytest.raises(GMTCLibNoSessionError):
-        assert lib.session_pointer
+            importlib.reload(clib)
+        assert clib.__gmt_version__ == "5.4.3"  # Make sure it's still the old version

pygmt/tests/test_clib_loading.py

@@ -11,7 +11,13 @@
 from pathlib import PurePath
 
 import pytest
-from pygmt.clib.loading import check_libgmt, clib_full_names, clib_names, load_libgmt
+from pygmt.clib.loading import (
+    check_libgmt,
+    clib_full_names,
+    clib_names,
+    get_gmt_version,
+    load_libgmt,
+)
 from pygmt.clib.session import Session
 from pygmt.exceptions import GMTCLibError, GMTCLibNotFoundError, GMTOSError
 
@@ -360,3 +366,15 @@ def test_clib_full_names_gmt_library_path_incorrect_path_included(
         # Windows: find_library() searches the library in PATH, so one more
         npath = 2 if sys.platform == "win32" else 1
         assert list(lib_fullpaths) == [gmt_lib_realpath] * npath + gmt_lib_names
+
+
+###############################################################################
+# Test get_gmt_version
+def test_get_gmt_version():
+    """
+    Test if get_gmt_version returns a version string in major.minor.patch format.
+    """
+    version = get_gmt_version(load_libgmt())
+    assert isinstance(version, str)
+    assert len(version.split(".")) == 3  # In major.minor.patch format
+    assert version.split(".")[0] == "6"  # Is GMT 6.x.x

pygmt/tests/test_which.py

@@ -2,11 +2,15 @@
 Test pygmt.which.
 """
 
+import os
+import sys
 from pathlib import Path
+from tempfile import TemporaryDirectory
 
 import pytest
 from pygmt import which
 from pygmt.helpers import unique_name
+from pygmt.session_management import begin, end
 
 
 def test_which():
@@ -40,3 +44,35 @@ def test_which_fails():
         which(bogus_file)
     with pytest.raises(FileNotFoundError):
         which(fname=[f"{bogus_file}.nc", f"{bogus_file}.txt"])
+
+
+@pytest.mark.skipif(
+    sys.platform == "win32",
+    reason="The Windows mkdir() function doesn't support multi-byte characters",
+)
+def test_which_nonascii_path(monkeypatch):
+    """
+    Make sure PyGMT works with paths that contain non-ascii characters (e.g., Chinese).
+    """
+    # Create a temporary directory with a Chinese suffix as a fake home directory.
+    with TemporaryDirectory(suffix="中文") as fakehome:
+        assert fakehome.endswith("中文")  # Make sure fakename contains Chinese.
+        (Path(fakehome) / ".gmt").mkdir()  # Create the ~/.gmt directory.
+        with monkeypatch.context() as mpatch:
+            # Set HOME to the fake home directory and GMT will use it.
+            mpatch.setenv("HOME", fakehome)
+            # Check if HOME is set correctly
+            assert os.getenv("HOME") == fakehome
+            assert os.environ["HOME"] == fakehome
+
+            # Start a new session
+            begin()
+            # GMT should download the remote file under the new home directory.
+            fname = which(fname="@static_earth_relief.nc", download="c", verbose="d")
+            assert fname.startswith(fakehome)
+            assert fname.endswith("static_earth_relief.nc")
+            end()
+
+    # Make sure HOME is reverted correctly.
+    assert os.getenv("HOME") != fakehome
+    assert os.environ["HOME"] != fakehome