From 344dcb2c66b0f2b31ff42121e9e826f6c05d1475 Mon Sep 17 00:00:00 2001 From: Harshit Saxena Date: Mon, 11 May 2026 12:16:25 -0400 Subject: [PATCH] Discourage Lasso widget in docs --- doc/api/next_api_changes/deprecations/19221-HS.rst | 6 ++++++ galleries/examples/event_handling/lasso_demo.py | 6 ++++++ galleries/examples/widgets/lasso_selector_demo_sgskip.py | 7 ++++++- lib/matplotlib/widgets.py | 8 +++++++- 4 files changed, 25 insertions(+), 2 deletions(-) create mode 100644 doc/api/next_api_changes/deprecations/19221-HS.rst diff --git a/doc/api/next_api_changes/deprecations/19221-HS.rst b/doc/api/next_api_changes/deprecations/19221-HS.rst new file mode 100644 index 000000000000..78f686561ed9 --- /dev/null +++ b/doc/api/next_api_changes/deprecations/19221-HS.rst @@ -0,0 +1,6 @@ +``Lasso`` is discouraged +~~~~~~~~~~~~~~~~~~~~~~~~ + +The use of `.Lasso` is discouraged for new code. Use `.LassoSelector` +instead, which follows the selector-widget interface and remains connected +to the Axes until disconnected. diff --git a/galleries/examples/event_handling/lasso_demo.py b/galleries/examples/event_handling/lasso_demo.py index ed493a289993..fdc26e061df0 100644 --- a/galleries/examples/event_handling/lasso_demo.py +++ b/galleries/examples/event_handling/lasso_demo.py @@ -6,6 +6,12 @@ Use a lasso to select a set of points and get the indices of the selected points. A callback is used to change the color of the selected points. +This example uses the low-level `~matplotlib.widgets.Lasso` widget. For new +code, prefer `~matplotlib.widgets.LassoSelector`, which is shown in the +:doc:`/gallery/widgets/lasso_selector_demo_sgskip` example. `~.LassoSelector` +uses the same interface as the other selector widgets and remains connected +until it is disconnected. + .. note:: This example exercises the interactive capabilities of Matplotlib, and this will not appear in the static documentation. Please run this code on your diff --git a/galleries/examples/widgets/lasso_selector_demo_sgskip.py b/galleries/examples/widgets/lasso_selector_demo_sgskip.py index fd2459be4f4f..f4dc66e062f3 100644 --- a/galleries/examples/widgets/lasso_selector_demo_sgskip.py +++ b/galleries/examples/widgets/lasso_selector_demo_sgskip.py @@ -5,9 +5,14 @@ Interactively selecting data points with the lasso tool. -This examples plots a scatter plot. You can then select a few points by drawing +This example plots a scatter plot. You can then select a few points by drawing a lasso loop around the points on the graph. To draw, just click on the graph, hold, and drag it around the points you need to select. + +For most lasso-selection use cases, prefer `~matplotlib.widgets.LassoSelector` +over `~matplotlib.widgets.Lasso`, which is shown in the +:doc:`/gallery/event_handling/lasso_demo` example. `~.LassoSelector` follows +the selector-widget API and stays connected until explicitly disconnected. """ diff --git a/lib/matplotlib/widgets.py b/lib/matplotlib/widgets.py index f27e3f21bec5..2644e5a100e9 100644 --- a/lib/matplotlib/widgets.py +++ b/lib/matplotlib/widgets.py @@ -4376,7 +4376,13 @@ def _clear_without_update(self): class Lasso(AxesWidget): """ - Selection curve of an arbitrary shape. + [*Discouraged*] Selection curve of an arbitrary shape. + + .. admonition:: Discouraged + + The use of `Lasso` is discouraged for new code. Use `LassoSelector` + instead, which uses the selector-widget interface and remains + connected to the Axes until disconnected. The selected path can be used in conjunction with `~matplotlib.path.Path.contains_point` to select data points from an image.