Correct and test stacklevel of deprecation warnings

The previous default stacklevel wouldn't have shown a confusing origin
of the warning to users.

skimage/util/compare.py

@@ -29,7 +29,7 @@ def wrapper(*args, **kwargs):
             zip(args, ["image0", "image1", "method", "n_tiles"])
         ):
             if i >= 2:
-                warnings.warn(wm_method, category=FutureWarning)
+                warnings.warn(wm_method, category=FutureWarning, stacklevel=2)
             if param in kwargs:
                 raise ValueError(
                     f"{param} passed both as positional and keyword argument."
@@ -40,7 +40,7 @@ def wrapper(*args, **kwargs):
 
         # Account for `image2` if given
         if "image2" in kwargs.keys():
-            warnings.warn(wm_images, category=FutureWarning)
+            warnings.warn(wm_images, category=FutureWarning, stacklevel=2)
 
             # Safely move `image2` to `image1` if that's empty
             if "image1" in kwargs.keys():
@@ -59,7 +59,7 @@ def wrapper(*args, **kwargs):
 
 
 @_rename_image_params
-def compare_images(image0, image1, method='diff', *, n_tiles=(8, 8)):
+def compare_images(image0, image1, *, method='diff', n_tiles=(8, 8)):
     """
     Return an image showing the differences between two images.
 
@@ -68,15 +68,12 @@ def compare_images(image0, image1, method='diff', *, n_tiles=(8, 8)):
     Parameters
     ----------
     image0 : ndarray, shape (M, N)
-        First input image.
-
-        .. versionadded:: 0.23
-    image1 : ndarray, shape (M, N)
-        Second input image. Must be of the same shape as `image0`.
+    image0, image1 : ndarray, shape (M, N)
+        Images to process, must be of the same shape.
 
         .. versionchanged:: 0.23
-            `image1` changed from being the name of the first image to that of
-            the second image.
+            `image1` and `image2` where renamed to `image0` and `image1`
+            respecitively.
     method : string, optional
         Method used for the comparison.
         Valid values are {'diff', 'blend', 'checkerboard'}.

skimage/util/tests/test_compare.py

@@ -2,6 +2,7 @@
 import pytest
 
 from skimage.util.compare import compare_images
+from skimage._shared.testing import assert_stacklevel
 
 
 def test_compare_images_ValueError_shape():
@@ -36,12 +37,32 @@ def test_compare_images_replaced_param():
     img1[3:8, 3:8] = 255
     img2 = np.zeros_like(img1)
     img2[3:8, 0:8] = 255
-    with pytest.warns(FutureWarning):
-        compare_images(image1=img1, image2=img2)
-    with pytest.warns(FutureWarning):
-        compare_images(image0=img1, image2=img2)
-    with pytest.warns(FutureWarning):
-        compare_images(img1, image2=img2)
+    expected_result = np.zeros_like(img1, dtype=np.float64)
+    expected_result[3:8, 0:3] = 1
+
+    regex = ".*Please use `image0, image1`.*"
+    with pytest.warns(FutureWarning, match=regex) as record:
+        result = compare_images(image1=img1, image2=img2)
+    assert_stacklevel(record)
+    np.testing.assert_array_equal(result, expected_result)
+
+    with pytest.warns(FutureWarning, match=regex) as record:
+        result = compare_images(image0=img1, image2=img2)
+    assert_stacklevel(record)
+    np.testing.assert_array_equal(result, expected_result)
+
+    with pytest.warns(FutureWarning, match=regex) as record:
+        result = compare_images(img1, image2=img2)
+    assert_stacklevel(record)
+    np.testing.assert_array_equal(result, expected_result)
+
+    # Test making "method" keyword-only here as well
+    # so whole test can be removed in one go
+    regex = ".*Please pass `method=`.*"
+    with pytest.warns(FutureWarning, match=regex) as record:
+        result = compare_images(img1, img2, "diff")
+    assert_stacklevel(record)
+    np.testing.assert_array_equal(result, expected_result)
 
 
 def test_compare_images_blend():