MNT Refactor and deprecate `get_metadata_routing` method in `_MetadataRequester` #31695

StefanieSenger · 2025-07-03T08:06:24Z

What does this implement/fix? Explain your changes.

This PR de-couples the double-handling of MetadataRouter and MetadataRequest objects in metadata routing ( a bit), by not using the get_metadata_routing method in MetadataRequest anymore, but instead to directly use _get_metadata_request.

This change has affect in several parts of our metadata routing implementation and the tests and there simplifies the code and makes it more intuitive to read.

The goal of this PR is to increase maintainability.

While at it, I also:

re-named __metadata_request__* class attribute into __metadata_request__{method} and made clear to mention its a class attribute in our internal documentation to make it easier to distinguish it from the _metadata_request instance attribute present in consumers at first sight
made some other small improvements for the external or internal documentation in metadata routing

github-actions · 2025-07-03T08:07:19Z

✔️ Linting Passed

All linting checks passed. Your pull request is in excellent shape! ☀️

_{Generated for commit: 6f97885. Link to the linter CI: here}

StefanieSenger · 2025-07-04T13:55:05Z

sklearn/tests/test_base.py

+    with pytest.warns(UserWarning, match="`transform` method which consumes metadata"):
+        rct = RoutingCustomTransformer(
+            estimator=CustomTransformer()
+            .set_fit_request(metadata=True)
+            .set_transform_request(metadata=True)
        )
+        rct.fit_transform(X=[[1]], metadata="metadata")


This test was added to make sure the warning is also shown when a transformer is not a pure consumer (but also a router). It refers to the change in sklearn.base.TransformerMixin.fit_transform.

StefanieSenger · 2025-07-04T14:06:04Z

sklearn/tests/test_metadata_routing.py

-def test_default_requests():
-    class OddEstimator(BaseEstimator):
+def test_class_level_requests():
+    class StubEstimator(BaseEstimator):


I'm renaming OddEstimator because the old naming implies we are intentionally demonstrating wrong usage, but that's not our purpose here.

StefanieSenger · 2025-07-04T14:08:37Z

sklearn/tests/test_metadata_routing.py

@@ -210,19 +210,19 @@ def test_request_type_is_valid(val, res):


 @config_context(enable_metadata_routing=True)
-def test_default_requests():
-    class OddEstimator(BaseEstimator):
+def test_class_level_requests():


I'm renaming test_default_requests because the term "default" is not referring to default / auto routing here and could be mis-understood. What is meant are the class level requests.

StefanieSenger · 2025-07-05T15:51:21Z

Log of my though process (that hopefully helps me move forwards):

The de-coupeling of _get_metadata_request for consumers and get_metadata_routing that was previously used in both consumers and routers and is now only used in routers is a separate issue than removing the add_self_request in routers by using their _get_metadata_request method, that is still present in them.
I understand I should do it in the same PR nevertheless.

I wonder if we want to fully automate the setting of self requests, or if it should be integrated in MetadataRouter.add(). But if the latter, I wonder if it really makes things simpler, because we would force estimator developers to define a method_mapping in .add, that is not easily available for self requests (or only in a hacky way).
So I tend to fully automate, which means that I'd have to manipulate MetadataRouter.__init__(). I have hardly seen us add any functionality to any init method in scikit-learn, and I think for a good reason (predictability or so?). Still, I will make a suggestion to automate the setting of self requests for router, because otherwise, we force us and developers of custom meta-estimators to pass a complicated method mapping into MetadataRouter.add()...

Since then I need to pass an object into MetadataRouter.__init__(), so I can create a self request, I wonder if I should make the existing owner become an object type, instead of a string, or if I should add a new init param that would be the object. Maybe better to pass a new param, because then the owner string can still get a user-defined name?

But potentially, those could both be merged into the same param, since passing MetadataRouter(owner=self.__class__.__name__, owning_obj=self) seems a bit unnecessary.

StefanieSenger · 2025-07-05T16:56:38Z

I understood that this PR cannot do much about the double-handling of MetadataRouter and MetadataRequest objects (which I had thought it was intending in the beginning), because that depends on several other places and choices taken. But it does part of the job by taking care of certain methods. I will update the PR title to better fit that.

StefanieSenger · 2025-07-05T17:14:58Z

I've experimented with my above idea to add a self-request automatically to routers, but it fails for routers that are pure routers but not also consumers. Given that, I no longer see a benefit in removing or refining the add_self_request method from MetadataRouter. We would still require some input from estimator developers on whether a self request should be added or not.

