Improve deprecation system and warning messages

Author: lukelbd

WHATSNEW.rst

@@ -13,15 +13,20 @@
 What's new?
 ===========
 
-This page lists the API changes with each version. Please note that
-when functions and keywords are renamed, they are not removed -- requesting
-the old name will issue a warning rather than an error. Authors are shown next to
-each change. Where not indicated, `Luke Davis`_ was the author.
-
-See the :ref:`author page <authors>` for a list of contributors, and see
-the :ref:`contribution guide <contributions>` if you are interested in
+This page lists the API changes with each version. Authors are shown next to
+each change. Where not indicated, `Luke Davis`_ was the author. See the
+:ref:`author page <authors>` for a list of contributors, and see the
+:ref:`contribution guide <contributions>` if you are interested in
 submitting your own changes.
 
+.. important::
+
+   Please note that when classes, functions, keywords, or settings are deprecated,
+   they are not removed -- using the old syntax will result in a warning rather than
+   an error and preserve the original functionality. Since proplot adheres to `semantic
+   versioning <https://semver.org>`__, we will not consider removing the deprecated
+   syntax until the first major release (i.e., version 1.0.0).
+
 Version 1.0.0 (2022-XX-XX)
 ==========================
 

docs/api.rst

@@ -8,10 +8,27 @@ The comprehensive API reference. All of the below objects are imported
 into the top-level namespace. Use ``help(pplt.object)`` to read
 the docs during a python session.
 
-Please note that the documentation for "wrapper" functions from
-proplot < 0.8 is now found under the individual `~proplot.axes.PlotAxes`
-plotting commands. Using ``help(ax.command)`` during a python session shows both
-the proplot documentation and the original matplotlib documentation.
+Please note that proplot removes the associated documentation when functionality
+is deprecated (see :ref:`What's New <whats_new>`). However, proplot adheres to
+`semantic versioning <https://semver.org>`__, which means old code that uses deprecated
+functionality will 1) still work and 2) issue warnings rather than errors until the
+first major release (i.e. version 1.0.0).
+
+.. important::
+
+   The color transformation functions like `to_rgba` and `scale_luminance` from
+   proplot < 0.10.0 can now be found as methods on the new `~proplot.colors.Color`
+   class. Please see `~proplot.colors.Color` for the relevant documentation. Note that
+   old code that uses commands like ``pplt.to_rgba()`` and ``pplt.scale_luminance()``
+   will still work -- but it will result in a deprecation warning.
+
+.. important::
+
+   The documentation for "wrapper" functions like `standardize_1d` and `cmap_changer`
+   from proplot < 0.8.0 like can now be found under individual `~proplot.axes.PlotAxes`
+   methods like `~proplot.axes.PlotAxes.pcolor`. Please see `~proplot.axes.PlotAxes` for
+   the relevant documentation. Note that calling ``help(ax.method)`` in a python session
+   will show both the proplot documentation and the original matplotlib documentation.
 
 Figure class
 ============

proplot/axes/plot.py

@@ -2092,7 +2092,7 @@ def _parse_color(self, x, y, c, *, apply_cycle=True, infer_rgb=False, **kwargs):
             warnings._warn_proplot(f'Ignoring unused keyword arg(s): {pop}')
         return (c, kwargs)
 
