Merge branch 'main' into refactor/logo

seisman · seisman · commit dab0bdb76a61 · 2025-09-09T23:00:22.000+08:00
diff --git a/.github/workflows/benchmarks.yml b/.github/workflows/benchmarks.yml
@@ -84,8 +84,9 @@ jobs:
 
       # Run the benchmark tests
       - name: Run benchmarks
-        uses: CodSpeedHQ/action@76578c2a7ddd928664caa737f0e962e3085d4e7c # v3.8.1
+        uses: CodSpeedHQ/action@6eeb021fd0f305388292348b775d96d95253adf4 # v4.0.0
         with:
+          mode: "instrumentation"
           # 'bash -el -c' is needed to use the custom shell.
           # See https://github.com/CodSpeedHQ/action/issues/65.
           run: bash -el -c "python -c \"import pygmt; pygmt.show_versions()\"; PYGMT_USE_EXTERNAL_DISPLAY=false python -m pytest -r P --pyargs pygmt --codspeed --override-ini addopts='--verbose'"
diff --git a/.github/workflows/ci_tests.yaml b/.github/workflows/ci_tests.yaml
@@ -163,7 +163,11 @@ jobs:
 
       # Pull baseline image data from dvc remote (DAGsHub)
       - name: Pull baseline image data from dvc remote
-        run: uv run dvc pull --no-run-cache --verbose && ls -lhR pygmt/tests/baseline/
+        run: |
+          uv run dvc remote modify upstream url https://${DAGSHUB_TOKEN}@dagshub.com/GenericMappingTools/pygmt.dvc --local
+          uv run dvc pull --no-run-cache --verbose && ls -lhR pygmt/tests/baseline/
+        env:
+          DAGSHUB_TOKEN: ${{ secrets.DAGSHUB_TOKEN }}
 
       # Install the package that we want to test
       - name: Install the package
@@ -183,7 +187,7 @@ jobs:
 
       # Upload coverage to Codecov
       - name: Upload coverage to Codecov
-        uses: codecov/codecov-action@18283e04ce6e62d37312384ff67231eb8fd56d24 # v5.4.3
+        uses: codecov/codecov-action@fdcc8476540edceab3de004e990f80d881c6cc00 # v5.5.0
         if: success() || failure()
         with:
           use_oidc: true
diff --git a/.github/workflows/ci_tests_dev.yaml b/.github/workflows/ci_tests_dev.yaml
@@ -161,7 +161,11 @@ jobs:
 
       # Pull baseline image data from dvc remote (DAGsHub)
       - name: Pull baseline image data from dvc remote
-        run: dvc pull --no-run-cache --verbose && ls -lhR pygmt/tests/baseline/
+        run: |
+          dvc remote modify upstream url https://${DAGSHUB_TOKEN}@dagshub.com/GenericMappingTools/pygmt.dvc --local
+          dvc pull --no-run-cache --verbose && ls -lhR pygmt/tests/baseline/
+        env:
+          DAGSHUB_TOKEN: ${{ secrets.DAGSHUB_TOKEN }}
 
       # Download cached remote files (artifacts) from GitHub
       - name: Download remote data from GitHub
diff --git a/.github/workflows/dvc-diff.yml b/.github/workflows/dvc-diff.yml
@@ -57,10 +57,14 @@ jobs:
       env:
         repo_token: ${{ github.token }}
         PR_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+        DAGSHUB_TOKEN: ${{ secrets.DAGSHUB_TOKEN }}
       run: |
         echo -e "## Summary of changed images\n" > report.md
         echo -e "This is an auto-generated report of images that have changed on the DVC remote\n" >> report.md
 
+        # Configure DVC to use the DAGsHub remote via a token
+        dvc remote modify upstream url https://${DAGSHUB_TOKEN}@dagshub.com/GenericMappingTools/pygmt.dvc --local
+
         # Pull image data from cloud storage
         dvc pull --remote upstream
         dvc diff --md main HEAD >> report.md
