Merge branch 'main' into improve-proj-table

.github/workflows/cache_data.yaml

@@ -58,7 +58,7 @@ jobs:
             xarray
             netCDF4
             packaging
-            build
+            python-build
 
       # Install the package that we want to test
       - name: Install the package

.github/workflows/ci_docs.yml

@@ -104,9 +104,9 @@ jobs:
             geopandas<1.0
             ipython
             rioxarray
-            build
             make
             pip
+            python-build
             myst-nb
             panel
             sphinx

.github/workflows/ci_doctests.yaml

@@ -62,9 +62,9 @@ jobs:
             ipython
             pyarrow
             rioxarray
-            build
             make
             pip
+            python-build
             pytest
             pytest-doctestplus
             pytest-mpl

.github/workflows/ci_tests.yaml

@@ -125,10 +125,10 @@ jobs:
             xarray${{ matrix.xarray-version }}
             netCDF4
             packaging
-            build
             dvc
             make
             pip
+            python-build
             pytest
             pytest-cov
             pytest-doctestplus

.github/workflows/ci_tests_legacy.yaml

@@ -72,9 +72,9 @@ jobs:
             pyarrow
             rioxarray
             sphinx-gallery
-            build
             make
             pip
+            python-build
             pytest
             pytest-doctestplus
             pytest-mpl

.pre-commit-config.yaml

@@ -15,3 +15,9 @@ repos:
     - id: remove-crlf
     - id: chmod
       args: ['644']
+
+# https://pre-commit.ci/#configuration
+ci:
+  skip: [chmod]
+  autofix_prs: false
+  autoupdate_schedule: quarterly

README.md