-    @warnings._rename_kwargs('0.6', centers='values')
+    @warnings._rename_kwargs('0.6.0', centers='values')
     def _parse_cmap(
         self, *args,
         cmap=None, cmap_kw=None, c=None, color=None, colors=None,
@@ -4094,5 +4094,5 @@ def _iter_arg_cols(self, *args, label=None, labels=None, values=None, **kwargs):
     _level_parsers = (_parse_level_list, _parse_level_count, _parse_level_lim)
 
     # Rename the shorthands
-    boxes = warnings._rename_objs('0.8', boxes=box)
-    violins = warnings._rename_objs('0.8', violins=violin)
+    boxes = warnings._rename_objs('0.8.0', boxes=box)
+    violins = warnings._rename_objs('0.8.0', violins=violin)

proplot/colors.py

@@ -117,59 +117,59 @@
 ):
     CMAPS_DIVERGING[_cmap_diverging.lower()] = _cmap_diverging.lower()
 CMAPS_REMOVED = {
-    'Blue0': '0.6',
-    'Cool': '0.6',
-    'Warm': '0.6',
-    'Hot': '0.6',
-    'Floral': '0.6',
-    'Contrast': '0.6',
-    'Sharp': '0.6',
-    'Viz': '0.6',
+    'Blue0': '0.6.0',
+    'Cool': '0.6.0',
+    'Warm': '0.6.0',
+    'Hot': '0.6.0',
+    'Floral': '0.6.0',
+    'Contrast': '0.6.0',
+    'Sharp': '0.6.0',
+    'Viz': '0.6.0',
 }
 CMAPS_RENAMED = {
-    'GrayCycle': ('MonoCycle', '0.6'),
-    'Blue1': ('Blues1', '0.7'),
-    'Blue2': ('Blues2', '0.7'),
-    'Blue3': ('Blues3', '0.7'),
-    'Blue4': ('Blues4', '0.7'),
-    'Blue5': ('Blues5', '0.7'),
-    'Blue6': ('Blues6', '0.7'),
-    'Blue7': ('Blues7', '0.7'),
-    'Blue8': ('Blues8', '0.7'),
-    'Blue9': ('Blues9', '0.7'),
-    'Green1': ('Greens1', '0.7'),
-    'Green2': ('Greens2', '0.7'),
-    'Green3': ('Greens3', '0.7'),
-    'Green4': ('Greens4', '0.7'),
-    'Green5': ('Greens5', '0.7'),
-    'Green6': ('Greens6', '0.7'),
-    'Green7': ('Greens7', '0.7'),
-    'Green8': ('Greens8', '0.7'),
-    'Orange1': ('Yellows1', '0.7'),
-    'Orange2': ('Yellows2', '0.7'),
-    'Orange3': ('Yellows3', '0.7'),
-    'Orange4': ('Oranges2', '0.7'),
-    'Orange5': ('Oranges1', '0.7'),
-    'Orange6': ('Oranges3', '0.7'),
-    'Orange7': ('Oranges4', '0.7'),
-    'Orange8': ('Yellows4', '0.7'),
-    'Brown1': ('Browns1', '0.7'),
-    'Brown2': ('Browns2', '0.7'),
-    'Brown3': ('Browns3', '0.7'),
-    'Brown4': ('Browns4', '0.7'),
-    'Brown5': ('Browns5', '0.7'),
-    'Brown6': ('Browns6', '0.7'),
-    'Brown7': ('Browns7', '0.7'),
-    'Brown8': ('Browns8', '0.7'),
-    'Brown9': ('Browns9', '0.7'),
-    'RedPurple1': ('Reds1', '0.7'),
-    'RedPurple2': ('Reds2', '0.7'),
-    'RedPurple3': ('Reds3', '0.7'),
-    'RedPurple4': ('Reds4', '0.7'),
-    'RedPurple5': ('Reds5', '0.7'),
-    'RedPurple6': ('Purples1', '0.7'),
-    'RedPurple7': ('Purples2', '0.7'),
-    'RedPurple8': ('Purples3', '0.7'),
+    'GrayCycle': ('MonoCycle', '0.6.0'),
+    'Blue1': ('Blues1', '0.7.0'),
+    'Blue2': ('Blues2', '0.7.0'),
+    'Blue3': ('Blues3', '0.7.0'),
+    'Blue4': ('Blues4', '0.7.0'),
+    'Blue5': ('Blues5', '0.7.0'),
+    'Blue6': ('Blues6', '0.7.0'),
+    'Blue7': ('Blues7', '0.7.0'),
+    'Blue8': ('Blues8', '0.7.0'),
+    'Blue9': ('Blues9', '0.7.0'),
+    'Green1': ('Greens1', '0.7.0'),
+    'Green2': ('Greens2', '0.7.0'),
+    'Green3': ('Greens3', '0.7.0'),
+    'Green4': ('Greens4', '0.7.0'),
+    'Green5': ('Greens5', '0.7.0'),
+    'Green6': ('Greens6', '0.7.0'),
+    'Green7': ('Greens7', '0.7.0'),
+    'Green8': ('Greens8', '0.7.0'),
+    'Orange1': ('Yellows1', '0.7.0'),
+    'Orange2': ('Yellows2', '0.7.0'),
+    'Orange3': ('Yellows3', '0.7.0'),
+    'Orange4': ('Oranges2', '0.7.0'),
+    'Orange5': ('Oranges1', '0.7.0'),
+    'Orange6': ('Oranges3', '0.7.0'),
+    'Orange7': ('Oranges4', '0.7.0'),
+    'Orange8': ('Yellows4', '0.7.0'),
+    'Brown1': ('Browns1', '0.7.0'),
+    'Brown2': ('Browns2', '0.7.0'),
+    'Brown3': ('Browns3', '0.7.0'),
+    'Brown4': ('Browns4', '0.7.0'),
+    'Brown5': ('Browns5', '0.7.0'),
+    'Brown6': ('Browns6', '0.7.0'),
+    'Brown7': ('Browns7', '0.7.0'),
+    'Brown8': ('Browns8', '0.7.0'),
+    'Brown9': ('Browns9', '0.7.0'),
+    'RedPurple1': ('Reds1', '0.7.0'),
+    'RedPurple2': ('Reds2', '0.7.0'),
+    'RedPurple3': ('Reds3', '0.7.0'),
+    'RedPurple4': ('Reds4', '0.7.0'),
+    'RedPurple5': ('Reds5', '0.7.0'),
+    'RedPurple6': ('Purples1', '0.7.0'),
+    'RedPurple7': ('Purples2', '0.7.0'),
+    'RedPurple8': ('Purples3', '0.7.0'),
 }
 
 # Color constants
