From 889a6e7b955ddd8a9700e7afa4af85deb67ec393 Mon Sep 17 00:00:00 2001 From: Mathias Hauser Date: Mon, 4 Nov 2024 11:46:52 +0100 Subject: [PATCH] Rename deprecation (#142) * module renaming deprecation * changelog * add version info --- CHANGELOG.md | 4 +- mplotutils/__init__.py | 27 +++++++++++ mplotutils/_deprecate.py | 28 +++++++++++ mplotutils/cartopy_utils.py | 8 ++++ mplotutils/colormaps.py | 8 ++++ mplotutils/map_layout.py | 8 ++++ mplotutils/mpl.py | 8 ++++ mplotutils/tests/test_rename_modules.py | 62 +++++++++++++++++++++++++ mplotutils/xrcompat.py | 8 ++++ 9 files changed, 160 insertions(+), 1 deletion(-) create mode 100644 mplotutils/cartopy_utils.py create mode 100644 mplotutils/colormaps.py create mode 100644 mplotutils/map_layout.py create mode 100644 mplotutils/mpl.py create mode 100644 mplotutils/tests/test_rename_modules.py create mode 100644 mplotutils/xrcompat.py diff --git a/CHANGELOG.md b/CHANGELOG.md index c503f89..549e455 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/mplotutils/__init__.py b/mplotutils/__init__.py index a5a26be..b5029c0 100644 --- a/mplotutils/__init__.py +++ b/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}") diff --git a/mplotutils/_deprecate.py b/mplotutils/_deprecate.py index 8345ff0..d85f082 100644 --- a/mplotutils/_deprecate.py +++ b/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, + ) diff --git a/mplotutils/cartopy_utils.py b/mplotutils/cartopy_utils.py new file mode 100644 index 0000000..b9344ad --- /dev/null +++ b/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 diff --git a/mplotutils/colormaps.py b/mplotutils/colormaps.py new file mode 100644 index 0000000..2c5edd8 --- /dev/null +++ b/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 diff --git a/mplotutils/map_layout.py b/mplotutils/map_layout.py new file mode 100644 index 0000000..6c683d1 --- /dev/null +++ b/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 diff --git a/mplotutils/mpl.py b/mplotutils/mpl.py new file mode 100644 index 0000000..f6ed3c4 --- /dev/null +++ b/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 diff --git a/mplotutils/tests/test_rename_modules.py b/mplotutils/tests/test_rename_modules.py new file mode 100644 index 0000000..08bf6ac --- /dev/null +++ b/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) diff --git a/mplotutils/xrcompat.py b/mplotutils/xrcompat.py new file mode 100644 index 0000000..17fb0e5 --- /dev/null +++ b/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