Figure: Deprecate the private _preprocess method (will be removed in v0.18.0)

pygmt/figure.py

@@ -4,6 +4,7 @@
 
 import base64
 import os
+import warnings
 from pathlib import Path
 from tempfile import TemporaryDirectory
 from typing import Literal, overload
@@ -119,12 +120,19 @@
         with Session() as lib:
             lib.call_module(module="figure", args=[self._name, fmt])
 
+    # TODO(PyGMT>=v0.18.0):  Remove the _preprocess method.
     def _preprocess(self, **kwargs):
         """
         Call the ``figure`` module before each plotting command to ensure we're plotting
         to this particular figure.
         """
         self._activate_figure()
+        warnings.warn(
+            "The Figure._preprocess() method is deprecated since v0.16.0 and will be "
+            "removed in v0.18.0. Use Figure._activate_figure() instead.",
+            FutureWarning,
+            stacklevel=2,
+        )
         return kwargs
 
     @property

pygmt/src/basemap.py

@@ -82,6 +82,6 @@ def basemap(self, **kwargs):
     {perspective}
     {transparency}
     """
-    kwargs = self._preprocess(**kwargs)
+    self._activate_figure()
     with Session() as lib:
         lib.call_module(module="basemap", args=build_arg_list(kwargs))

pygmt/src/coast.py

@@ -193,7 +193,7 @@ def coast(self, **kwargs):
     >>> # Show the plot
     >>> fig.show()
     """
