diff --git a/pyproject.toml b/pyproject.toml index 9e87da2c..73f7b83a 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -62,6 +62,8 @@ filterwarnings = [ 'ignore:Passing unrecognized arguments to super:DeprecationWarning', 'ignore:Jupyter is migrating its paths:DeprecationWarning', 'ignore:setDaemon\(\) is deprecated, set the daemon attribute instead:DeprecationWarning', + 'ignore:TriCutTool is deprecated::', + 'ignore:Cut3dTool is deprecated::', ] [tool.bandit] diff --git a/src/plopp/graphics/figure.py b/src/plopp/graphics/figure.py index b7d1e0a0..5ed923c8 100644 --- a/src/plopp/graphics/figure.py +++ b/src/plopp/graphics/figure.py @@ -1,22 +1,13 @@ # SPDX-License-Identifier: BSD-3-Clause # Copyright (c) 2023 Scipp contributors (https://github.com/scipp) -import warnings from typing import Literal from .. import backends -from ..core.typing import VisibleDeprecationWarning - - -def _warn_deprecated(func_name: str, new_func_name: str): - warnings.warn( - f'The function `{func_name}` is deprecated and will be removed in a future ' - f'version. Use `{new_func_name}` instead.', - VisibleDeprecationWarning, - stacklevel=2, - ) +from ..utils import deprecated +@deprecated('Use ``linefigure`` instead.') def figure1d(*args, style: Literal['line'] = 'line', **kwargs): """ Create a figure to represent one-dimensional data from one or more graph node(s). @@ -53,8 +44,6 @@ def figure1d(*args, style: Literal['line'] = 'line', **kwargs): >>> fig = pp.figure1d(in_node, norm='log') """ - _warn_deprecated('figure1d', 'linefigure') - if style == 'line': from .lineview import LineView @@ -63,6 +52,7 @@ def figure1d(*args, style: Literal['line'] = 'line', **kwargs): raise ValueError(f'Unsupported style={style} for figure1d.') +@deprecated('Use ``imagefigure`` instead.') def figure2d(*args, style: Literal['image'] = 'image', **kwargs): """ Create a figure to represent two-dimensional data from a graph node. @@ -91,8 +81,6 @@ def figure2d(*args, style: Literal['image'] = 'image', **kwargs): >>> fig = pp.figure2d(in_node, norm='log') """ - _warn_deprecated('figure2d', 'imagefigure') - if style == 'image': from .imageview import ImageView @@ -101,6 +89,7 @@ def figure2d(*args, style: Literal['image'] = 'image', **kwargs): raise ValueError(f'Unsupported style={style} for figure2d.') +@deprecated('Use ``scatter3dfigure`` instead.') def figure3d(*args, style: Literal['scatter'] = 'scatter', **kwargs): """ Create a figure to represent three-dimensional data from a graph node. @@ -129,8 +118,6 @@ def figure3d(*args, style: Literal['scatter'] = 'scatter', **kwargs): >>> fig = pp.figure3d(in_node, norm='log') """ - _warn_deprecated('figure3d', 'scatter3dfigure') - if style == 'scatter': from .scatter3dview import Scatter3dView diff --git a/src/plopp/graphics/imageview.py b/src/plopp/graphics/imageview.py index 51d5864f..a23922f2 100644 --- a/src/plopp/graphics/imageview.py +++ b/src/plopp/graphics/imageview.py @@ -119,6 +119,20 @@ def imagefigure(*args, **kwargs): Create a figure to represent two-dimensional data from one or more graph node(s). .. versionadded:: 24.04.0 + + Examples + -------- + Create an input node and attach an ``imagefigure`` as a view: + + >>> da = pp.data.data2d() + >>> in_node = pp.Node(da) + >>> fig = pp.imagefigure(in_node) + + With a customization argument to make the color scale logarithmic: + + >>> da = pp.data.data2d() + >>> in_node = pp.Node(da) + >>> fig = pp.imagefigure(in_node, norm='log') """ return backends.figure2d(ImageView, *args, **kwargs) diff --git a/src/plopp/graphics/lineview.py b/src/plopp/graphics/lineview.py index 6d771dce..7f55da33 100644 --- a/src/plopp/graphics/lineview.py +++ b/src/plopp/graphics/lineview.py @@ -122,6 +122,28 @@ def linefigure(*args, **kwargs): Create a figure to represent one-dimensional data from one or more graph node(s). .. versionadded:: 24.04.0 + + Examples + -------- + Create an input node and attach a ``linefigure`` as a view: + + >>> da = pp.data.data1d() + >>> in_node = pp.Node(da) + >>> fig = pp.linefigure(in_node) + + Visualize two data arrays on the same figure: + + >>> a = pp.data.data1d() + >>> b = 3 * a + >>> a_node = pp.Node(a) + >>> b_node = pp.Node(b) + >>> fig = pp.linefigure(a_node, b_node) + + With a customization argument to make the vertical scale logarithmic: + + >>> da = pp.data.data1d() + >>> in_node = pp.Node(da) + >>> fig = pp.linefigure(in_node, norm='log') """ return backends.figure2d(LineView, *args, **kwargs) diff --git a/src/plopp/graphics/scatter3dview.py b/src/plopp/graphics/scatter3dview.py index 1976df8e..5c95483a 100644 --- a/src/plopp/graphics/scatter3dview.py +++ b/src/plopp/graphics/scatter3dview.py @@ -192,6 +192,20 @@ def scatter3dfigure(*args, **kwargs): Create a figure to represent three-dimensional data from one or more graph node(s). .. versionadded:: 24.04.0 + + Examples + -------- + Create an input node and attach a ``scatter3dfigure`` as a view: + + >>> da = pp.data.scatter() + >>> in_node = pp.Node(da) + >>> fig = pp.scatter3dfigure(in_node) + + With a customization argument to make the color scale logarithmic: + + >>> da = pp.data.scatter() + >>> in_node = pp.Node(da) + >>> fig = pp.scatter3dfigure(in_node, norm='log') """ return backends.figure3d(Scatter3dView, *args, **kwargs) diff --git a/src/plopp/graphics/scatterview.py b/src/plopp/graphics/scatterview.py index 6965b7a3..ee541715 100644 --- a/src/plopp/graphics/scatterview.py +++ b/src/plopp/graphics/scatterview.py @@ -94,6 +94,20 @@ def scatterfigure(*args, **kwargs): Create a figure to represent scatter data from one or more graph node(s). .. versionadded:: 24.04.0 + + Examples + -------- + Create an input node and attach a ``scatterfigure`` as a view: + + >>> da = pp.data.scatter() + >>> in_node = pp.Node(da) + >>> fig = pp.scatterfigure(in_node) + + A scatter figure with a color bar (using the data values for the color scale): + + >>> da = pp.data.scatter() + >>> in_node = pp.Node(da) + >>> fig = pp.scatterfigure(in_node, cbar=True) """ return backends.figure2d(ScatterView, *args, **kwargs) diff --git a/src/plopp/utils.py b/src/plopp/utils.py new file mode 100644 index 00000000..9a842ade --- /dev/null +++ b/src/plopp/utils.py @@ -0,0 +1,27 @@ +# SPDX-License-Identifier: BSD-3-Clause +# Copyright (c) 2024 Scipp contributors (https://github.com/scipp) + +import functools +import warnings +from typing import Callable + +from .core.typing import VisibleDeprecationWarning + + +def deprecated(message: str = '') -> Callable: + def decorator(function: Callable) -> Callable: + @functools.wraps(function) + def wrapper(*args, **kwargs): + warnings.warn( + f'{function.__name__} is deprecated. {message}', + VisibleDeprecationWarning, + stacklevel=2, + ) + return function(*args, **kwargs) + + return wrapper + + return decorator + + +__all__ = ['deprecated'] diff --git a/src/plopp/widgets/cut3d.py b/src/plopp/widgets/cut3d.py index 60d00d21..994b0c73 100644 --- a/src/plopp/widgets/cut3d.py +++ b/src/plopp/widgets/cut3d.py @@ -10,11 +10,13 @@ import scipp as sc from ..core import View, node +from ..utils import deprecated from .debounce import debounce from .style import BUTTON_LAYOUT from .tools import PlusMinusTool +@deprecated("Use ``Clip3dTool`` instead.") class Cut3dTool(ipw.HBox): """ A tool that provides a slider to extract a plane of points in a three-dimensional @@ -220,11 +222,14 @@ def decrease_thickness(self): self._add_cut() +@deprecated("Use ``ClippingPlanes`` instead.") class TriCutTool(ipw.HBox): """ A collection of :class:`Cut3dTool` to make spatial cuts in the X, Y, and Z directions on a three-dimensional scatter plot. + .. deprecated:: v24.04.0 + Parameters ---------- fig: