Use TODO comments to track deprecations and workarounds

pygmt/clib/conversion.py

@@ -173,12 +173,11 @@ def _to_numpy(data: Any) -> np.ndarray:
     # The numpy dtype for the result numpy array, but can be None.
     numpy_dtype = dtypes.get(str(dtype))
 
+    # TODO(pandas>=2.2): Remove the workaround for pandas<2.2.
+    #
     # pandas numeric dtypes were converted to np.object_ dtype prior pandas 2.2, and are
     # converted to suitable NumPy dtypes since pandas 2.2. Refer to the following link
     # for details: https://pandas.pydata.org/docs/whatsnew/v2.2.0.html#to-numpy-for-numpy-nullable-and-arrow-types-converts-to-suitable-numpy-dtype
-    #
-    # Workarounds for pandas < 2.2. Following SPEC 0, pandas 2.1 should be dropped in
-    # 2025 Q3, so it's likely we can remove the workaround in PyGMT v0.17.0.
     if (
         Version(pd.__version__) < Version("2.2")  # pandas < 2.2 only.
         and hasattr(data, "dtype")  # NumPy array or pandas objects only.

pygmt/clib/session.py

@@ -384,7 +384,8 @@ def print_func(file_pointer, message):  # noqa: ARG001
             We'll capture the messages and print them to stderr so that they will show
             up on the Jupyter notebook.
             """
-            # Have to use try..except due to upstream GMT bug in GMT <= 6.5.0.
+            # TODO(GMT>6.5.0): Remove the workaround for upstream bug in GMT<=6.5.0.
+            # Have to use try..except due to upstream GMT bug in GMT<=6.5.0.
             # See https://github.com/GenericMappingTools/pygmt/issues/3205.
             try:
                 message = message.decode().strip()
@@ -1388,6 +1389,7 @@ def open_virtualfile(
                 msg = f"Failed to close virtual file '{vfname}'."
                 raise GMTCLibError(msg)
 
+    # TODO(PyGMT>=0.15.0): Remove the deprecated open_virtual_file method.
     def open_virtual_file(self, family, geometry, direction, data):
         """
         Open a GMT virtual file associated with a data object for reading or writing.
@@ -1454,9 +1456,9 @@ def virtualfile_from_vectors(
         ...             print(fout.read().strip())
         <vector memory>: N = 3 <1/3> <4/6> <7/9>
         """
+        # TODO(PyGMT>=0.16.0): Remove the "*args" parameter and related codes.
         # "*args" is added in v0.14.0 for backward-compatibility with the deprecated
         # syntax of passing multiple vectors as positional arguments.
-        # Remove it in v0.16.0.
         if len(args) > 0:
             msg = (
                 "Passing multiple arguments to Session.virtualfile_from_vectors is "
@@ -1918,6 +1920,7 @@ def virtualfile_in(
         file_context = _virtualfile_from(_data)
         return file_context
 
+    # TODO(PyGMT>=0.15.0): Remove the deprecated virtualfile_from_data method.
     def virtualfile_from_data(
         self,
         check_kind=None,

pygmt/conftest.py

@@ -5,7 +5,7 @@
 import numpy as np
 from packaging.version import Version
 
-# Keep this until we require numpy to be >=2.0
+# TODO(NumPy>=2.0): Remove the conftest.py file.
 # Address https://github.com/GenericMappingTools/pygmt/issues/2628.
 if Version(np.__version__) >= Version("2.0.0.dev0+git20230726"):
     np.set_printoptions(legacy="1.25")  # type: ignore[arg-type]

pygmt/datasets/tile_map.py

@@ -166,6 +166,7 @@ def load_tile_map(
         "wait": wait,
         "max_retries": max_retries,
     }
+    # TODO(contextily>=1.5.0): Remove the check for the 'zoom_adjust' parameter.
     if zoom_adjust is not None:
         if Version(contextily.__version__) < Version("1.5.0"):
             msg = (

pygmt/figure.py

@@ -248,6 +248,7 @@ def savefig(
         kwargs.pop("metadata", None)
         self.psconvert(prefix=prefix, fmt=fmts[ext], crop=crop, **kwargs)
 
+        # TODO(GMT>=6.5.0): Remve the workaround for upstream bug in GMT<6.5.0.
         # Remove the .pgw world file if exists. Not necessary after GMT 6.5.0.
         # See upstream fix https://github.com/GenericMappingTools/gmt/pull/7865
         if ext == "tiff":

pygmt/helpers/tempfile.py

@@ -144,6 +144,8 @@ def tempfile_from_geojson(geojson):
             # https://github.com/geopandas/geopandas/issues/967#issuecomment-842877704
             # https://github.com/GenericMappingTools/pygmt/issues/2497
             int32_info = np.iinfo(np.int32)
+            # TODO(GeoPandas>=1.0): Remove the workaround for GeoPandas < 1.
+            # The default engine is "fiona" in v0.x and "pyogrio" in v1.x.
             if Version(gpd.__version__).major < 1:  # GeoPandas v0.x
                 # The default engine 'fiona' supports the 'schema' parameter.
                 if geojson.index.name is None:

pygmt/src/ternary.py

@@ -87,7 +87,7 @@ def ternary(
     if any(v is not None for v in labels):
         kwargs["L"] = "/".join(str(v) if v is not None else "-" for v in labels)
 
-    # Patch for GMT < 6.5.0.
+    # TODO(GMT>=6.5.0): Remove the patch for upstream bug fixed in GMT 6.5.0.
     # See https://github.com/GenericMappingTools/pygmt/pull/2138
     if Version(__gmt_version__) < Version("6.5.0") and isinstance(data, pd.DataFrame):
         data = data.to_numpy()

pygmt/src/timestamp.py

@@ -84,6 +84,7 @@ def timestamp(
         kwdict["U"] += f"{label}"
     kwdict["U"] += f"+j{justify}"
 
+    # TODO(GMT>=6.5.0): Remove the patch for upstream bug fixed in GMT 6.5.0.
     if Version(__gmt_version__) < Version("6.5.0") and "/" not in str(offset):
         # Giving a single offset doesn't work in GMT < 6.5.0.
         # See https://github.com/GenericMappingTools/gmt/issues/7107.
@@ -99,6 +100,7 @@ def timestamp(
                 "The given text string will be truncated to 64 characters."
             )
             warnings.warn(message=msg, category=RuntimeWarning, stacklevel=2)
+        # TODO(GMT>=6.5.0): Remove the workaround for the new '+t' modifier.
         if Version(__gmt_version__) < Version("6.5.0"):
             # Workaround for GMT<6.5.0 by overriding the 'timefmt' parameter
             timefmt = text[:64]

pygmt/tests/test_accessor.py

@@ -73,6 +73,7 @@ def test_accessor_set_non_boolean():
         grid.gmt.gtype = 2
 
 
+# TODO(GMT>=6.5.0): Remove the xfail marker for GMT>=6.5.0.
 @pytest.mark.xfail(
     condition=sys.platform == "win32" and Version(__gmt_version__) < Version("6.5.0"),
     reason="Upstream bug fixed in https://github.com/GenericMappingTools/gmt/pull/7573",

pygmt/tests/test_clib_to_numpy.py

@@ -54,6 +54,7 @@ def _check_result(result, expected_dtype):
 @pytest.mark.parametrize(
     ("data", "expected_dtype"),
     [
+        # TODO(NumPy>=2.0): Remove the if-else statement after NumPy>=2.0.
         pytest.param(
             [1, 2, 3],
             np.int32
@@ -218,9 +219,10 @@ def test_to_numpy_pandas_numeric(dtype, expected_dtype):
     Test the _to_numpy function with pandas.Series of numeric dtypes.
     """
     data = [1.0, 2.0, 3.0, 4.0, 5.0, 6.0]
+    # TODO(pandas>=2.2): Remove the workaround for float16 dtype in pandas<2.2.
+    # float16 needs special handling for pandas < 2.2.
+    # Example from https://arrow.apache.org/docs/python/generated/pyarrow.float16.html
     if dtype == "float16[pyarrow]" and Version(pd.__version__) < Version("2.2"):
-        # float16 needs special handling for pandas < 2.2.
-        # Example from https://arrow.apache.org/docs/python/generated/pyarrow.float16.html
         data = np.array(data, dtype=np.float16)
     series = pd.Series(data, dtype=dtype)[::2]  # Not C-contiguous
     result = _to_numpy(series)
@@ -264,9 +266,10 @@ def test_to_numpy_pandas_numeric_with_na(dtype, expected_dtype):
     dtypes and missing values (NA).
     """
     data = [1.0, 2.0, None, 4.0, 5.0, 6.0]
+    # TODO(pandas>=2.2): Remove the workaround for float16 dtype in pandas<2.2.
+    # float16 needs special handling for pandas < 2.2.
+    # Example from https://arrow.apache.org/docs/python/generated/pyarrow.float16.html
     if dtype == "float16[pyarrow]" and Version(pd.__version__) < Version("2.2"):
-        # float16 needs special handling for pandas < 2.2.
-        # Example from https://arrow.apache.org/docs/python/generated/pyarrow.float16.html
         data = np.array(data, dtype=np.float16)
     series = pd.Series(data, dtype=dtype)[::2]  # Not C-contiguous
     assert series.isna().any()
@@ -287,6 +290,7 @@ def test_to_numpy_pandas_numeric_with_na(dtype, expected_dtype):
             "string[pyarrow_numpy]",
             marks=[
                 skip_if_no(package="pyarrow"),
+                # TODO(pandas>=2.1): Remove the skipif marker for pandas<2.1.
                 pytest.mark.skipif(
                     Version(pd.__version__) < Version("2.1"),
                     reason="string[pyarrow_numpy] was added since pandas 2.1",
@@ -426,6 +430,7 @@ def test_to_numpy_pyarrow_numeric_with_na(dtype, expected_dtype):
         "large_utf8",  # alias for large_string
         pytest.param(
             "string_view",
+            # TODO(pyarrow>=16): Remove the skipif marker for pyarrow<16.
             marks=pytest.mark.skipif(
                 Version(pa.__version__) < Version("16"),
                 reason="string_view type was added since pyarrow 16",

pygmt/tests/test_clib_virtualfile_from_vectors.py

@@ -192,6 +192,8 @@ def test_virtualfile_from_vectors_arraylike():
         assert output == expected
 
 
+# TODO(PyGMT>=0.16.0): Remove this test in PyGMT v0.16.0 in which the "*args" parameter
+# will be removed.
 def test_virtualfile_from_vectors_args():
     """
     Test the backward compatibility of the deprecated syntax for passing multiple

pygmt/tests/test_clib_virtualfile_in.py

@@ -105,6 +105,7 @@ def test_virtualfile_in_fail_non_valid_data(data):
             )
 
 
+# TODO(GMT>6.5.0): Remove the xfail marker for GMT<=6.5.0.
 @pytest.mark.xfail(
     condition=Version(__gmt_version__) <= Version("6.5.0"),
     reason="Upstream bug fixed in https://github.com/GenericMappingTools/gmt/pull/8600",
@@ -129,6 +130,8 @@ def test_virtualfile_in_matrix_string_dtype():
                 # not lib.virtualfile_from_matrix, but it's technically complicated.
 
 
+# TODO(PyGMT>=0.16.0): Remove this test in PyGMT v0.16.0 in which the old usage of
+# virtualfile_from_data is removed.
 def test_virtualfile_from_data():
     """
     Test the backwards compatibility of the virtualfile_from_data method.

pygmt/tests/test_clib_virtualfiles.py

@@ -109,6 +109,8 @@ def test_open_virtualfile_bad_direction():
                 pass
 
 
+# TODO(PyGMT>=0.15.0): Remove the test after removing the deprecated open_virtual_file
+# method.
 def test_open_virtual_file():
     """
     Test the deprecated Session.open_virtual_file method.

pygmt/tests/test_datasets_earth_relief.py

@@ -192,6 +192,7 @@ def test_earth_relief_15s_default_registration():
     npt.assert_allclose(data.max(), -76.5, atol=0.5)
 
 
+# TODO(GMT X.Y.Z): Upstream bug which is not fixed yet.
 @pytest.mark.xfail(
     condition=Version(__gmt_version__) >= Version("6.5.0"),
     reason="Upstream bug tracked in https://github.com/GenericMappingTools/pygmt/issues/2511",

pygmt/tests/test_grdimage.py

@@ -256,6 +256,7 @@ def test_grdimage_imgout_fails(grid):
         fig.grdimage(grid, A="out.png")
 
 
+# TODO(GMT>6.5.0): Remove the xfail marker for GMT<=6.5.0.
 @pytest.mark.xfail(
     condition=Version(__gmt_version__) <= Version("6.5.0"),
     reason="Upstream bug fixed in https://github.com/GenericMappingTools/gmt/pull/8554",

pygmt/tests/test_meca.py

@@ -143,6 +143,7 @@ def test_meca_spec_multiple_focalmecha(inputtype):
     return fig
 
 
+# TODO(GMT>=6.5.0): Remove the skipif condition for GMT>=6.5.0.
 @pytest.mark.mpl_image_compare(filename="test_meca_offset.png")
 @pytest.mark.parametrize(
     "inputtype",
@@ -201,8 +202,9 @@ def test_meca_offset(inputtype):
     return fig
 
 
-# Passing event names via pandas doesn't work for GMT<=6.4, thus marked as
-# xfail. See https://github.com/GenericMappingTools/pygmt/issues/2524.
+# TODO(GMT>=6.5.0): Remove the skipif marker for GMT>=6.5.0.
+# Passing event names via pandas doesn't work for GMT<=6.4.
+# See https://github.com/GenericMappingTools/pygmt/issues/2524.
 @pytest.mark.mpl_image_compare(filename="test_meca_eventname.png")
 @pytest.mark.parametrize(
     "inputtype",

pygmt/tests/test_x2sys_cross.py

@@ -37,6 +37,7 @@ def fixture_tracks():
     return [dataframe.query(expr="z > -20")]  # reduce size of dataset
 
 
+# TODO(GMT>=6.5.0): Remove the xfail marker for the upstream bug fixed in GMT 6.5.0.
 @pytest.mark.usefixtures("mock_x2sys_home")
 @pytest.mark.xfail(
     condition=Version(__gmt_version__) < Version("6.5.0"),
@@ -66,6 +67,7 @@ def test_x2sys_cross_input_file_output_file():
         npt.assert_allclose(result["i_1"].max(), 82945.9370, rtol=1.0e-4)
 
 
+# TODO(GMT>=6.5.0): Remove the xfail marker for the upstream bug fixed in GMT 6.5.0.
 @pytest.mark.usefixtures("mock_x2sys_home")
 @pytest.mark.xfail(
     condition=Version(__gmt_version__) < Version("6.5.0"),
@@ -244,6 +246,7 @@ def test_x2sys_cross_invalid_tracks_input_type(tracks):
         x2sys_cross(tracks=[invalid_tracks])
 
 
+# TODO(GMT>=6.5.0): Remove the xfail marker for the upstream bug fixed in GMT 6.5.0.
 @pytest.mark.usefixtures("mock_x2sys_home")
 @pytest.mark.xfail(
     condition=Version(__gmt_version__) < Version("6.5.0"),
@@ -279,6 +282,7 @@ def test_x2sys_cross_region_interpolation_numpoints():
             npt.assert_allclose(output.z_M.mean(), -2896.875915, rtol=1e-4)
 
 
+# TODO(GMT>=6.5.0): Remove the xfail marker for the upstream bug fixed in GMT 6.5.0.
 @pytest.mark.usefixtures("mock_x2sys_home")
 @pytest.mark.xfail(
     condition=Version(__gmt_version__) < Version("6.5.0"),