-    kwargs = self._preprocess(**kwargs)
+    self._activate_figure()
     if not args_in_kwargs(args=["C", "G", "S", "I", "N", "E", "Q", "W"], kwargs=kwargs):
         msg = (
             "At least one of the following parameters must be specified: "

pygmt/src/colorbar.py

@@ -144,6 +144,6 @@ def colorbar(self, **kwargs):
     >>> # Show the plot
     >>> fig.show()
     """
-    kwargs = self._preprocess(**kwargs)
+    self._activate_figure()
     with Session() as lib:
         lib.call_module(module="colorbar", args=build_arg_list(kwargs))

pygmt/src/contour.py

@@ -133,7 +133,7 @@ def contour(
     {perspective}
     {transparency}
     """
-    kwargs = self._preprocess(**kwargs)
+    self._activate_figure()
 
     # Specify levels for contours or annotations.
     # One level is converted to a string with a trailing comma to separate it from

pygmt/src/grdcontour.py

@@ -138,7 +138,7 @@ def grdcontour(self, grid: PathLike | xr.DataArray, **kwargs):
     >>> # Show the plot
     >>> fig.show()
     """
-    kwargs = self._preprocess(**kwargs)
+    self._activate_figure()
 
     # Specify levels for the annotation and levels parameters.
     # One level is converted to a string with a trailing comma to separate it from

pygmt/src/grdimage.py

@@ -156,7 +156,7 @@ def grdimage(self, grid: PathLike | xr.DataArray, **kwargs):
     >>> # show the plot
     >>> fig.show()
     """
-    kwargs = self._preprocess(**kwargs)
+    self._activate_figure()
 
     # Do not support -A option
     if any(kwargs.get(arg) is not None for arg in ["A", "img_out"]):

pygmt/src/grdview.py

@@ -140,7 +140,7 @@ def grdview(self, grid: PathLike | xr.DataArray, **kwargs):
     >>> # Show the plot
     >>> fig.show()
     """
-    kwargs = self._preprocess(**kwargs)
+    self._activate_figure()
     with Session() as lib:
         with (
             lib.virtualfile_in(check_kind="raster", data=grid) as vingrd,

pygmt/src/histogram.py

@@ -135,7 +135,7 @@ def histogram(self, data: PathLike | TableLike, **kwargs):
     {transparency}
     {wrap}
     """
-    kwargs = self._preprocess(**kwargs)
+    self._activate_figure()
     with Session() as lib:
         with lib.virtualfile_in(check_kind="vector", data=data) as vintbl:
             lib.call_module(

pygmt/src/hlines.py

@@ -80,7 +80,7 @@ def hlines(
     >>> fig.legend()
     >>> fig.show()
     """
-    self._preprocess()
+    self._activate_figure()
 
     # Determine the x limits from the current plot region if not specified.
     if xmin is None or xmax is None:

pygmt/src/image.py

@@ -68,6 +68,6 @@ def image(self, imagefile: PathLike, **kwargs):
     {perspective}
     {transparency}
     """
-    kwargs = self._preprocess(**kwargs)
+    self._activate_figure()
     with Session() as lib:
         lib.call_module(module="image", args=build_arg_list(kwargs, infile=imagefile))

pygmt/src/inset.py

@@ -134,7 +134,7 @@ def inset(self, **kwargs):
     >>> fig.logo(position="jBR+o0.2c+w3c")
     >>> fig.show()
     """
-    kwargs = self._preprocess(**kwargs)
+    self._activate_figure()
     with Session() as lib:
         try:
             lib.call_module(module="inset", args=["begin", *build_arg_list(kwargs)])

pygmt/src/legend.py

@@ -82,7 +82,7 @@ def legend(
     {perspective}
     {transparency}
     """
-    kwargs = self._preprocess(**kwargs)
+    self._activate_figure()
 
     if kwargs.get("D") is None:
         kwargs["D"] = position

pygmt/src/logo.py

@@ -54,6 +54,6 @@ def logo(self, **kwargs):
     {panel}
     {transparency}
     """
-    kwargs = self._preprocess(**kwargs)
+    self._activate_figure()
     with Session() as lib:
         lib.call_module(module="logo", args=build_arg_list(kwargs))

pygmt/src/meca.py

@@ -337,7 +337,7 @@ def meca(  # noqa: PLR0913
     {perspective}
     {transparency}
     """
-    kwargs = self._preprocess(**kwargs)
+    self._activate_figure()
     # Determine the focal mechanism convention from the input data or parameters.
     _convention = _get_focal_convention(spec, convention, component)
     # Preprocess the input data.

pygmt/src/plot.py

@@ -230,7 +230,7 @@ def plot(  # noqa: PLR0912
     """
     # TODO(GMT>6.5.0): Remove the note for the upstream bug of the "straight_line"
     # parameter.
-    kwargs = self._preprocess(**kwargs)
+    self._activate_figure()
 
     kind = data_kind(data)
     if kind == "empty":  # Data is given via a series of vectors.

pygmt/src/plot3d.py

@@ -208,7 +208,7 @@ def plot3d(  # noqa: PLR0912
     """
     # TODO(GMT>6.5.0): Remove the note for the upstream bug of the "straight_line"
     # parameter.
-    kwargs = self._preprocess(**kwargs)
+    self._activate_figure()
 
     kind = data_kind(data)
     if kind == "empty":  # Data is given via a series of vectors.

pygmt/src/psconvert.py

@@ -108,7 +108,7 @@ def psconvert(self, **kwargs):
         ``prefix`` parameter.
     {verbose}
     """
-    kwargs = self._preprocess(**kwargs)
+    self._activate_figure()
     # Default cropping the figure to True
     if kwargs.get("A") is None:
         kwargs["A"] = ""

pygmt/src/rose.py

@@ -199,8 +199,7 @@ def rose(
     {transparency}
     {wrap}
     """
-
-    kwargs = self._preprocess(**kwargs)
+    self._activate_figure()
 
     with Session() as lib:
         with lib.virtualfile_in(

pygmt/src/shift_origin.py

@@ -98,7 +98,7 @@ def shift_origin(
     ...     fig.basemap(region=[0, 5, 0, 5], projection="X5c/5c", frame=True)
     >>> fig.show()
     """
-    self._preprocess()
+    self._activate_figure()
     kwdict = {"T": True, "X": xshift, "Y": yshift}
 
     with Session() as lib:

pygmt/src/solar.py

@@ -95,7 +95,7 @@ def solar(
     >>> # show the plot
     >>> fig.show()
     """
-    kwargs = self._preprocess(**kwargs)
+    self._activate_figure()
     if kwargs.get("T") is not None:
         msg = "Use 'terminator' and 'terminator_datetime' instead of 'T'."
         raise GMTInvalidInput(msg)

pygmt/src/subplot.py

@@ -145,7 +145,7 @@ def subplot(self, nrows=1, ncols=1, **kwargs):
         [no heading]. Font is determined by setting :gmt-term:`FONT_HEADING`.
     {verbose}
     """
-    kwargs = self._preprocess(**kwargs)
+    self._activate_figure()
 
     if nrows < 1 or ncols < 1:
         msg = "Please ensure that both 'nrows'>=1 and 'ncols'>=1."
@@ -224,7 +224,7 @@ def set_panel(self, panel=None, **kwargs):
 
     {verbose}
     """
-    kwargs = self._preprocess(**kwargs)
+    self._activate_figure()
 
     with Session() as lib:
         lib.call_module(

pygmt/src/ternary.py

@@ -81,7 +81,7 @@ def ternary(
     {perspective}
     {transparency}
     """
-    kwargs = self._preprocess(**kwargs)
+    self._activate_figure()
 
     # -Lalabel/blabel/clabel. '-' means skipping the label.
     labels = (alabel, blabel, clabel)

pygmt/src/text.py

@@ -179,7 +179,7 @@ def text_(  # noqa: PLR0912
         ``x``/``y`` and ``text``.
     {wrap}
     """
-    kwargs = self._preprocess(**kwargs)
+    self._activate_figure()
 
     # Ensure inputs are either textfiles, x/y/text, or position/text
     if (

pygmt/src/tilemap.py

@@ -105,7 +105,7 @@ def tilemap(
     kwargs : dict
         Extra keyword arguments to pass to :meth:`pygmt.Figure.grdimage`.
     """
-    kwargs = self._preprocess(**kwargs)
+    self._activate_figure()
 
     raster = load_tile_map(
         region=region,

pygmt/src/timestamp.py

@@ -76,7 +76,7 @@ def timestamp(
     >>> fig.timestamp(label="Powered by PyGMT")
     >>> fig.show()
     """
-    self._preprocess()
+    self._activate_figure()
 
     # Build the options passed to the "plot" module
     kwdict: dict = {"T": True, "U": ""}

pygmt/src/velo.py

@@ -239,7 +239,7 @@ def velo(self, data: PathLike | TableLike | None = None, **kwargs):
     {perspective}
     {transparency}
     """
-    kwargs = self._preprocess(**kwargs)
+    self._activate_figure()
 
     if kwargs.get("S") is None or (
         kwargs.get("S") is not None and not isinstance(kwargs["S"], str)

pygmt/src/vlines.py

@@ -80,7 +80,7 @@ def vlines(
     >>> fig.legend()
     >>> fig.show()
     """
-    self._preprocess()
+    self._activate_figure()
 
     # Determine the y limits from the current plot region if not specified.
     if ymin is None or ymax is None:

pygmt/src/wiggle.py

@@ -98,7 +98,7 @@ def wiggle(
     {transparency}
     {wrap}
     """
-    kwargs = self._preprocess(**kwargs)
+    self._activate_figure()
 
     if fillpositive or fillnegative:
         kwargs["G"] = []