If that input is done by calling MetadataRouter().add_self_request(self) in get_metadata_routing() or through - in the simplest case, boolean paramater (like add_self_request=True) feels like an implementation detail.

Also, the original change of this PR, the de-tangling of _get_metadata_request and get_metadata_routing methods for consumers doesn't provide a new possibility here, because MetadataRouter().add_self_request had already internally used obj._get_metadata_request().

At this point, I am tempted to think this refactoring is complete, unless there is some specific thing that we want to do with add_self_request?

This PR makes the code more readable, because we can clearly see if we deal with a consumer based on the method called on an object. It also adds some improvements to the internal and the API docs and personally, it has given me more insights and more ideas for refactorings (which I will open separate PRs for).

What is left that I will go through our docs and examples to check whether the right method is used everywhere. I will do that and then un-draft this PR. Do you consider it complete, @adrinjalali?

StefanieSenger · 2025-07-05T14:46:42Z

sklearn/utils/_metadata_requests.py

@@ -46,15 +45,20 @@
 MetadataRouter
 ~~~~~~~~~~~~~~

+The ``MetadataRouter`` objects are constructed via a `get_metadata_routing` method,


The MetadataRouter objects are constructed via a get_metadata_routing method

@adrinjalali, Do you think it makes sense to rename get_metadata_routing into get_metadata_router?
That would be more precise and we spare people to wonder about whether there is a difference between "metadata router" and "metadata routing". In fact, this method returns a MetadataRouter object.

That would be for a new PR and could be done without deprecation (because we are still in experimental stage), I believe?

I wouldn't mind the rename, but needs to go through a deprecation cycle. Maybe a different PR.

I think the renaming would be very useful for people unfamiliar with metadata routing like me: _get_metadata_request returns a MetadataRequest, get_metadata_router returns a MetadataRouter, all is clear. So +1 for a follow-up PR with the renaming !

…build]

StefanieSenger · 2025-07-05T20:54:20Z

sklearn/utils/_metadata_requests.py

-    Consumer-only classes such as simple estimators return a serialized
-    version of this class as the output of `get_metadata_routing()`.
-


That's not true (anymore).

get_routing_for_object(), _get_metadata_request() and get_metadata_routing() all return unserialised output.

StefanieSenger · 2025-07-23T11:53:51Z

sklearn/utils/_metadata_requests.py

@@ -1529,20 +1532,6 @@ def _get_metadata_request(self):

        return requests

-    def get_metadata_routing(self):


A side effect of this change is that this method won't be displayed in the docs for the consumers anymore. I don't think it's too bad, since we want users to use get_routing_for_object anyways.

I think we should also do a single release deprecation cycle for this (shorter than usual).

StefanieSenger · 2025-08-16T23:51:03Z

