Merge branch 'docstub-fixes-III' of github.com:mkcor/scikit-image into docstub-fixes-III

Author: mkcor

.github/workflows/typing.yml

@@ -37,22 +37,12 @@ jobs:
           cache: "pip"
           cache-dependency-path: "requirements/*.txt"
 
-      - name: Install build dependencies
-        env:
-          PIP_FLAGS: ${{ matrix.PIP_FLAGS }}
-        run: |
-          source .github/scripts/setup-build-env.sh
-
-      - name: Build and install from source
-        run: |
-          pip install -v --no-build-isolation .
-
       - name: Install docstub
         run: |
           pip install docstub~=0.6.0
           docstub --version
 
-      - name: Create stubs with docstub
+      - name: Create skimage-stubs with docstub
         shell: bash
         run: |
           echo -e "## docstub output\n\`\`\`" >> $GITHUB_STEP_SUMMARY
@@ -62,6 +52,29 @@ jobs:
            2>&1 | tee -a $GITHUB_STEP_SUMMARY)
            echo -e "\`\`\`" >> $GITHUB_STEP_SUMMARY
 
+      - name: Create skimage2-stubs with docstub
+        shell: bash
+        run: |
+          echo -e "## docstub output\n\`\`\`" >> $GITHUB_STEP_SUMMARY
+          (set -o pipefail && \
+           docstub run --verbose --group-errors \
+                       --out-dir ${MYPYPATH}/skimage2 src/skimage2/ \
+           2>&1 | tee -a $GITHUB_STEP_SUMMARY)
+           echo -e "\`\`\`" >> $GITHUB_STEP_SUMMARY
+
+      # Not needed yet, since we don't run mypy.stubtest or similar
+      # which would require importing scikit-image.
+      #
+      #      - name: Install build dependencies
+      #        env:
+      #          PIP_FLAGS: ${{ matrix.PIP_FLAGS }}
+      #        run: |
+      #          source .github/scripts/setup-build-env.sh
+      #
+      #      - name: Build and install from source
+      #        run: |
+      #          pip install -v --no-build-isolation .
+
       - uses: actions/upload-artifact@v4
         with:
           name: skimage-stubs

src/skimage/_shared/utils.py

@@ -205,11 +205,23 @@ def __repr__(cls):
 
 
 class DEPRECATED(metaclass=PatchClassRepr):
-    """Signal value to help with deprecating parameters that use None.
+    """Signal that a deprecated parameter has not been set.
 
-    This is a proxy object, used to signal that a parameter has not been set.
     This is useful if ``None`` is already used for a different purpose or just
     to highlight a deprecated parameter in the signature.
+
+    This is a sentinel and not meant to be initialized.
+    """
+
+
+class DEPRECATED_GOT_VALUE(metaclass=PatchClassRepr):
+    """Signal that a value was passed to a deprecated parameter.
+
+    Used by :class:`deprecate_parameter` to replace values that were passed to
+    deprecated parameters. This allows further handling of the deprecated case
+    inside the decorated function.
+
+    This is a sentinel and not meant to be initialized.
     """
 
 
@@ -228,9 +240,13 @@ class deprecate_parameter:
     template : str, optional
         If given, this message template is used instead of the default one.
     new_name : str, optional
-        If given, the default message will recommend the new parameter name and an
-        error will be raised if the user uses both old and new names for the
-        same parameter.
+        The name of a new parameter replacing the deprecated one. If given:
+        - The default message will recommend the new parameter name.
+        - Values passed to `deprecated_name` are replaced with
+          :class:`DEPRECATED_GOT_VALUE`, and the replaced value is passed to
+          `new_name` instead.
+        - An error will be raised if the user uses both `deprecated_name` and
+          `new_name`.
     modify_docstring : bool, optional
         If the wrapped function has a docstring, add the deprecated parameters
         to the "Other Parameters" section.
@@ -267,6 +283,7 @@ class deprecate_parameter:
     """
 
     DEPRECATED = DEPRECATED  # Make signal value accessible for convenience