diff --git a/.github/workflows/release-baseline-images.yml b/.github/workflows/release-baseline-images.yml
@@ -31,7 +31,11 @@ jobs:
       uses: iterative/setup-dvc@175771be1dc3d119268e00a896b52a4b77decb5e # v1.2.0
 
     - name: Pull baseline image data from dvc remote
-      run: dvc pull && ls -lhR pygmt/tests/baseline/
+      run: |
+        dvc remote modify upstream url https://${DAGSHUB_TOKEN}@dagshub.com/GenericMappingTools/pygmt.dvc --local
+        dvc pull && ls -lhR pygmt/tests/baseline/
+      env:
+        DAGSHUB_TOKEN: ${{ secrets.DAGSHUB_TOKEN }}
 
     - name: Create the baseline image asset in zip format
       run: |
diff --git a/doc/api/index.rst b/doc/api/index.rst
@@ -203,6 +203,16 @@ Xarray Integration
     GMTBackendEntrypoint
     GMTDataArrayAccessor
 
+Class-style Parameters
+----------------------
+
+.. currentmodule:: pygmt.params
+
+.. autosummary::
+    :toctree: generated
+
+    Box
+
 Enums
 -----
 
diff --git a/examples/gallery/embellishments/inset.py b/examples/gallery/embellishments/inset.py
@@ -10,6 +10,7 @@
 
 # %%
 import pygmt
+from pygmt.params import Box
 
 fig = pygmt.Figure()
 # Create the primary figure, setting the region to Madagascar, the land color
@@ -19,7 +20,7 @@
 # Create an inset, placing it in the Top Left (TL) corner with a width of 3.5 cm and
 # x- and y-offsets of 0.2 cm. The margin is set to 0, and the border is "gold" with a
 # pen size of 1.5 points.
-with fig.inset(position="jTL+w3.5c+o0.2c", margin=0, box="+p1.5p,gold"):
+with fig.inset(position="jTL+w3.5c+o0.2c", margin=0, box=Box(pen="1.5p,gold")):
     # Create a figure in the inset using coast. This example uses the azimuthal
     # orthogonal projection centered at 47E, 20S. The land color is set to
     # "gray" and Madagascar is highlighted in "red3".
diff --git a/examples/gallery/embellishments/inset_rectangle_region.py b/examples/gallery/embellishments/inset_rectangle_region.py
@@ -10,6 +10,7 @@
 
 # %%
 import pygmt
+from pygmt.params import Box
 
 # Set the region of the main figure
 region = [137.5, 141, 34, 37]
@@ -34,7 +35,7 @@
 # a pen of "1p".
 with fig.inset(
     position="jBR+o0.1c",
-    box="+gwhite+p1p",
+    box=Box(fill="white", pen="1p"),
     region=[129, 146, 30, 46],
     projection="U54S/3c",
 ):
diff --git a/examples/gallery/embellishments/scalebar.py b/examples/gallery/embellishments/scalebar.py
@@ -42,6 +42,7 @@
 
 # %%
 import pygmt
+from pygmt.params import Box
 
 # Create a new Figure instance
 fig = pygmt.Figure()
@@ -103,7 +104,7 @@
     # Fill the box in white with a transparency of 30 percent, add a solid
     # outline in darkgray (gray30) with a thickness of 0.5 points, and use
     # rounded edges with a radius of 3 points
-    box="+gwhite@30+p0.5p,gray30,solid+r3p",
+    box=Box(fill="white@30", pen="0.5p,gray30,solid", radius="3p"),
 )
 
 fig.show()
diff --git a/examples/gallery/images/cross_section.py b/examples/gallery/images/cross_section.py
@@ -14,6 +14,7 @@
 
 # %%
 import pygmt
+from pygmt.params import Box
 
 # Define region of study area
 # lon_min, lon_max, lat_min, lat_max in degrees East and North