@@ -1584,11 +1584,11 @@ def from_list(cls, *args, **kwargs):
 
     # Deprecated
     to_listed = warnings._rename_objs(
-        '0.8',
+        '0.8.0',
         to_listed=to_discrete
     )
     concatenate, punched, truncated, updated = warnings._rename_objs(
-        '0.6',
+        '0.6.0',
         concatenate=append,
         punched=cut,
         truncated=truncate,
@@ -1864,7 +1864,7 @@ def from_file(cls, path, *, warn_on_failure=False):
 
     # Rename methods
     concatenate, truncated, updated = warnings._rename_objs(
-        '0.6',
+        '0.6.0',
         concatenate=append,
         truncated=truncate,
         updated=copy,
@@ -2077,7 +2077,7 @@ def to_continuous(self, name=None, **kwargs):
 
     @classmethod
     @docstring._snippet_manager
-    @warnings._rename_kwargs('0.7', fade='saturation', shade='luminance')
+    @warnings._rename_kwargs('0.7.0', fade='saturation', shade='luminance')
     def from_color(cls, *args, **kwargs):
         """
         Return a simple monochromatic "sequential" colormap that blends from white
@@ -2272,7 +2272,7 @@ def from_list(cls, *args, adjust_grays=True, **kwargs):
 
     # Deprecated
     to_linear_segmented = warnings._rename_objs(
-        '0.8',
+        '0.8.0',
         to_linear_segmented=to_continuous
     )
 
@@ -2341,7 +2341,7 @@ class DiscreteNorm(mcolors.BoundaryNorm):
     # test for class membership, crucially including _process_values(), which
     # if it doesn't detect BoundaryNorm will try to use DiscreteNorm.inverse().
     @warnings._rename_kwargs(
-        '0.7', extend='unique', descending='DiscreteNorm(descending_levels)'
+        '0.7.0', extend='unique', descending='DiscreteNorm(descending_levels)'
     )
     def __init__(self, levels, norm=None, unique=None, step=None, clip=False):
         """
@@ -3026,13 +3026,14 @@ def _translate_deprecated(self, key):
         if not self._has_item(test) and test in CMAPS_REMOVED:
             version = CMAPS_REMOVED[test]
             raise ValueError(
-                f'Proplot colormap {key!r} was removed in version {version}.'
+                f'The colormap name {key!r} was removed in version {version}.'
             )
         if not self._has_item(test) and test in CMAPS_RENAMED:
             test_new, version = CMAPS_RENAMED[test]
             warnings._warn_proplot(
-                f'Colormap {test!r} was renamed in version {version} and will be '
-                f'removed in a future release. Please use {test_new!r} instead.'  # noqa: E501
+                f'The colormap name {test!r} was deprecated in version {version} '
+                f'and may be removed in {warnings._next_release()}. Please use '
+                f'the colormap name {test_new!r} instead.'
             )
             key = re.sub(test, test_new, key, flags=re.IGNORECASE)
         return key
@@ -3118,7 +3119,7 @@ def _set_item(self, key, value):
     PerceptuallyUniformColormap,
     LinearSegmentedNorm,
 ) = warnings._rename_objs(  # noqa: E501
-    '0.8',
+    '0.8.0',
     ListedColormap=DiscreteColormap,
     LinearSegmentedColormap=ContinuousColormap,
     PerceptuallyUniformColormap=PerceptualColormap,

proplot/config.py

@@ -1743,7 +1743,7 @@ def changed(self):
         return _filter_style_dict(rcdict, warn=False)
 
     # Renamed methods
-    load_file = warnings._rename_objs('0.8', load_file=load)
+    load_file = warnings._rename_objs('0.8.0', load_file=load)
 
 
 # Initialize locations
@@ -1764,8 +1764,8 @@ def changed(self):
 
 # Deprecated
 RcConfigurator = warnings._rename_objs(
-    '0.8', RcConfigurator=Configurator,
+    '0.8.0', RcConfigurator=Configurator,
 )
 inline_backend_fmt = warnings._rename_objs(
-    '0.6', inline_backend_fmt=config_inline_backend
+    '0.6.0', inline_backend_fmt=config_inline_backend
 )

proplot/constructor.py

@@ -360,7 +360,7 @@ def _modify_colormap(cmap, *, cut, left, right, reverse, shift, alpha, samples):
 
 
 @warnings._rename_kwargs(
-    '0.8', fade='saturation', shade='luminance', to_listed='discrete'
+    '0.8.0', fade='saturation', shade='luminance', to_listed='discrete'
 )
 def Colormap(
     *args, name=None, listmode='perceptual', filemode='continuous', discrete=False,
@@ -1560,5 +1560,5 @@ def Proj(
 
 # Deprecated
 Colors = warnings._rename_objs(
-    '0.8', Colors=get_colors
+    '0.8.0', Colors=get_colors
 )

proplot/demos.py

@@ -417,8 +417,8 @@ def show_colorspaces(*, luminance=None, saturation=None, hue=None, refwidth=2):
     return fig, axs
 
 
-@warnings._rename_kwargs('0.8', categories='include')
-@warnings._rename_kwargs('0.10', rasterize='rasterized')
+@warnings._rename_kwargs('0.8.0', categories='include')
+@warnings._rename_kwargs('0.10.0', rasterize='rasterized')
 def _draw_bars(
     cmaps, *, source, unknown='User', include=None, ignore=None,
     length=4.0, width=0.2, N=None, rasterized=None,

proplot/figure.py

@@ -511,7 +511,9 @@ def __repr__(self):
     # simply used in the warning message.
     @docstring._obfuscate_kwargs
     @docstring._snippet_manager
-    @warnings._rename_kwargs('0.7', axpad='innerpad', autoformat='pplt.rc.autoformat = {}')  # noqa: E501
+    @warnings._rename_kwargs(
+        '0.7.0', axpad='innerpad', autoformat='pplt.rc.autoformat = {}'
+    )
     def __init__(
         self, *, refnum=None, ref=None, refaspect=None, aspect=None,
         refwidth=None, refheight=None, axwidth=None, axheight=None,
@@ -770,8 +772,8 @@ def _parse_proj(
         if basemap is not None:
             backend = ('cartopy', 'basemap')[bool(basemap)]
             warnings._warn_proplot(
-                f'The {basemap!r} keyword was deprecated in version 0.10 and will be '
-                f'removed in a future release. Please use backend={backend!r} intead.'
+                f'The {basemap!r} keyword was deprecated in version 0.10.0 and will be '
+                f'removed in a future release. Please use backend={backend!r} instead.'
             )
         if isinstance(proj, str):
             proj = proj.lower()
@@ -1463,7 +1465,9 @@ def _align_content():  # noqa: E306
             gs._auto_layout_tight(renderer)
         _align_content()
 
-    @warnings._rename_kwargs('0.10', mathtext_fallback='pplt.rc.mathtext_fallback = {}')
+    @warnings._rename_kwargs(
+        '0.10.0', mathtext_fallback='pplt.rc.mathtext_fallback = {}'
+    )
     @docstring._snippet_manager
     def format(
         self, axs=None, *,

proplot/gridspec.py

@@ -1575,4 +1575,4 @@ def shape(self):
     SubplotGrid._add_command(_src, _name)
 
 # Deprecated
-SubplotsContainer = warnings._rename_objs('0.8', SubplotsContainer=SubplotGrid)
+SubplotsContainer = warnings._rename_objs('0.8.0', SubplotsContainer=SubplotGrid)