@adrinjalali, I did the deprecation of get_metadata_routing for estimators that are consumers and would like to do the deprecation of the method name for routers (get_metadata_router instead, see #31695) in a separate PR after this PR got merged (but before the next release).

adrinjalali

I think otherwise LGTM.

adrinjalali · 2025-08-20T13:58:57Z

sklearn/utils/_metadata_requests.py

+        hasattr(_obj, "get_metadata_routing")
+        or hasattr(_obj, "_get_metadata_request")
+        or isinstance(_obj, MetadataRouter)
+    ):
        raise AttributeError(
            f"The given object ({_obj.__class__.__name__!r}) needs to either"
            " implement the routing method `get_metadata_routing` or be a"


this error message is now wrong for simple consumers which do not inherit from BaseEstimator.

Should'nt we limit the scope of process_routing to routers (eg a meta-estimator) only ? It seems here that we allow simple consumers and MetadataRouter instances as well. According to the docstring its only use is inside routers. Are they cases where we need to call it on simple consumers or MetadataRouter instances ? If not, maybe we should raise an error (which could help debugging).

Oh my, when I added that condition, it had made sense to me and now I cannot explain it anymore ... 😅

I now think you are right and I have removed the new condition, @antoinebaker.

On the question whether we ever call process_routing on MetadataRouter instances: It seems we do that in some of the tests in the test_metaestimators_metadata_routing.py module. But we shouldn't modify code just to match a test. Instead, I think the tests would need to be different / less abstract.

antoinebaker

Thanks @StefanieSenger for the PR, it does improve the code readability. Being unfamiliar with the metadata routing code, I had some difficulty understanding which object was returned by the get_metadata_routing methods, but it's much clearer now.

Here is a first round of comments, I'll do another pass later on, as I feel I don't fully grasp the metadata routing mechanics yet !

antoinebaker · 2025-08-29T08:50:13Z

sklearn/utils/_metadata_requests.py

@@ -46,15 +45,20 @@
 MetadataRouter
 ~~~~~~~~~~~~~~

+The ``MetadataRouter`` objects are constructed via a `get_metadata_routing` method,


I think the renaming would be very useful for people unfamiliar with metadata routing like me: _get_metadata_request returns a MetadataRequest, get_metadata_router returns a MetadataRouter, all is clear. So +1 for a follow-up PR with the renaming !

sklearn/utils/_metadata_requests.py

antoinebaker · 2025-08-29T09:12:30Z

sklearn/utils/_metadata_requests.py

@@ -91,8 +94,7 @@
 which inherit from ``BaseEstimator``. This is done by attaching instances
 of the ``RequestMethod`` descriptor to classes, which is done in the
 ``_MetadataRequester`` class, and ``BaseEstimator`` inherits from this mixin.
-This mixin also implements the ``get_metadata_routing``, which meta-estimators
-need to override, but it works for simple consumers as is.
+This mixin also implements a ``_get_metadata_request`` method.


If I understand correctly, meta-estimators who inherit from BaseEstimator will also have a _get_metadata_request method ? But I'm confused, what is the purpose of this method for routers, will it return a MetadataRequest ? Is it the self request for routers that are also consumers ?

Yes, I think you are right. However, returning the self requests is not the primary purpose of having _get_metadata_request for pure routers.

I will try to explain to the best of my current understanding:

All estimator objects have their own _get_metadata_request method. I think it is easier to just have the method than to define some distinction between routers and consumers, because many can be both, pure routers are seldom and being a consumer depends on whether a set_{method}_request method is set on them or not.

When set_fit_request is called for instance, _get_metadata_request method is used to check whether they could potentially consume metadata by checking the signatures of their methods and adding class level settings (see _get_class_level_metadata_request_values therefore). And thewhile, the estimator builds a _metadata_request attribute that stores all that information. If I understand correctly, this is identical to the self requests.

When we call _get_metadata_request on a router, it returns that stored object. It might have been updated via the user code in the meantime.

So _get_metadata_request can serve two different purposes, and the first one is needed for any estimator, the second one is actually only interesing for consumers.

I also find that very confusing. I wonder if a solution could be to make the if-else distinction in _get_metadata_request in other places instead and reduce the functionality of _get_metadata_request to either only build the MetadataRequest object or to retrieve it. In that case, we could also rename it. What do you think, @antoinebaker and @adrinjalali? (I am thinking about a future PR of cause.)

sklearn/utils/_metadata_requests.py

antoinebaker · 2025-08-29T13:24:53Z

sklearn/utils/_metadata_requests.py

-    # for other reasons.
-    if hasattr(obj, "get_metadata_routing"):
+
+    # TODO(1.9): remove when get_metadata_routing is removed


get_metadata_routing removed from where ? I guess from _MetadataRequester, but I'm not sure.

Yes, I will add that. Thanks!

antoinebaker · 2025-08-29T13:57:17Z

sklearn/utils/_metadata_requests.py

+        hasattr(_obj, "get_metadata_routing")
+        or hasattr(_obj, "_get_metadata_request")
+        or isinstance(_obj, MetadataRouter)
+    ):
        raise AttributeError(
            f"The given object ({_obj.__class__.__name__!r}) needs to either"
            " implement the routing method `get_metadata_routing` or be a"


Should'nt we limit the scope of process_routing to routers (eg a meta-estimator) only ? It seems here that we allow simple consumers and MetadataRouter instances as well. According to the docstring its only use is inside routers. Are they cases where we need to call it on simple consumers or MetadataRouter instances ? If not, maybe we should raise an error (which could help debugging).

antoinebaker · 2025-08-29T14:44:18Z

With this PR and after the deprecation of _MetadataRequester.get_metadata_routing, will we able to tell if an object if a router/consumer by duck typing ?

hasattr(obj, "_get_metadata_request") # consumer
hasattr(obj, "get_metadata_routing") # router

Co-authored-by: antoinebaker <[email protected]>

…/scikit-learn into refactor_router_requester

StefanieSenger

Thanks for reviewing, @antoinebaker! I have modified a bit according to your review. Awaiting the next pass. :)

StefanieSenger · 2025-09-09T13:44:41Z

sklearn/utils/_metadata_requests.py