+    DEPRECATED_GOT_VALUE = DEPRECATED_GOT_VALUE
 
     remove_parameter_template = (
         "Parameter `{deprecated_name}` is deprecated since version "
@@ -341,21 +358,20 @@ def fixed_func(*args, **kwargs):
             deprecated_value = DEPRECATED
             new_value = DEPRECATED
 
-            # Extract value of deprecated parameter
+            # Extract value of deprecated parameter and overwrite with
+            # DEPRECATED_GOT_VALUE if replacement exists
             if len(args) > deprecated_idx:
                 deprecated_value = args[deprecated_idx]
-                # Overwrite old with DEPRECATED if replacement exists
                 if self.new_name is not None:
                     args = (
                         args[:deprecated_idx]
-                        + (DEPRECATED,)
+                        + (DEPRECATED_GOT_VALUE,)
                         + args[deprecated_idx + 1 :]
                     )
             if self.deprecated_name in kwargs.keys():
                 deprecated_value = kwargs[self.deprecated_name]
-                # Overwrite old with DEPRECATED if replacement exists
                 if self.new_name is not None:
-                    kwargs[self.deprecated_name] = DEPRECATED
+                    kwargs[self.deprecated_name] = DEPRECATED_GOT_VALUE
 
             # Extract value of new parameter (if present)
             if new_idx is not False and len(args) > new_idx:

src/skimage/morphology/misc.py

@@ -2,7 +2,6 @@
 
 import numpy as np
 import functools
-import warnings
 from scipy import ndimage as ndi
 from scipy.spatial import cKDTree
 
@@ -67,7 +66,7 @@ def _check_dtype_supported(ar):
     "its value, while the previous parameter only removed smaller ones.",
 )
 def remove_small_objects(
-    ar, min_size=DEPRECATED, connectivity=1, *, max_size=64, out=None
+    ar, min_size=DEPRECATED, connectivity=1, *, max_size=63, out=None
 ):
     """Remove objects smaller than the specified size.
 
@@ -81,7 +80,7 @@ def remove_small_objects(
     ar : ndarray (arbitrary shape, int or bool type)
         The array containing the objects of interest. If the array type is
         int, the ints must be non-negative.
-    max_size : int, optional (default: 64)
+    max_size : int, optional
         Remove objects whose contiguous area (or volume, in N-D) contains this
         number of pixels or fewer.
 
@@ -167,12 +166,12 @@ def remove_small_objects(
             "Did you mean to use a boolean array?"
         )
 
-    if min_size is not DEPRECATED:
-        # Exclusive threshold is deprecated behavior
-        too_small = component_sizes < min_size
-    else:
-        # New behavior uses inclusive threshold
-        too_small = component_sizes <= max_size
+    if min_size is deprecate_parameter.DEPRECATED_GOT_VALUE:
+        # Old parameter with exclusive threshold (< instead of <=) was used and
+        # forwarded to `max_size`, correct for this
+        max_size -= 1
+
+    too_small = component_sizes <= max_size
     too_small_mask = too_small[ccs]
     out[too_small_mask] = 0
 
@@ -189,15 +188,15 @@ def remove_small_objects(
     "its value, while the previous parameter only removed smaller ones.",
 )
 def remove_small_holes(
-    ar, area_threshold=DEPRECATED, connectivity=1, *, max_size=64, out=None
+    ar, area_threshold=DEPRECATED, connectivity=1, *, max_size=63, out=None
 ):
     """Remove contiguous holes smaller than the specified size.
 
     Parameters
     ----------
     ar : ndarray (arbitrary shape, int or bool type)
         The array containing the connected components of interest.
-    max_size : int, optional (default: 64)
+    max_size : int, optional
         Remove holes whose contiguous area (or volume, in N-D) contains this
         number of pixels or fewer.
 