@@ -44,9 +45,9 @@
     # corner with an offset ("+o") of 0.7 centimeters and 0.3 centimeters in x- or y-
     # directions, respectively; move the x-label above the horizontal colorbar ("+ml")
     position="jBR+o0.7c/0.8c+h+w5c/0.3c+ml",
-    # Add a box around the colobar with a fill ("+g") in "white" color and a
-    # transparency ("@") of 30 % and with a 0.8-points thick, black, outline ("+p")
-    box="+gwhite@30+p0.8p,black",
+    # Add a box around the colobar, filled in white and a 30 % transparency, with a
+    # 0.8-points thick, black, outline.
+    box=Box(pen="0.8p,black", fill="white@30"),
     # Add x- and y-labels ("+l")
     frame=["x+lElevation", "y+lm"],
 )
diff --git a/examples/gallery/lines/hlines_vlines.py b/examples/gallery/lines/hlines_vlines.py
@@ -12,6 +12,7 @@
 # In Cartesian coordinate systems lines are plotted as straight lines.
 
 import pygmt
+from pygmt.params import Box
 
 fig = pygmt.Figure()
 
@@ -31,7 +32,7 @@
 fig.hlines(
     y=[2, 3], xmin=[0, 1], xmax=[7, 7.5], pen="1.5p,dodgerblue3", label="Lines 7 & 8"
 )
-fig.legend(position="JBR+jBR+o0.2c", box="+gwhite+p1p")
+fig.legend(position="JBR+jBR+o0.2c", box=Box(pen="1p", fill="white"))
 
 fig.shift_origin(xshift="w+2c")
 
diff --git a/examples/tutorials/advanced/insets.py b/examples/tutorials/advanced/insets.py
@@ -10,6 +10,7 @@
 
 # %%
 import pygmt
+from pygmt.params import Box
 
 # %%
 # Prior to creating an inset figure, a larger figure must first be plotted. In
@@ -48,7 +49,7 @@
     water="lightblue",
     frame="a",
 )
-with fig.inset(position="jBL+w3c", box="+pblack+glightred"):
+with fig.inset(position="jBL+w3c", box=Box(pen="black", fill="lightred")):
     # pass is used to exit the with statement as no plotting methods are
     # called
     pass
@@ -72,7 +73,7 @@
     water="lightblue",
     frame="a",
 )
-with fig.inset(position="jBL+w3c+o0.5c/0.2c", box="+pblack+glightred"):
+with fig.inset(position="jBL+w3c+o0.5c/0.2c", box=Box(pen="black", fill="lightred")):
     pass
 fig.show()
 
@@ -97,7 +98,7 @@
 # parameters.
 with fig.inset(
     position="jBL+o0.5c/0.2c",
-    box="+pblack",
+    box=Box(pen="black"),
     region=[-80, -65, 35, 50],
     projection="M3c",
 ):
diff --git a/examples/tutorials/advanced/legends.py b/examples/tutorials/advanced/legends.py
@@ -10,6 +10,7 @@
 import io
 
 import pygmt
+from pygmt.params import Box
 
 # %%
 # Create an auto-legend
@@ -89,8 +90,8 @@
 fig.plot(x=[-3, 3], y=[-2, -2], pen="darkred", label="darkred line")
 
 # Add a box with a 2-points thick blue, solid outline and a white fill with a
-# transparency of 70 percentage ("@30").
-fig.legend(position="jTL+o0.3c/0.2c", box="+p2p,blue+gwhite@30")
+# transparency of 30 percent ("@30").
+fig.legend(position="jTL+o0.3c/0.2c", box=Box(pen="2p,blue", fill="white@30"))
 
 fig.show()
 
@@ -152,7 +153,7 @@
 fig.basemap(region=[-5, 5, -5, 5], projection="M10c", frame=True)
 
 # Pass the io.StringIO object to the "spec" parameter