@@ -91,8 +94,7 @@
 which inherit from ``BaseEstimator``. This is done by attaching instances
 of the ``RequestMethod`` descriptor to classes, which is done in the
 ``_MetadataRequester`` class, and ``BaseEstimator`` inherits from this mixin.
-This mixin also implements the ``get_metadata_routing``, which meta-estimators
-need to override, but it works for simple consumers as is.
+This mixin also implements a ``_get_metadata_request`` method.


Yes, I think you are right. However, returning the self requests is not the primary purpose of having _get_metadata_request for pure routers.

I will try to explain to the best of my current understanding:

All estimator objects have their own _get_metadata_request method. I think it is easier to just have the method than to define some distinction between routers and consumers, because many can be both, pure routers are seldom and being a consumer depends on whether a set_{method}_request method is set on them or not.

When set_fit_request is called for instance, _get_metadata_request method is used to check whether they could potentially consume metadata by checking the signatures of their methods and adding class level settings (see _get_class_level_metadata_request_values therefore). And thewhile, the estimator builds a _metadata_request attribute that stores all that information. If I understand correctly, this is identical to the self requests.

When we call _get_metadata_request on a router, it returns that stored object. It might have been updated via the user code in the meantime.

So _get_metadata_request can serve two different purposes, and the first one is needed for any estimator, the second one is actually only interesing for consumers.

I also find that very confusing. I wonder if a solution could be to make the if-else distinction in _get_metadata_request in other places instead and reduce the functionality of _get_metadata_request to either only build the MetadataRequest object or to retrieve it. In that case, we could also rename it. What do you think, @antoinebaker and @adrinjalali? (I am thinking about a future PR of cause.)

sklearn/utils/_metadata_requests.py

StefanieSenger · 2025-09-11T09:49:05Z

sklearn/utils/_metadata_requests.py

-    # for other reasons.
-    if hasattr(obj, "get_metadata_routing"):
+
+    # TODO(1.9): remove when get_metadata_routing is removed


Yes, I will add that. Thanks!

StefanieSenger · 2025-09-11T10:55:48Z

sklearn/utils/_metadata_requests.py