@@ -186,12 +186,6 @@ Other official wrappers for GMT:
 - [GMT.jl](https://github.com/GenericMappingTools/GMT.jl): A Julia wrapper for GMT.
 - [gmtmex](https://github.com/GenericMappingTools/gmtmex): A Matlab/Octave wrapper for GMT.
 
-Other non-official Python wrappers for GMT (not maintained):
-
-- [gmtpy](https://github.com/emolch/gmtpy) by [Sebastian Heimann](https://github.com/emolch)
-- [pygmt](https://github.com/ian-r-rose/pygmt) by [Ian Rose](https://github.com/ian-r-rose)
-- [PyGMT](https://github.com/glimmer-cism/PyGMT) by [Magnus Hagdorn](https://github.com/mhagdorn)
-
 <!-- doc-index-end-before -->
 
 ## Minimum supported versions

ci/requirements/docs.yml

@@ -18,9 +18,9 @@ dependencies:
     - ipython
     - rioxarray
     # Development dependencies (general)
-    - build
     - make
     - pip
+    - python-build
     # Dev dependencies (building documentation)
     - myst-nb
     - panel

doc/maintenance.md

@@ -3,11 +3,9 @@
 This page contains instructions for project maintainers about how our setup works,
 making releases, creating packages, etc.
 
-If you want to make a contribution to the project, see the
-[Contributing Guide](https://github.com/GenericMappingTools/pygmt/blob/main/CONTRIBUTING.md)
-instead.
+If you want to make a contribution to the project, see the {doc}`contributing` instead.
 
-## Onboarding Access Checklist
+## Onboarding/Offboarding Access Checklist
 
 Note that anyone can contribute to PyGMT, even without being added to the
 [GenericMappingTools team](https://github.com/orgs/GenericMappingTools/teams).
@@ -17,25 +15,31 @@ communication tools we use.
 
 ### As a Contributor
 
-- Added to the [pygmt-contributors team](https://github.com/orgs/GenericMappingTools/teams/pygmt-contributors) (gives 'write' permission to the repository)
-- Added as a collaborator on [DAGsHub](https://dagshub.com/GenericMappingTools/pygmt/settings/collaboration) (gives 'write' permission to dvc remote storage)
-- Added to the [PyGMT devs Slack channel](https://pygmtdevs.slack.com) (for casual conversations)
-- Added to the {doc}`Team Gallery page <team>`
-- Added as a member on [HackMD](https://hackmd.io/@pygmt) (for draft announcements) [optional]
+- Add to the [pygmt-contributors team](https://github.com/orgs/GenericMappingTools/teams/pygmt-contributors) (gives 'write' permission to the repository)
+- Add as a collaborator on [DAGsHub](https://dagshub.com/GenericMappingTools/pygmt) (gives 'write' permission to dvc remote storage)
+- Add as a member on [HackMD](https://hackmd.io/@pygmt) (for draft announcements) [optional]
 
 ### As a Maintainer
 
-- Added to the [pygmt-maintainers team](https://github.com/orgs/GenericMappingTools/teams/pygmt-maintainers) (gives 'maintain' permission to the repository)
-- Update the role on the {doc}`Team Gallery page <team>`
-- Added as a moderator on the [GMT forum](https://forum.generic-mapping-tools.org) (to see mod-only discussions) [optional]
-- Added as a maintainer on [ReadtheDocs](https://readthedocs.org/projects/pygmt-dev) [optional]
-- Added as a curator to the [GMT community](https://zenodo.org/communities/generic-mapping-tools/) on Zenodo (for making releases) [optional]
+- Add to the [pygmt-maintainers team](https://github.com/orgs/GenericMappingTools/teams/pygmt-maintainers) (gives 'maintain' permission to the repository)
+- Add to "Active Maintainers" on the {doc}`Team Gallery page <team>`
+- Add as a moderator on the [GMT forum](https://forum.generic-mapping-tools.org) (to see mod-only discussions) [optional]
+- Add as a maintainer on [ReadtheDocs](https://readthedocs.org/projects/pygmt-dev) [optional]
+- Add as a curator to the [GMT community](https://zenodo.org/communities/generic-mapping-tools/) on Zenodo (for making releases) [optional]
 
 ### As an Administrator
 
-- Added to the [pygmt-admin team](https://github.com/orgs/GenericMappingTools/teams/pygmt-admin) (gives 'admin' permission to the repository)
-- Added as an admin on [DAGsHub](https://www.dagshub.com/GenericMappingTools/pygmt/settings/collaboration)
-- Added as a maintainer on [PyPI](https://pypi.org/project/pygmt/) and [Test PyPI](https://test.pypi.org/project/pygmt) [optional]
+- Add to the [pygmt-admin team](https://github.com/orgs/GenericMappingTools/teams/pygmt-admin) (gives 'admin' permission to the repository)
+- Add as an admin on [DAGsHub](https://www.dagshub.com/GenericMappingTools/pygmt)
+- Add as a maintainer on [PyPI](https://pypi.org/project/pygmt/) and [Test PyPI](https://test.pypi.org/project/pygmt) [optional]
+
+**Note**: When a maintainer is no longer active (no activity in one year), we will mirror
+the onboarding access checklist:
+
+- Move from the [pygmt-maintainers team](https://github.com/orgs/GenericMappingTools/teams/pygmt-maintainers)
+  to [pygmt-contributors team](https://github.com/orgs/GenericMappingTools/teams/pygmt-contributors)
+- Move from "Active Maintainers" to "Distinguished Contributors" on the {doc}`Team Gallery page <team>`
+- Remove 'maintain' permission from GMT forum, ReadTheDocs, Zenodo
 
 ## Branches
 

environment.yml

@@ -18,11 +18,11 @@ dependencies:
     - ipython
     - rioxarray
     # Development dependencies (general)
-    - build
     - dvc
     - jupyter
     - make
     - pip
+    - python-build
     # Dev dependencies (style checks)
     - codespell
     - pre-commit

pygmt/_show_versions.py

@@ -52,9 +52,7 @@ def _get_ghostscript_version() -> str | None:
     Get Ghostscript version.
     """
     match sys.platform:
-        case "linux" | "darwin":
-            cmds = ["gs"]
-        case os_name if os_name.startswith("freebsd"):
+        case name if name in {"linux", "darwin"} or name.startswith("freebsd"):
             cmds = ["gs"]
         case "win32":
             cmds = ["gswin64c.exe", "gswin32c.exe"]

pygmt/clib/loading.py

@@ -111,14 +111,12 @@ def clib_names(os_name: str) -> list[str]:
         If the operating system is not supported yet.
     """
     match os_name:
-        case "linux":  # Linux
+        case name if name == "linux" or name.startswith("freebsd"):  # Linux or FreeBSD
             libnames = ["libgmt.so"]
         case "darwin":  # macOS
             libnames = ["libgmt.dylib"]
         case "win32":  # Windows
             libnames = ["gmt.dll", "gmt_w64.dll", "gmt_w32.dll"]
-        case name if name.startswith("freebsd"):  # FreeBSD
-            libnames = ["libgmt.so"]
         case _:
             raise GMTOSError(f"Operating system '{os_name}' is not supported.")
     return libnames

pygmt/figure.py

@@ -4,7 +4,7 @@
 
 import base64
 import os
-from pathlib import Path
+from pathlib import Path, PurePath
 from tempfile import TemporaryDirectory
 
 try:
@@ -253,12 +253,12 @@ def psconvert(self, **kwargs):
 
     def savefig(  # noqa: PLR0912
         self,
-        fname,
-        transparent=False,
-        crop=True,
-        anti_alias=True,
-        show=False,
-        worldfile=False,
+        fname: str | PurePath,
+        transparent: bool = False,
+        crop: bool = True,
+        anti_alias: bool = True,
+        show: bool = False,
+        worldfile: bool = False,
         **kwargs,
     ):
         """
@@ -280,45 +280,39 @@ def savefig(  # noqa: PLR0912
         - EPS (``.eps``)
         - PDF (``.pdf``)
 
-        Beside the above formats, you can also save the figure to a KML file
-        (``.kml``), with a companion PNG file generated automatically. The KML
-        file can be viewed in Google Earth.
+        Besides the above formats, you can also save the figure to a KML file
+        (``.kml``), with a companion PNG file generated automatically. The KML file can
+        be viewed in Google Earth.
 
-        You can pass in any keyword arguments that
-        :meth:`pygmt.Figure.psconvert` accepts.
+        You can pass in any keyword arguments that :meth:`pygmt.Figure.psconvert`
+        accepts.
 
         Parameters
         ----------
-        fname : str
-            The desired figure file name, including the extension. See the list
-            of supported formats and their extensions above.
-        transparent : bool
-            If ``True``, will use a transparent background for the figure.
-            Only valid for PNG format.
-        crop : bool
-            If ``True``, will crop the figure canvas (page) to the plot area.
-        anti_alias: bool
-            If ``True``, will use anti-aliasing when creating raster images.
-            More specifically, it passes the arguments ``"t2"`` and ``"g2"``
-            to the ``anti_aliasing`` parameter of
-            :meth:`pygmt.Figure.psconvert`. Ignored if creating vector images.
-        show: bool
-            If ``True``, will open the figure in an external viewer.
-        worldfile : bool
-            If ``True``, will create a companion
-            `world file <https://en.wikipedia.org/wiki/World_file>`__ for the
-            figure. The world file will have the same name as the figure file
-            but with different extension (e.g. tfw for tif). See
-            https://en.wikipedia.org/wiki/World_file#Filename_extension
-            for the convention of world file extensions. This parameter only
-            works for raster image formats (except GeoTIFF).
-        dpi : int
-            Set raster resolution in dpi [Default is ``720`` for PDF, ``300``
-            for others].
+        fname
+            The desired figure file name, including the extension. See the list of
+            supported formats and their extensions above.
+        transparent
+            Use a transparent background for the figure. Only valid for PNG format.
+        crop
+            Crop the figure canvas (page) to the plot area.
+        anti_alias
+            Use anti-aliasing when creating raster images. Ignored if creating vector
+            images. More specifically, it passes the arguments ``"t2"`` and ``"g2"`` to
+            the ``anti_aliasing`` parameter of :meth:`pygmt.Figure.psconvert`.
+        show
+            Display the figure in an external viewer.
+        worldfile
+            Create a companion `world file <https://en.wikipedia.org/wiki/World_file>`__
+            for the figure. The world file will have the same name as the figure file
+            but with different extension (e.g., ``.tfw`` for ``.tif``). See
+            https://en.wikipedia.org/wiki/World_file#Filename_extension for the
+            convention of world file extensions. This parameter only works for raster
+            image formats (except GeoTIFF).
         **kwargs : dict
-            Additional keyword arguments passed to
-            :meth:`pygmt.Figure.psconvert`. Valid parameters are ``gs_path``,
-            ``gs_option``, ``resize``, ``bb_style``, and ``verbose``.
+            Additional keyword arguments passed to :meth:`pygmt.Figure.psconvert`. Valid
+            parameters are ``dpi``, ``gs_path``, ``gs_option``, ``resize``,
+            ``bb_style``, and ``verbose``.
         """
         # All supported formats
         fmts = {
@@ -382,7 +376,7 @@ def savefig(  # noqa: PLR0912
             fname.with_suffix("." + ext).rename(fname)
 
         if show:
-            launch_external_viewer(fname)
+            launch_external_viewer(str(fname))
 
     def show(self, dpi=300, width=500, method=None, waiting=0.5, **kwargs):
         """

pygmt/helpers/utils.py

@@ -630,42 +630,43 @@ def is_nonstr_iter(value):
     return isinstance(value, Iterable) and not isinstance(value, str)
 
 
-def launch_external_viewer(fname, waiting=0):
+def launch_external_viewer(fname: str, waiting: float = 0):
     """
     Open a file in an external viewer program.
 
-    Uses the ``xdg-open`` command on Linux, the ``open`` command on macOS, the
-    associated application on Windows, and the default web browser on other
-    systems.
+    Uses the ``xdg-open`` command on Linux/FreeBSD, the ``open`` command on macOS, the
+    associated application on Windows, and the default web browser on other systems.
 
     Parameters
     ----------
-    fname : str
+    fname
         The file name of the file (preferably a full path).
+    waiting
+        Wait for a few seconds before exiting the function, to allow the external viewer
+        open the file before it's deleted.
     """
-    # Redirect stdout and stderr to devnull so that the terminal isn't filled
-    # with noise
+    # Redirect stdout and stderr to devnull so that the terminal isn't filled with noise
     run_args = {
         "stdout": subprocess.DEVNULL,
         "stderr": subprocess.DEVNULL,
     }
 
-    # Open the file with the default viewer.
-    # Fall back to the browser if can't recognize the operating system.
-    os_name = sys.platform
-    if os_name.startswith(("linux", "freebsd")) and (
-        xdgopen := shutil.which("xdg-open")
-    ):
-        subprocess.run([xdgopen, fname], check=False, **run_args)
-    elif os_name == "darwin":  # Darwin is macOS
-        subprocess.run([shutil.which("open"), fname], check=False, **run_args)
-    elif os_name == "win32":
-        os.startfile(fname)  # noqa: S606
-    else:
-        webbrowser.open_new_tab(f"file://{fname}")
+    match sys.platform:
+        case name if (
+            (name == "linux" or name.startswith("freebsd"))
+            and (xdgopen := shutil.which("xdg-open"))
+        ):  # Linux/FreeBSD
+            subprocess.run([xdgopen, fname], check=False, **run_args)  # type:ignore[call-overload]
+        case "darwin":  # macOS
+            subprocess.run([shutil.which("open"), fname], check=False, **run_args)  # type:ignore[call-overload]
+        case "win32":  # Windows
+            os.startfile(fname)  # type:ignore[attr-defined] # noqa: S606
+        case _:  # Fall back to the browser if can't recognize the operating system.
+            webbrowser.open_new_tab(f"file://{fname}")
     if waiting > 0:
-        # suspend the execution for a few seconds to avoid the images being
-        # deleted when a Python script exits
+        # Preview images will be deleted when a GMT modern-mode session ends, but the
+        # external viewer program may take a few seconds to open the images.
+        # Suspend the execution for a few seconds.
         time.sleep(waiting)
 
 

pygmt/tests/test_sphinx_gallery.py

@@ -9,7 +9,7 @@
 from pygmt.figure import SHOWED_FIGURES, Figure
 from pygmt.sphinx_gallery import PyGMTScraper
 
-pytest.importorskip("sphinx-gallery", reason="Requires sphinx-gallery to be installed")
+pytest.importorskip("sphinx_gallery", reason="Requires sphinx-gallery to be installed")
 pytest.importorskip("IPython", reason="Requires IPython to be installed")