Rename deprecation (#142)

* module renaming deprecation

* changelog

* add version info

CHANGELOG.md

@@ -15,7 +15,9 @@
   | seaborn     | 0.12   | 0.13    |
   | xarray      | 2022.12| 2023.9  |
 
-- The modules ``cartopy_utils``, ``colormaps``, ``map_layout``, ``mpl``, and ``xrcompat`` were renamed (added a leading underscore) to indicate that they are private ([#141](https://github.com/mathause/mplotutils/pull/141)).
+- The modules ``cartopy_utils``, ``colormaps``, ``map_layout``, ``mpl``, and ``xrcompat``
+  were renamed (added a leading underscore) to indicate that they are private
+  ([#141](https://github.com/mathause/mplotutils/pull/141) and [#142](https://github.com/mathause/mplotutils/pull/142)).
 
 ### Enhancements
 

mplotutils/__init__.py

@@ -14,6 +14,7 @@
 )
 from mplotutils._colorbar import colorbar
 from mplotutils._colormaps import from_levels_and_cmap
+from mplotutils._deprecate import _module_renamed_warning_init
 from mplotutils._hatch import hatch, hatch_map, hatch_map_global
 from mplotutils._map_layout import set_map_layout
 from mplotutils._mpl import _get_renderer
@@ -51,3 +52,29 @@
     # Local copy or not installed with setuptools.
     # Disable minimum version checks on downstream libraries.
     __version__ = "999"
+
+
+def __getattr__(attr):
+
+    m = (
+        "cartopy_utils",
+        "colormaps",
+        "map_layout",
+        "mpl",
+        "xrcompat",
+    )
+
+    import mplotutils
+
+    if attr in m:
+
+        _module_renamed_warning_init(attr)
+
+        # NOTE: could use importlib.import_module() but it registers the function in
+        # sys.modules such that the warning is only called once
+        # return importlib.import_module(f".{attr}", "mplotutils")
+
+        return getattr(mplotutils, f"_{attr}")
+
+    # required for ipython tab completion
+    raise AttributeError(f"module {__name__!r} has no attribute {attr!r}")

mplotutils/_deprecate.py

@@ -107,3 +107,31 @@ def inner(*args, **kwargs):
         return inner
 
     return _decorator
+
+
+def _module_renamed_warning_init(attr):
+
+    old_module = f"mplotutils.{attr}"
+    new_module = f"mplotutils._{attr}"
+
+    msg = (
+        f"``{old_module}`` is deprecated and has been renamed to ``{new_module}`` in v0.6.0.."
+        f" Note that importing ``{new_module}`` is discuraged. Please use"
+        f" functions directly from the  main namespace."
+    )
+
+    warnings.warn(msg, FutureWarning, stacklevel=2)
+
+
+def _module_renamed_warning(attr, submodule):
+
+    old_module = f"mplotutils.{submodule}"
+    new_module = f"mplotutils._{submodule}"
+
+    warnings.warn(
+        f"``{old_module}`` is deprecated and has been renamed to ``{new_module}`` in v0.6.0."
+        f" Note that importing from ``{new_module}`` is discuraged. Please use"
+        f" functions directly from the  main namespace, i.e., ``mplotutils.{attr}``",
+        FutureWarning,
+        stacklevel=3,
+    )

mplotutils/cartopy_utils.py

@@ -0,0 +1,8 @@
+from mplotutils import _cartopy_utils
+from mplotutils._deprecate import _module_renamed_warning
+
+
+def __getattr__(attr_name):
+    attr = getattr(_cartopy_utils, attr_name)
+    _module_renamed_warning(attr_name, "cartopy_utils")
+    return attr

mplotutils/colormaps.py

@@ -0,0 +1,8 @@
+from mplotutils import _colormaps
+from mplotutils._deprecate import _module_renamed_warning
+
+
+def __getattr__(attr_name):
+    attr = getattr(_colormaps, attr_name)
+    _module_renamed_warning(attr_name, "colormaps")
+    return attr

mplotutils/map_layout.py

@@ -0,0 +1,8 @@
+from mplotutils import _map_layout
+from mplotutils._deprecate import _module_renamed_warning
+
+
+def __getattr__(attr_name):
+    attr = getattr(_map_layout, attr_name)
+    _module_renamed_warning(attr_name, "map_layout")
+    return attr

mplotutils/mpl.py

@@ -0,0 +1,8 @@
+from mplotutils import _mpl
+from mplotutils._deprecate import _module_renamed_warning
+
+
+def __getattr__(attr_name):
+    attr = getattr(_mpl, attr_name)
+    _module_renamed_warning(attr_name, "mpl")
+    return attr

mplotutils/tests/test_rename_modules.py

@@ -0,0 +1,62 @@
+import importlib
+
+import pytest
+
+import mplotutils as mpu
+
+DEPRECATED_MODULES = {
+    "cartopy_utils": (
+        "cyclic_dataarray",
+        "sample_data_map",
+        "sample_dataarray",
+        "xlabel_map",
+        "xticklabels",
+        "ylabel_map",
+        "yticklabels",
+    ),
+    "colormaps": ("from_levels_and_cmap",),
+    "map_layout": ("set_map_layout",),
+    "mpl": ("_get_renderer",),
+    "xrcompat": ("infer_interval_breaks",),
+}
+
+
+def test_00_deprecated_not_in_dir():
+
+    dir = mpu.__dir__()
+
+    for module in DEPRECATED_MODULES:
+        assert module not in dir
+
+
+def test_01_in_dir():
+
+    dir = mpu.__dir__()
+
+    assert "hatch" in dir
+
+
+@pytest.mark.parametrize("mod", DEPRECATED_MODULES)
+def test_01_deprecated_modules_from_import(mod):
+
+    with pytest.warns(FutureWarning, match=f"``mplotutils.{mod}`` is deprecated"):
+        importlib.__import__("mplotutils", fromlist=[mod])
+
+
+@pytest.mark.parametrize("mod, functions", DEPRECATED_MODULES.items())
+def test_depm3(mod, functions):
+
+    module = importlib.import_module(f"mplotutils.{mod}")
+
+    for function in functions:
+        with pytest.warns(FutureWarning, match=f"``mplotutils.{mod}`` is deprecated"):
+            getattr(module, function)
+
+
+def test_fcn_warns():
+
+    # NOTE: this is the only import that does not warn
+    import mplotutils.cartopy_utils
+
+    with pytest.warns(FutureWarning):
+        mplotutils.cartopy_utils.sample_data_map(6, 6)

mplotutils/xrcompat.py

@@ -0,0 +1,8 @@
+from mplotutils import _xrcompat
+from mplotutils._deprecate import _module_renamed_warning
+
+
+def __getattr__(attr_name):
+    attr = getattr(_xrcompat, attr_name)
+    _module_renamed_warning(attr_name, "xrcompat")
+    return attr