+        hasattr(_obj, "get_metadata_routing")
+        or hasattr(_obj, "_get_metadata_request")
+        or isinstance(_obj, MetadataRouter)
+    ):
        raise AttributeError(
            f"The given object ({_obj.__class__.__name__!r}) needs to either"
            " implement the routing method `get_metadata_routing` or be a"


Oh my, when I added that condition, it had made sense to me and now I cannot explain it anymore ... 😅

I now think you are right and I have removed the new condition, @antoinebaker.

On the question whether we ever call process_routing on MetadataRouter instances: It seems we do that in some of the tests in the test_metaestimators_metadata_routing.py module. But we shouldn't modify code just to match a test. Instead, I think the tests would need to be different / less abstract.

StefanieSenger · 2025-09-11T11:29:57Z

@antoinebaker:

With this PR and after the deprecation of _MetadataRequester.get_metadata_routing, will we able to tell if an object if a router/consumer by duck typing ?
hasattr(obj, "_get_metadata_request") # consumer
hasattr(obj, "get_metadata_routing") # router

No, unfortunately, we won't be able to do that, since both objects will have the _get_metadata_request method and its used for creating a request object as well as to retrieve it. (See this comment.)

It might be that pure routers (that do not have self requests), don't need it and in this case, they could maybe not inherit from the _MetadataRequest mixin class?

base

ee05a5f

github-actions bot added module:metrics module:model_selection module:utils labels Jul 3, 2025

cleaning work

0d8b460

Merge branch 'main' into refactor_router_requester

0c4ccc4

StefanieSenger changed the title ~~Re-factor~~ MNT Refactor double-handling of MetadataRouter and MetadataRequest objects Jul 3, 2025

StefanieSenger added Metadata Routing all issues related to metadata routing, slep006, sample props No Changelog Needed and removed module:metrics module:model_selection labels Jul 3, 2025

StefanieSenger added 2 commits July 3, 2025 12:23

internal doc refinements

b93584d

add test for routing custom transformer

a33295f

StefanieSenger commented Jul 4, 2025

View reviewed changes

little fix

a9ef7f2

StefanieSenger commented Jul 4, 2025

View reviewed changes

nits [no build]

5b1810a

StefanieSenger changed the title ~~MNT Refactor double-handling of MetadataRouter and MetadataRequest objects~~ MNT Refactor get_metadata_routing method in MetadataRequest to directly use _get_metadata_request instead Jul 5, 2025

StefanieSenger commented Jul 5, 2025

View reviewed changes

update info on get_metadata_routing in plot_metadata_routing.py [doc …

27a8c02

…build]

StefanieSenger marked this pull request as ready for review July 5, 2025 17:45

wording

20c5dcd

StefanieSenger commented Jul 5, 2025

View reviewed changes

StefanieSenger mentioned this pull request Jul 7, 2025

MNT refactoring in routing _MetadataRequester #31534

Merged

StefanieSenger commented Jul 23, 2025

View reviewed changes

adrinjalali moved this to To Review in Metadata routing Aug 11, 2025

StefanieSenger and others added 8 commits August 15, 2025 15:30

Merge branch 'main' into refactor_router_requester

b6b1f5e

deprecate get_metadata_routing for consumers

5c09ac3

add changelog

39f53a1

re-do deprecation in a different way

7964524

exclude deprecated methods from test_docstring

eed13c7

fix warning

1815122

move comment

c95ef82

Merge branch 'main' into refactor_router_requester

eafdc8c

StefanieSenger removed the No Changelog Needed label Aug 17, 2025

StefanieSenger changed the title ~~MNT Refactor get_metadata_routing method in MetadataRequest to directly use _get_metadata_request instead~~ MNT Refactor and partially deprecate get_metadata_routing method in _MetadataRequester Aug 17, 2025

StefanieSenger changed the title ~~MNT Refactor and partially deprecate get_metadata_routing method in _MetadataRequester~~ MNT Refactor and deprecate get_metadata_routing method in _MetadataRequester Aug 17, 2025

adrinjalali reviewed Aug 20, 2025

View reviewed changes

antoinebaker reviewed Aug 29, 2025

View reviewed changes

antoinebaker mentioned this pull request Sep 4, 2025

FEAT (alt3) allow setting auto routed strategy on objects #31413

Open

StefanieSenger and others added 7 commits September 9, 2025 12:56

document test case better

e9b6c7c

Merge branch 'main' into refactor_router_requester

c016689

slightly improve documentation

06bce3a

Apply suggestions from code review

a800161

Co-authored-by: antoinebaker <[email protected]>

Merge branch 'refactor_router_requester' of github.com:StefanieSenger…

7860707

…/scikit-learn into refactor_router_requester

fix formatting and simplify comment

73c9611

remove condition

9138438

StefanieSenger commented Sep 11, 2025

View reviewed changes

Merge branch 'main' into refactor_router_requester

6e86b90

StefanieSenger mentioned this pull request Sep 12, 2025

FIX (SLEP6) descriptor shouldn't override method #32111

Open

StefanieSenger and others added 2 commits September 15, 2025 11:49

Merge branch 'main' into refactor_router_requester

308eeaa

add to TODO(1.9) comment

6f97885

		Consumer-only classes such as simple estimators return a serialized
		version of this class as the output of `get_metadata_routing()`.

		@@ -1529,20 +1532,6 @@ def _get_metadata_request(self):

		return requests

		def get_metadata_routing(self):

Uh oh!

MNT Refactor and deprecate get_metadata_routing method in _MetadataRequester #31695

Are you sure you want to change the base?

MNT Refactor and deprecate get_metadata_routing method in _MetadataRequester #31695

Conversation

StefanieSenger commented Jul 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What does this implement/fix? Explain your changes.

Uh oh!

github-actions bot commented Jul 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✔️ Linting Passed

Uh oh!

StefanieSenger Jul 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

StefanieSenger Jul 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

StefanieSenger commented Jul 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

StefanieSenger commented Jul 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

StefanieSenger commented Jul 5, 2025

Uh oh!

StefanieSenger Jul 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

StefanieSenger commented Aug 16, 2025

Uh oh!

adrinjalali left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

antoinebaker left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

antoinebaker commented Aug 29, 2025

Uh oh!

StefanieSenger left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

MNT Refactor and deprecate `get_metadata_routing` method in `_MetadataRequester` #31695

MNT Refactor and deprecate `get_metadata_routing` method in `_MetadataRequester` #31695

StefanieSenger commented Jul 3, 2025 •

edited

Loading

github-actions bot commented Jul 3, 2025 •

edited

Loading

StefanieSenger Jul 4, 2025 •

edited

Loading

StefanieSenger Jul 4, 2025 •

edited

Loading

StefanieSenger commented Jul 5, 2025 •

edited

Loading

StefanieSenger commented Jul 5, 2025 •

edited

Loading

StefanieSenger Jul 5, 2025 •

edited

Loading