-fig.legend(spec=spec_io, position="jMC+w9c", box="+p1p,gray50+ggray95")
+fig.legend(spec=spec_io, position="jMC+w9c", box=Box(pen="1p,gray50", fill="gray95"))
 
 fig.show()
 
diff --git a/pygmt/params/__init__.py b/pygmt/params/__init__.py
@@ -0,0 +1,5 @@
+"""
+Classes for common parameters in PyGMT.
+"""
+
+from pygmt.params.box import Box
diff --git a/pygmt/params/base.py b/pygmt/params/base.py
@@ -0,0 +1,97 @@
+"""
+Base class for common parameters shared in PyGMT.
+"""
+
+from abc import ABC, abstractmethod
+
+
+class BaseParam(ABC):
+    """
+    Base class for parameters in PyGMT.
+
+    To define a new parameter class, inherit from this class and define the attributes
+    that correspond to the parameters you want to include.
+
+    The class should also implement the ``_aliases`` property, which returns a list of
+    ``Alias`` objects. Each ``Alias`` object represents a parameter and its value, and
+    the ``__str__`` method will concatenate these values into a single string that can
+    be passed to GMT.
+
+    Optionally, you can override the ``_validate`` method to perform any necessary
+    validation on the parameters after initialization.
+
+    Examples
+    --------
+    >>> from typing import Any
+    >>> import dataclasses
+    >>> from pygmt.params.base import BaseParam
+    >>> from pygmt.alias import Alias
+    >>>
+    >>> @dataclasses.dataclass(repr=False)
+    ... class Test(BaseParam):
+    ...     par1: Any = None
+    ...     par2: Any = None
+    ...     par3: Any = None
+    ...
+    ...     @property
+    ...     def _aliases(self):
+    ...         return [
+    ...             Alias(self.par1),
+    ...             Alias(self.par2, prefix="+a"),
+    ...             Alias(self.par3, prefix="+b", sep="/"),
+    ...         ]
+
+    >>> var = Test(par1="val1")
+    >>> str(var)
+    'val1'
+    >>> repr(var)
+    "Test(par1='val1')"
+
+    >>> var = Test(par1="val1", par2="val2", par3=("val3a", "val3b"))
+    >>> str(var)
+    'val1+aval2+bval3a/val3b'
+    >>> repr(var)
+    "Test(par1='val1', par2='val2', par3=('val3a', 'val3b'))"
+    """
+
+    def __post_init__(self):
+        """
+        Post-initialization method to _validate the _aliases property.
+        """
+        self._validate()
+
+    def _validate(self):  # noqa: B027
+        """
+        Validate the parameters of the object.
+
+        Optional method but can be overridden in subclasses to perform any necessary
+        validation on the parameters.
+        """
+
+    @property
+    @abstractmethod
+    def _aliases(self):
+        """
+        List of Alias objects representing the parameters of this class.
+
+        Must be implemented in subclasses to define the parameters and their aliases.
+        """
+
+    def __str__(self):
+        """
+        String representation of the object that can be passed to GMT directly.
+        """
+        return "".join(
+            [alias._value for alias in self._aliases if alias._value is not None]
+        )
+
+    def __repr__(self):
+        """
+        String representation of the object.
+        """
+        params = ", ".join(
+            f"{k}={v!r}"
+            for k, v in vars(self).items()
+            if v is not None and v is not False
+        )
+        return f"{self.__class__.__name__}({params})"
diff --git a/pygmt/params/box.py b/pygmt/params/box.py
diff --git a/pygmt/src/inset.py b/pygmt/src/inset.py
diff --git a/pygmt/tests/test_image.py b/pygmt/tests/test_image.py
diff --git a/pygmt/tests/test_inset.py b/pygmt/tests/test_inset.py
diff --git a/pygmt/tests/test_params_box.py b/pygmt/tests/test_params_box.py
