Recommend Figure.timestamp and remove timestamp (U) alias from all pl…

…otting methods (#2135)

Co-authored-by: Wei Ji <[email protected]>

pygmt/helpers/decorators.py

@@ -35,9 +35,6 @@
         frame : bool or str or list
             Set map boundary
             :doc:`frame and axes attributes </tutorials/basics/frames>`. """,
-    "timestamp": r"""
-        timestamp : bool or str
-            Draw GMT time stamp logo on plot.""",
     "cmap": r"""
         cmap : str
            File name of a CPT file or a series of comma-separated colors
@@ -565,6 +562,17 @@ def new_module(*args, **kwargs):
                     )
                     warnings.warn(msg, category=SyntaxWarning, stacklevel=2)
 
+            # timestamp (U) is deprecated since v0.9.0.
+            if "U" in kwargs or "timestamp" in kwargs:
+                if "timestamp" in kwargs:
+                    kwargs["U"] = kwargs.pop("timestamp")
+                msg = (
+                    "Parameters 'U' and 'timestamp' are deprecated since v0.9.0 "
+                    "and will be removed in v0.12.0. "
+                    "Use Figure.timestamp() instead."
+                )
+                warnings.warn(msg, category=SyntaxWarning, stacklevel=2)
+
             # xshift (X) is deprecated since v0.8.0.
             if "X" in kwargs or "xshift" in kwargs:
                 if "xshift" in kwargs:

pygmt/src/basemap.py

@@ -23,7 +23,6 @@
     F="box",
     Td="rose",
     Tm="compass",
-    U="timestamp",
     V="verbose",
     c="panel",
     f="coltypes",
@@ -80,7 +79,6 @@ def basemap(self, **kwargs):
     compass : str
         Draws a map magnetic rose on the map at the location defined by the
         reference and anchor points
-    {timestamp}
     {verbose}
     {panel}
     {coltypes}

pygmt/src/coast.py

@@ -30,7 +30,6 @@
     W="shorelines",
     G="land",
     S="water",
-    U="timestamp",
     V="verbose",
     c="panel",
     p="perspective",
@@ -147,7 +146,6 @@ def coast(self, **kwargs):
         a = All boundaries (1-3)
     water : str
         Select filling or clipping of "wet" areas.
-    {timestamp}
     shorelines : int or str or list
         [*level*\ /]\ *pen*.
         Draw shorelines [Default is no shorelines]. Append pen attributes

pygmt/src/contour.py

@@ -17,7 +17,6 @@
     N="no_clip",
     R="region",
     S="skip",
-    U="timestamp",
     V="verbose",
     W="pen",
     b="binary",