@@ -278,20 +277,18 @@ def remove_small_holes(
     # Creating the inverse of ar
     np.logical_not(ar, out=out)
 
+    if area_threshold is deprecate_parameter.DEPRECATED_GOT_VALUE:
+        # Old parameter with exclusive threshold (< instead of <=) was used and
+        # forwarded to `max_size`, correct for this
+        max_size -= 1
+
     # removing small objects from the inverse of ar
-    with warnings.catch_warnings():
-        warnings.filterwarnings(
-            "ignore",
-            message="Parameter `min_size` is deprecated",
-            category=FutureWarning,
-        )
-        out = remove_small_objects(
-            out,
-            min_size=area_threshold,
-            max_size=max_size,
-            connectivity=connectivity,
-            out=out,
-        )
+    out = remove_small_objects(
+        out,
+        max_size=max_size,
+        connectivity=connectivity,
+        out=out,
+    )
 
     np.logical_not(out, out=out)
 

tests/skimage/_shared/test_utils.py

@@ -15,6 +15,7 @@
     deprecate_func,
     deprecate_parameter,
     DEPRECATED,
+    DEPRECATED_GOT_VALUE,
     FailedEstimationAccessError,
     FailedEstimation,
 )
@@ -356,7 +357,7 @@ def test_warning_replaced_param(self):
         with pytest.warns(FutureWarning, match=match):
             assert _func_replace_params(1, 2) == (
                 1,
-                DEPRECATED,
+                DEPRECATED_GOT_VALUE,
                 DEPRECATED,
                 None,
                 2,
@@ -366,8 +367,8 @@ def test_warning_replaced_param(self):
         with pytest.warns(FutureWarning, match=match) as records:
             assert _func_replace_params(1, 2, 3) == (
                 1,
-                DEPRECATED,
-                DEPRECATED,
+                DEPRECATED_GOT_VALUE,
+                DEPRECATED_GOT_VALUE,
                 3,
                 2,
                 None,
@@ -379,7 +380,7 @@ def test_warning_replaced_param(self):
         with pytest.warns(FutureWarning, match=match):
             assert _func_replace_params(1, old0=2) == (
                 1,
-                DEPRECATED,
+                DEPRECATED_GOT_VALUE,
                 DEPRECATED,
                 None,
                 2,
@@ -390,7 +391,7 @@ def test_warning_replaced_param(self):
             assert _func_replace_params(1, old1=3) == (
                 1,
                 DEPRECATED,
-                DEPRECATED,
+                DEPRECATED_GOT_VALUE,
                 3,
                 None,
                 None,

tests/skimage/morphology/test_misc.py

@@ -122,15 +122,24 @@ def test_negative_input():
 
 def test_remove_small_objects_deprecated_min_size():
     expected = np.array([[0, 0, 0, 0, 0], [1, 1, 1, 0, 0], [1, 1, 1, 0, 0]], dtype=bool)
+    zeros = np.zeros_like(expected)
 
-    # This is fine
-    observed = remove_small_objects(test_object_image, max_size=3)
+    # New max_size=6 filters all objects without warning
+    observed = remove_small_objects(test_object_image, max_size=6)
+    assert_array_equal(observed, zeros)
+    # New max_size=5 leaves on object of size 6 without warning
+    observed = remove_small_objects(test_object_image, max_size=5)
     assert_array_equal(observed, expected)
 
-    # Using area_threshold= warns
+    # Deprecated min_size=7 warns and filters all objects
     regex = "Parameter `min_size` is deprecated"
     with pytest.warns(FutureWarning, match=regex) as record:
-        observed = remove_small_objects(test_object_image, min_size=5)
+        observed = remove_small_objects(test_object_image, min_size=7)
+    assert_stacklevel(record)
+    assert_array_equal(observed, zeros)
+    # Deprecated min_size=6 warns leaves on object of size 6
+    with pytest.warns(FutureWarning, match=regex) as record:
+        observed = remove_small_objects(test_object_image, min_size=6)
     assert_stacklevel(record)
     assert_array_equal(observed, expected)