MNT little refactor and doc improvement for metadata routing consumes() methods (scikit-learn#31703)

Co-authored-by: Lucy Liu <[email protected]>

Author: StefanieSenger

sklearn/tests/test_metadata_routing.py

@@ -638,7 +638,7 @@ class Consumer(BaseEstimator):
 @config_context(enable_metadata_routing=True)
 def test_metadata_request_consumes_method():
     """Test that MetadataRequest().consumes() method works as expected."""
-    request = MetadataRouter(owner="test")
+    request = MetadataRequest(owner="test")
     assert request.consumes(method="fit", params={"foo"}) == set()
 
     request = MetadataRequest(owner="test")

sklearn/utils/_metadata_requests.py

@@ -501,26 +501,26 @@ def _route_params(self, params, parent, caller):
         return res
 
     def _consumes(self, params):
-        """Check whether the given metadata are consumed by this method.
+        """Return subset of `params` consumed by the method that owns this instance.
 
         Parameters
         ----------
         params : iterable of str
-            An iterable of parameters to check.
+            An iterable of parameter names to test for consumption.
 
         Returns
         -------
-        consumed : set of str
-            A set of parameters which are consumed by this method.
+        consumed_params : set of str
+            A subset of parameters from `params` which are consumed by this method.
         """
         params = set(params)
-        res = set()
-        for prop, alias in self._requests.items():
-            if alias is True and prop in params:
-                res.add(prop)
+        consumed_params = set()
+        for metadata_name, alias in self._requests.items():
+            if alias is True and metadata_name in params:
+                consumed_params.add(metadata_name)
             elif isinstance(alias, str) and alias in params:
-                res.add(alias)
-        return res
+                consumed_params.add(alias)
+        return consumed_params
 
     def _serialize(self):
         """Serialize the object.
@@ -571,22 +571,27 @@ def __init__(self, owner):
             )
 
     def consumes(self, method, params):
-        """Check whether the given metadata are consumed by the given method.
+        """Return params consumed as metadata in a :term:`consumer`.
+
+        This method returns the subset of given `params` that are consumed by the
+        given `method`. It can be used to check if parameters are used as metadata in
+        the specified method of the :term:`consumer` that owns this `MetadataRequest`
+        instance.
 
         .. versionadded:: 1.4
 
         Parameters
         ----------
         method : str
-            The name of the method to check.
+            The name of the method for which to determine consumed parameters.
 
         params : iterable of str
-            An iterable of parameters to check.
+            An iterable of parameter names to test for consumption.
 
         Returns
         -------
-        consumed : set of str
-            A set of parameters which are consumed by the given method.
+        consumed_params : set of str
+            A subset of parameters from `params` which are consumed by the given method.
         """
         return getattr(self, method)._consumes(params=params)
 
@@ -900,35 +905,42 @@ def add(self, *, method_mapping, **objs):
         return self
 
     def consumes(self, method, params):
-        """Check whether the given metadata is consumed by the given method.
+        """Return params consumed as metadata in a :term:`router` or its sub-estimators.
+
+        This method returns the subset of `params` that are consumed by the
+        `method`. A `param` is considered consumed if it is used in the specified
+        method of the :term:`router` itself or any of its sub-estimators (or their
+        sub-estimators).
 
         .. versionadded:: 1.4
 
         Parameters
         ----------
         method : str
-            The name of the method to check.
+            The name of the method for which to determine consumed parameters.
 
         params : iterable of str
-            An iterable of parameters to check.
+            An iterable of parameter names to test for consumption.
 
         Returns
         -------
-        consumed : set of str
-            A set of parameters which are consumed by the given method.
+        consumed_params : set of str
+            A subset of parameters from `params` which are consumed by this method.
         """
-        res = set()
+        consumed_params = set()
         if self._self_request:
-            res = res | self._self_request.consumes(method=method, params=params)
+            consumed_params.update(
+                self._self_request.consumes(method=method, params=params)
+            )
 
         for _, route_mapping in self._route_mappings.items():
             for caller, callee in route_mapping.mapping:
                 if caller == method:
-                    res = res | route_mapping.router.consumes(
-                        method=callee, params=params
+                    consumed_params.update(
+                        route_mapping.router.consumes(method=callee, params=params)
                     )
 
-        return res
+        return consumed_params
 
     def _get_param_names(self, *, method, return_alias, ignore_self_request):
         """Get names of all metadata that can be consumed or routed by specified \