@@ -102,7 +101,6 @@ def contour(self, data=None, x=None, y=None, z=None, **kwargs):
         to be of the format [*annotcontlabel*][/*contlabel*]. If either
         label contains a slash (/) character then use ``|`` as the
         separator for the two labels instead.
-    {timestamp}
     {verbose}
     {binary}
     {panel}

pygmt/src/grdcontour.py

@@ -18,7 +18,6 @@
     Q="cut",
     R="region",
     S="resample",
-    U="timestamp",
     V="verbose",
     W="pen",
     l="label",
@@ -80,7 +79,6 @@ def grdcontour(self, grid, **kwargs):
         Control the placement of labels along the quoted lines. It supports
         five controlling algorithms. See :gmt-docs:`grdcontour.html#g` for
         details.
-    {timestamp}
     {verbose}
     {pen}
     {panel}

pygmt/src/grdimage.py

@@ -29,7 +29,6 @@
     N="no_clip",
     Q="nan_transparent",
     R="region",
-    U="timestamp",
     V="verbose",
     n="interpolation",
     c="panel",

pygmt/src/histogram.py

@@ -21,7 +21,6 @@
     R="region",
     S="stairs",
     T="series",
-    U="timestamp",
     V="verbose",
     W="pen",
     Z="histtype",
@@ -122,7 +121,6 @@ def histogram(self, data, **kwargs):
 
         To use weights provided as a second data column instead of pure counts,
         append **+w**.
-    {timestamp}
     {verbose}
     {binary}
     {nodata}

pygmt/src/image.py

@@ -12,7 +12,6 @@
     D="position",
     F="box",
     M="monochrome",
-    U="timestamp",
     V="verbose",
     c="panel",
     p="perspective",
@@ -53,7 +52,6 @@ def image(self, imagefile, **kwargs):
     monochrome : bool
         Convert color image to monochrome grayshades using the (television)
         YIQ-transformation.
-    {timestamp}
     {verbose}
     {panel}
     {perspective}

pygmt/src/legend.py

@@ -19,7 +19,6 @@
     J="projection",
     D="position",
     F="box",
-    U="timestamp",
     V="verbose",
     c="panel",
     p="perspective",
@@ -63,7 +62,6 @@ def legend(self, spec=None, position="JTR+jTR+o0.2c", box="+gwhite+p1p", **kwarg
         using :gmt-term:`MAP_FRAME_PEN`. By default, uses
         **+g**\ white\ **+p**\ 1p which draws a box around the legend using a
         1p black pen and adds a white background.
-    {timestamp}
     {verbose}
     {panel}
     {perspective}

pygmt/src/logo.py

@@ -13,7 +13,6 @@
     D="position",
     F="box",
     S="style",
-    U="timestamp",
     V="verbose",
     c="panel",
     t="transparency",
@@ -51,7 +50,6 @@ def logo(self, **kwargs):
           [Default]
         - **n** to skip the label placement
         - **u** to place the URL to the GMT site
-    {timestamp}
     {verbose}
     {panel}
     {transparency}

pygmt/src/plot.py

@@ -31,7 +31,6 @@
     N="no_clip",
     R="region",
     S="style",
-    U="timestamp",
     V="verbose",
     W="pen",
     Z="zvalue",
@@ -183,7 +182,6 @@ def plot(self, data=None, x=None, y=None, size=None, direction=None, **kwargs):
         Plot symbols (including vectors, pie slices, fronts, decorated or
         quoted lines).
     {pen}
-    {timestamp}
     {verbose}
     zvalue : str
         *value*\|\ *file*.

pygmt/src/plot3d.py

@@ -151,7 +151,6 @@ def plot3d(
         the foreground are plotted after items in the background.
     style : str
         Plot symbols. Full documentation is at :gmt-docs:`plot3d.html#s`.
-    {timestamp}
     {verbose}
     {pen}
     zvalue : str

pygmt/src/rose.py

@@ -30,7 +30,6 @@
     R="region",
     S="norm",
     T="orientation",
-    U="timestamp",
     V="verbose",
     W="pen",
     Z="scale",
@@ -188,7 +187,6 @@ def rose(self, data=None, length=None, azimuth=None, **kwargs):
         Statistics, *J. Stat. Software*, 31(10), 1-21,
         https://doi.org/10.18637/jss.v031.i10.
 
-    {timestamp}
     {verbose}
     {binary}
     {panel}

pygmt/src/solar.py

@@ -15,7 +15,6 @@
     G="fill",
     J="projection",
     R="region",
-    U="timestamp",
     V="verbose",
     W="pen",
     c="panel",
@@ -56,7 +55,6 @@ def solar(self, terminator="d", terminator_datetime=None, **kwargs):
         Set color or pattern for filling terminators [Default is no fill].
     pen : str
         Set pen attributes for lines [Default is ``"0.25p,black,solid"``].
-    {timestamp}
     {verbose}
     {panel}
     {perspective}

pygmt/src/ternary.py

@@ -16,7 +16,6 @@
     JX="width",
     R="region",
     S="style",
-    U="timestamp",
     V="verbose",
     W="pen",
     c="panel",
@@ -69,7 +68,6 @@ def ternary(self, data, alabel=None, blabel=None, clabel=None, **kwargs):
         *symbol*\[\ *size*].
         Plot individual symbols in a ternary diagram.
     {pen}
-    {timestamp}
     {verbose}
     {panel}
     {perspective}

pygmt/src/text.py

@@ -25,7 +25,6 @@
     D="offset",
     G="fill",
     N="no_clip",
-    U="timestamp",
     V="verbose",
     W="pen",
     a="aspatial",
@@ -148,7 +147,6 @@ def text_(
         (see ``clearance``) [Default is ``"0.25p,black,solid"``].
     no_clip : bool
         Do NOT clip text at map boundaries [Default is with clip].
-    {timestamp}
     {verbose}
     {aspatial}
     {panel}

pygmt/src/velo.py

@@ -33,7 +33,6 @@
     N="no_clip",
     R="region",
     S="spec",
-    U="timestamp",
     V="verbose",
     W="pen",
     Z="zvalue",
@@ -216,7 +215,6 @@ def velo(self, data=None, **kwargs):
     no_clip: bool or str
         Do NOT skip symbols that fall outside the frame boundary specified
         by ``region`` [Default plots symbols inside frame only].
-    {timestamp}
     {verbose}
     pen : str
         [*pen*][**+c**\ [**f**\|\ **l**]].

pygmt/src/wiggle.py

@@ -16,7 +16,6 @@
     J="projection",
     R="region",
     T="track",
-    U="timestamp",
     V="verbose",
     W="pen",
     Z="scale",
@@ -86,7 +85,6 @@ def wiggle(
     track : str
         Draw track [Default is no track]. Append pen attributes to use
         [Default is ``"0.25p,black,solid"``].
-    {timestamp}
     {verbose}
     pen : str
         Specify outline pen attributes [Default is no outline].

pygmt/tests/test_timestamp.py

@@ -3,7 +3,7 @@
 """
 import pytest
 from packaging.version import Version
-from pygmt import Figure, __gmt_version__
+from pygmt import Figure, __gmt_version__, config
 
 
 @pytest.fixture(scope="module", name="faketime")
@@ -86,3 +86,38 @@ def test_timestamp_text(faketime):
     fig = Figure()
     fig.timestamp(text=faketime)
     return fig
+
+
+@pytest.mark.mpl_image_compare(filename="test_timestamp.png")
+def test_timestamp_deprecated_timestamp(faketime):
+    """
+    Check if the deprecated parameter 'timestamp' works but raises a warning.
+    """
+    fig = Figure()
+    with pytest.warns(expected_warning=SyntaxWarning) as record:
+        with config(FORMAT_TIME_STAMP=faketime):
+            # plot nothing (the data is outside the region) but a timestamp
+            fig.plot(
+                x=0,
+                y=0,
+                style="p",
+                projection="X1c",
+                region=[1, 2, 1, 2],
+                timestamp=True,
+            )
+        assert len(record) == 1  # check that only one warning was raised
+    return fig
+
+
+@pytest.mark.mpl_image_compare(filename="test_timestamp.png")
+def test_timestamp_deprecated_u(faketime):
+    """
+    Check if the deprecated parameter 'U' works but raises a warning.
+    """
+    fig = Figure()
+    with pytest.warns(expected_warning=SyntaxWarning) as record:
+        with config(FORMAT_TIME_STAMP=faketime):
+            # plot nothing (the data is outside the region) but a timestamp
+            fig.plot(x=0, y=0, style="p", projection="X1c", region=[1, 2, 1, 2], U=True)
+        assert len(record) == 1  # check that only one warning was raised
+    return fig