"""
Metadata Routing Utility

In order to better understand the components implemented in this file, one
needs to understand their relationship to one another.

The only relevant public API for end users are the ``set_{method}_request`` methods,
e.g. ``estimator.set_fit_request(sample_weight=True)``. However, third-party
developers and users who implement custom meta-estimators, need to deal with
the objects implemented in this file.

The routing is coordinated by building ``MetadataRequest`` objects
for objects that consume metadata, and ``MetadataRouter`` objects for objects that
can route metadata, which are then aligned during a call to `process_routing()`. This
function returns a Bunch object (dictionary-like) with all the information on the
consumers and which metadata they had requested and the actual metadata values. A
routing method (such as `fit` in a meta-estimator) can now provide the metadata to the
relevant consuming method (such as `fit` in a sub-estimator).

The ``MetadataRequest`` and ``MetadataRouter`` objects are constructed via a
``get_metadata_routing`` method, which all scikit-learn estimators provide.
This method is automatically implemented via ``BaseEstimator`` for all simple
estimators, but needs a custom implementation for meta-estimators.

MetadataRequest
~~~~~~~~~~~~~~~

In non-routing consumers, the simplest case, e.g. ``SVM``, ``get_metadata_routing``
returns a ``MetadataRequest`` object  which is assigned to the consumer's
`_metadata_request` attribute. It stores which metadata is required by each method of
the consumer by including one ``MethodMetadataRequest`` per method in ``METHODS``
(e. g. ``fit``, ``score``, etc).

Users and developers almost never need to directly add a new ``MethodMetadataRequest``,
to the consumer's `_metadata_request` attribute, since these are generated
automatically. This attribute is modified while running `set_{method}_request` methods
(such as `set_fit_request()`), which adds the request via
`method_metadata_request.add_request(param=prop, alias=alias)`.

The ``alias`` in the ``add_request`` method has to be either a string (an alias),
or one of ``[True (requested), False (unrequested), None (error if passed)]``. There
are some other special values such as ``UNUSED`` and ``WARN`` which are used
for purposes such as warning of removing a metadata in a child class, but not
used by the end users.

MetadataRouter
~~~~~~~~~~~~~~

In routers (such as meta-estimators or multi metric scorers), ``get_metadata_routing``
returns a ``MetadataRouter`` object. It provides information about which method, from
the router object, calls which method in a consumer's object, and also, which metadata
had been requested by the consumer's methods, thus specifying how metadata is to be
passed. If a sub-estimator is a router as well, their routing information is also stored
in the meta-estimators router.

Conceptually, this information looks like:

```
{
    "sub_estimator1": (
        mapping=[(caller="fit", callee="transform"), ...],
        router=MetadataRequest(...),  # or another MetadataRouter
    ),
    ...
}
```

The `MetadataRouter` objects are never stored and are always recreated anew whenever
the object's `get_metadata_routing` method is called.

An object that is both a router and a consumer, e.g. a meta-estimator which
consumes ``sample_weight`` and routes ``sample_weight`` to its sub-estimators
also returns a ``MetadataRouter`` object. Its routing information includes both
information about what metadata is required by the object itself (added via
``MetadataRouter.add_self_request``), as well as the routing information for its
sub-estimators (added via ``MetadataRouter.add``).

Implementation Details
~~~~~~~~~~~~~~~~~~~~~~

To give the above representation some structure, we use the following objects:

- ``(caller=..., callee=...)`` is a namedtuple called ``MethodPair``.

- The list of ``MethodPair`` stored in the ``mapping`` field of a `RouterMappingPair` is
  a ``MethodMapping`` object.

- ``(mapping=..., router=...)`` is a namedtuple called ``RouterMappingPair``.

The ``set_{method}_request`` methods are dynamically generated for estimators
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.
"""

# Authors: The scikit-learn developers
# SPDX-License-Identifier: BSD-3-Clause

import inspect
from collections import defaultdict, namedtuple
from copy import deepcopy
from typing import TYPE_CHECKING, Callable, Iterable, Optional, Union
from warnings import warn

from sklearn import get_config
from sklearn.exceptions import UnsetMetadataPassedError
from sklearn.utils._bunch import Bunch

# Only the following methods are supported in the routing mechanism. Adding new
# methods at the moment involves monkeypatching this list.
# Note that if this list is changed or monkeypatched, the corresponding method
# needs to be added under a TYPE_CHECKING condition like the one done here in
# _MetadataRequester
SIMPLE_METHODS = [
    "fit",
    "partial_fit",
    "predict",
    "predict_proba",
    "predict_log_proba",
    "decision_function",
    "score",
    "split",
    "transform",
    "inverse_transform",
]

# These methods are a composite of other methods and one cannot set their
# requests directly. Instead they should be set by setting the requests of the
# simple methods which make the composite ones.
COMPOSITE_METHODS = {
    "fit_transform": ["fit", "transform"],
    "fit_predict": ["fit", "predict"],
}

METHODS = SIMPLE_METHODS + list(COMPOSITE_METHODS.keys())


def _routing_repr(obj):
    """Get a representation suitable for messages printed in the routing machinery.

    This is different than `repr(obj)`, since repr(estimator) can be verbose when
    there are many constructor arguments set by the user.

    This is most suitable for Scorers as it gives a nice representation of what they
    are. This is done by implementing a `_routing_repr` method on the object.

    Since the `owner` object could be the type name (str), we return that string if the
    given `obj` is a string, otherwise we return the object's type name.

    .. versionadded:: 1.8
    """
    try:
        return obj._routing_repr()
    except AttributeError:
        return obj if isinstance(obj, str) else type(obj).__name__


def _routing_enabled():
    """Return whether metadata routing is enabled.

    .. versionadded:: 1.3

    Returns
    -------
    enabled : bool
        Whether metadata routing is enabled. If the config is not set, it
        defaults to False.
    """
    return get_config().get("enable_metadata_routing", False)


def _raise_for_params(params, owner, method, allow=None):
    """Raise an error if metadata routing is not enabled and params are passed.

    .. versionadded:: 1.4

    Parameters
    ----------
    params : dict
        The metadata passed to a method.

    owner : object
        The object to which the method belongs.

    method : str
        The name of the method, e.g. "fit".

    allow : list of str, default=None
        A list of parameters which are allowed to be passed even if metadata
        routing is not enabled.

    Raises
    ------
    ValueError
        If metadata routing is not enabled and params are passed.
    """
    caller = f"{_routing_repr(owner)}.{method}" if method else _routing_repr(owner)

    allow = allow if allow is not None else {}

    if not _routing_enabled() and (params.keys() - allow):
        raise ValueError(
            f"Passing extra keyword arguments to {caller} is only supported if"
            " enable_metadata_routing=True, which you can set using"
            " `sklearn.set_config`. See the User Guide"
            " <https://scikit-learn.org/stable/metadata_routing.html> for more"
            f" details. Extra parameters passed are: {set(params)}"
        )


def _raise_for_unsupported_routing(obj, method, **kwargs):
    """Raise when metadata routing is enabled and metadata is passed.

    This is used in meta-estimators which have not implemented metadata routing
    to prevent silent bugs. There is no need to use this function if the
    meta-estimator is not accepting any metadata, especially in `fit`, since
    if a meta-estimator accepts any metadata, they would do that in `fit` as
    well.

    Parameters
    ----------
    obj : estimator
        The estimator for which we're raising the error.

    method : str
        The method where the error is raised.

    **kwargs : dict
        The metadata passed to the method.
    """
    kwargs = {key: value for key, value in kwargs.items() if value is not None}
    if _routing_enabled() and kwargs:
        cls_name = _routing_repr(obj)
        raise NotImplementedError(
            f"{cls_name}.{method} cannot accept given metadata ({set(kwargs.keys())})"
            f" since metadata routing is not yet implemented for {cls_name}."
        )


class _RoutingNotSupportedMixin:
    """A mixin to be used to remove the default `get_metadata_routing`.

    This is used in meta-estimators where metadata routing is not yet
    implemented.

    This also makes it clear in our rendered documentation that this method
    cannot be used.
    """

    def get_metadata_routing(self):
        """Raise `NotImplementedError`.

        This estimator does not support metadata routing yet."""
        raise NotImplementedError(
            f"{_routing_repr(self)} has not implemented metadata routing yet."
        )


# Request values
# ==============
# Each request value needs to be one of the following values, or an alias.

# this is used in `__metadata_request__*` attributes to indicate that a
# metadata is not present even though it may be present in the
# corresponding method's signature.
UNUSED = "$UNUSED$"

# this is used whenever a default value is changed, and therefore the user
# should explicitly set the value, otherwise a warning is shown. An example
# is when a meta-estimator is only a router, but then becomes also a
# consumer in a new release.
WARN = "$WARN$"

# this is the default used in `set_{method}_request` methods to indicate no
# change requested by the user.
UNCHANGED = "$UNCHANGED$"

VALID_REQUEST_VALUES = [False, True, None, UNUSED, WARN]


def request_is_alias(item):
    """Check if an item is a valid string alias for a metadata.

    Values in ``VALID_REQUEST_VALUES`` are not considered aliases in this
    context. Only a string which is a valid identifier is.

    Parameters
    ----------
    item : object
        The given item to be checked if it can be an alias for the metadata.

    Returns
    -------
    result : bool
        Whether the given item is a valid alias.
    """
    if item in VALID_REQUEST_VALUES:
        return False

    # item is only an alias if it's a valid identifier
    return isinstance(item, str) and item.isidentifier()


def request_is_valid(item):
    """Check if an item is a valid request value (and not an alias).

    Parameters
    ----------
    item : object
        The given item to be checked.

    Returns
    -------
    result : bool
        Whether the given item is valid.
    """
    return item in VALID_REQUEST_VALUES


# Metadata Request for Simple Consumers
# =====================================
# This section includes MethodMetadataRequest and MetadataRequest which are
# used in simple consumers.


class MethodMetadataRequest:
    """Container for metadata requests associated with a single method.

    Instances of this class get used within a :class:`MetadataRequest` - one per each
    public method (`fit`, `transform`, ...) that its owning consumer has.

    .. versionadded:: 1.3

    Parameters
    ----------
    owner : object
        The object owning these requests.

    method : str
        The name of the method to which these requests belong.

    requests : dict of {str: bool, None or str}, default=None
        The initial requests for this method.
    """

    def __init__(self, owner, method, requests=None):
        self._requests = requests or dict()
        self.owner = owner
        self.method = method

    def __sklearn_clone__(self):
        # `owner` is a reference to the estimator and is only used by
        # `_routing_repr` for display; deep-copying it would drag the full
        # estimator state (and fail for non-picklable attributes) for no benefit.
        return MethodMetadataRequest(
            owner=self.owner,
            method=self.method,
            requests=deepcopy(self._requests),
        )

    @property
    def requests(self):
        """Dictionary of the form: ``{key: alias}``."""
        return self._requests

    def add_request(
        self,
        *,
        param,
        alias,
    ):
        """Add request info for a metadata.

        Parameters
        ----------
        param : str
            The metadata for which a request is set.

        alias : str, or {True, False, None}
            Specifies which metadata should be routed to the method that owns this
            `MethodMetadataRequest`.

            - str: the name (or alias) of metadata given to a meta-estimator that
              should be routed to the method that owns this `MethodMetadataRequest`.

            - True: requested

            - False: not requested

            - None: error if passed
        """
        if not request_is_alias(alias) and not request_is_valid(alias):
            raise ValueError(
                f"The alias you're setting for `{param}` should be either a "
                "valid identifier or one of {None, True, False}, but given "
                f"value is: `{alias}`"
            )

        if alias == param:
            alias = True

        if alias == UNUSED:
            if param in self._requests:
                del self._requests[param]
            else:
                raise ValueError(
                    f"Trying to remove parameter {param} with UNUSED which doesn't"
                    " exist."
                )
        else:
            self._requests[param] = alias

        return self

    def _get_param_names(self, return_alias):
        """Get names of all metadata that can be consumed or routed by this method.

        This method returns the names of all metadata, even the ``False``
        ones.

        Parameters
        ----------
        return_alias : bool
            Controls whether original or aliased names should be returned. If
            ``False``, aliases are ignored and original names are returned.

        Returns
        -------
        names : set of str
            A set of strings with the names of all metadata.
        """
        return set(
            alias if return_alias and not request_is_valid(alias) else prop
            for prop, alias in self._requests.items()
            if not request_is_valid(alias) or alias is not False
        )

    def _check_warnings(self, *, params):
        """Check whether metadata is passed which is marked as WARN.

        If any metadata is passed which is marked as WARN, a warning is raised.

        Parameters
        ----------
        params : dict
            The metadata passed to a method.
        """
        params = {} if params is None else params
        warn_params = {
            prop
            for prop, alias in self._requests.items()
            if alias == WARN and prop in params
        }
        for param in warn_params:
            warn(
                f"Support for {param} has recently been added to {self.owner} class. "
                "To maintain backward compatibility, it is ignored now. "
                f"Using `set_{self.method}_request({param}={{True, False}})` "
                "on this method of the class, you can set the request value "
                "to False to silence this warning, or to True to consume and "
                "use the metadata."
            )

    def _route_params(self, params, parent, caller):
        """Prepare the given metadata to be passed to the method.

        The output of this method can be used directly as the input to the
        corresponding method as **kwargs.

        Parameters
        ----------
        params : dict
            A dictionary of provided metadata.

        parent : object
            Parent class object, that routes the metadata.

        caller : str
            Method from the parent class object, where the metadata is routed from.

        Returns
        -------
        params : Bunch
            A :class:`~sklearn.utils.Bunch` of {metadata: value} which can be
            passed to the corresponding method.
        """
        self._check_warnings(params=params)
        unrequested = dict()
        args = {arg: value for arg, value in params.items() if value is not None}
        res = Bunch()
        for prop, alias in self._requests.items():
            if alias is False or alias == WARN:
                continue
            elif alias is True and prop in args:
                res[prop] = args[prop]
            elif alias is None and prop in args:
                unrequested[prop] = args[prop]
            elif alias in args:
                res[prop] = args[alias]
        if unrequested:
            if self.method in COMPOSITE_METHODS:
                callee_methods = COMPOSITE_METHODS[self.method]
            else:
                callee_methods = [self.method]
            set_requests_on = "".join(
                [
                    f".set_{method}_request({{metadata}}=True/False)"
                    for method in callee_methods
                ]
            )
            message = (
                f"[{', '.join([key for key in unrequested])}] are passed but are not"
                " explicitly set as requested or not requested for"
                f" {_routing_repr(self.owner)}.{self.method}, which is used within"
                f" {_routing_repr(parent)}.{caller}. Call `{_routing_repr(self.owner)}"
                + set_requests_on
                + "` for each metadata you want to request/ignore. See the"
                " Metadata Routing User guide"
                " <https://scikit-learn.org/stable/metadata_routing.html> for more"
                " information."
            )
            raise UnsetMetadataPassedError(
                message=message,
                unrequested_params=unrequested,
                routed_params=res,
            )
        return res

    def _consumes(self, params):
        """Return subset of `params` consumed by the method that owns this instance.

        Parameters
        ----------
        params : iterable of str
            An iterable of parameter names to test for consumption.

        Returns
        -------
        consumed_params : set of str
            A subset of parameters from `params` which are consumed by this method.
        """
        params = set(params)
        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:
                consumed_params.add(alias)
        return consumed_params

    def _serialize(self):
        """Serialize the object.

        Returns
        -------
        obj : dict
            A serialized version of the instance in the form of a dictionary.
        """
        return self._requests

    def __repr__(self):
        return str(self._serialize())

    def __str__(self):
        return str(repr(self))


class MetadataRequest:
    """Container for storing metadata request info and an associated consumer (`owner`).

    Instances of `MethodMetadataRequest` are used in this class for each
    available method under `MetadataRequest(owner=obj).{method}`.

    Every :term:`consumer` in scikit-learn has a `_metadata_request` attribute that is a
    `MetadataRequest`.

    Read more on developing custom estimators that can route metadata in the
    :ref:`Metadata Routing Developing Guide
    <sphx_glr_auto_examples_miscellaneous_plot_metadata_routing.py>`.

    .. versionadded:: 1.3

    Parameters
    ----------
    owner : object
        The object to which these requests belong.

    Examples
    --------
    >>> from sklearn import set_config
    >>> set_config(enable_metadata_routing=True)
    >>> from pprint import pprint
    >>> from sklearn.utils.metadata_routing import MetadataRequest
    >>> r = MetadataRequest(owner="any_object")
    >>> r.fit.add_request(param="sample_weight", alias=True)
    {'sample_weight': True}
    >>> r.score.add_request(param="sample_weight", alias=False)
    {'sample_weight': False}
    >>> pprint(r)
    {'fit': {'sample_weight': True}, 'score': {'sample_weight': False}}
    >>> set_config(enable_metadata_routing=False)
    """

    # this is here for us to use this attribute's value instead of doing
    # `isinstance` in our checks, so that we avoid issues when people vendor
    # this file instead of using it directly from scikit-learn.
    _type = "metadata_request"

    def __init__(self, owner):
        self.owner = owner
        for method in SIMPLE_METHODS:
            setattr(
                self,
                method,
                MethodMetadataRequest(owner=owner, method=method),
            )

    def __sklearn_clone__(self):
        # `owner` is a reference to the estimator and is only used by
        # `_routing_repr` for display; see MethodMetadataRequest.__sklearn_clone__.
        new = MetadataRequest(owner=self.owner)
        for method in SIMPLE_METHODS:
            setattr(new, method, getattr(self, method).__sklearn_clone__())
        return new

    def consumes(self, method, params):
        """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 for which to determine consumed parameters.

        params : iterable of str
            An iterable of parameter names to test for consumption.

        Returns
        -------
        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)

    def __getattr__(self, name):
        # Called when the default attribute access fails with an AttributeError
        # (either __getattribute__() raises an AttributeError because name is
        # not an instance attribute or an attribute in the class tree for self;
        # or __get__() of a name property raises AttributeError). This method
        # should either return the (computed) attribute value or raise an
        # AttributeError exception.
        # https://docs.python.org/3/reference/datamodel.html#object.__getattr__
        if name not in COMPOSITE_METHODS:
            raise AttributeError(
                f"'{self.__class__.__name__}' object has no attribute '{name}'"
            )

        requests = {}
        for method in COMPOSITE_METHODS[name]:
            mmr = getattr(self, method)
            existing = set(requests.keys())
            upcoming = set(mmr.requests.keys())
            common = existing & upcoming
            conflicts = [key for key in common if requests[key] != mmr._requests[key]]
            if conflicts:
                raise ValueError(
                    f"Conflicting metadata requests for {', '.join(conflicts)} while"
                    f" composing the requests for {name}. Metadata with the same name"
                    f" for methods {', '.join(COMPOSITE_METHODS[name])} should have the"
                    " same request value."
                )
            requests.update(mmr._requests)
        return MethodMetadataRequest(owner=self.owner, method=name, requests=requests)

    def _get_param_names(self, method, return_alias, ignore_self_request=None):
        """Get names of all metadata that can be consumed or routed by specified \
            method.

        This method returns the names of all metadata, even the ``False``
        ones.

        Parameters
        ----------
        method : str
            The name of the method for which metadata names are requested.

        return_alias : bool
            Controls whether original or aliased names should be returned. If
            ``False``, aliases are ignored and original names are returned.

        ignore_self_request : bool
            Ignored. Present for API compatibility.

        Returns
        -------
        names : set of str
            A set of strings with the names of all metadata.
        """
        return getattr(self, method)._get_param_names(return_alias=return_alias)

    def _route_params(self, *, params, method, parent, caller):
        """Prepare the given parameters to be passed to the method.

        The output of this method can be used directly as the input to the
        corresponding method as extra keyword arguments to pass metadata.

        Parameters
        ----------
        params : dict
            A dictionary of provided metadata.

        method : str
            The name of the method for which the parameters are requested and
            routed.

        parent : object
            Parent class object, that routes the metadata.

        caller : str
            Method from the parent class object, where the metadata is routed from.

        Returns
        -------
        params : Bunch
            A :class:`~sklearn.utils.Bunch` of {metadata: value} which can be given to
            the corresponding method.
        """
        return getattr(self, method)._route_params(
            params=params, parent=parent, caller=caller
        )

    def _check_warnings(self, *, method, params):
        """Check whether metadata is passed which is marked as WARN.

        If any metadata is passed which is marked as WARN, a warning is raised.

        Parameters
        ----------
        method : str
            The name of the method for which the warnings should be checked.

        params : dict
            The metadata passed to a method.
        """
        getattr(self, method)._check_warnings(params=params)

    def _serialize(self):
        """Serialize the object.

        Returns
        -------
        obj : dict
            A serialized version of the instance in the form of a dictionary.
        """
        output = dict()
        for method in SIMPLE_METHODS:
            mmr = getattr(self, method)
            if len(mmr.requests):
                output[method] = mmr._serialize()
        return output

    def __repr__(self):
        return str(self._serialize())

    def __str__(self):
        return str(repr(self))


# Metadata Request for Routers
# ============================
# This section includes all objects required for MetadataRouter which is used
# in routers, returned by their ``get_metadata_routing``.

# `RouterMappingPair` is used to store a (mapping, router) tuple where `mapping` is a
# `MethodMapping` object and `router` is the output of `get_metadata_routing`.
# `MetadataRouter` stores a collection of `RouterMappingPair` objects in its
# `_route_mappings` attribute.
RouterMappingPair = namedtuple("RouterMappingPair", ["mapping", "router"])

# `MethodPair` is used to store a single method routing. `MethodMapping` stores a list
# of `MethodPair` objects in its `_routes` attribute.
MethodPair = namedtuple("MethodPair", ["caller", "callee"])


class MethodMapping:
    """Stores the mapping between `caller` and `callee` methods for a :term:`router`.

    This class is primarily used in a ``get_metadata_routing()`` of a router
    object when defining the mapping between the router's methods and a sub-object (a
    sub-estimator or a scorer).

    Iterating through an instance of this class yields
    ``MethodPair(caller, callee)`` instances.

    Read more on developing custom estimators that can route metadata in the
    :ref:`Metadata Routing Developing Guide
    <sphx_glr_auto_examples_miscellaneous_plot_metadata_routing.py>`.

    .. versionadded:: 1.3

    Examples
    --------
    >>> from sklearn.utils.metadata_routing import MethodMapping
    >>> MethodMapping().add(caller="fit", callee="split")
    [{'caller': 'fit', 'callee': 'split'}]
    """

    def __init__(self):
        self._routes = []

    def __iter__(self):
        return iter(self._routes)

    def add(self, *, caller, callee):
        """Add a method mapping.

        Parameters
        ----------

        caller : str
            Parent estimator's method name in which the ``callee`` is called.

        callee : str
            Child object's method name. This method is called in ``caller``.

        Returns
        -------
        self : MethodMapping
            Returns self.
        """
        if caller not in METHODS:
            raise ValueError(
                f"Given caller:{caller} is not a valid method. Valid methods are:"
                f" {METHODS}"
            )
        if callee not in METHODS:
            raise ValueError(
                f"Given callee:{callee} is not a valid method. Valid methods are:"
                f" {METHODS}"
            )
        self._routes.append(MethodPair(caller=caller, callee=callee))
        return self

    def _serialize(self):
        """Serialize the object.

        Returns
        -------
        obj : list
            A serialized version of the instance in the form of a list.
        """
        result = list()
        for route in self._routes:
            result.append({"caller": route.caller, "callee": route.callee})
        return result

    def __repr__(self):
        return str(self._serialize())

    def __str__(self):
        return str(repr(self))


class MetadataRouter:
    """Coordinates metadata routing for a :term:`router` object.

    This class is used by :term:`meta-estimators` or functions that can route metadata,
    to handle their metadata routing. Routing information is stored in a
    dictionary-like structure of the form ``{"object_name":
    RouterMappingPair(mapping, router)}``, where ``mapping``
    is an instance of :class:`~sklearn.utils.metadata_routing.MethodMapping` and
    ``router`` is either a
    :class:`~sklearn.utils.metadata_routing.MetadataRequest` or another
    :class:`~sklearn.utils.metadata_routing.MetadataRouter` instance.

    Read more on developing custom estimators that can route metadata in the
    :ref:`Metadata Routing Developing Guide
    <sphx_glr_auto_examples_miscellaneous_plot_metadata_routing.py>`.

    .. versionadded:: 1.3

    Parameters
    ----------
    owner : object
        The object to which these requests belong.

    Examples
    --------
    >>> from pprint import pprint
    >>> from sklearn import set_config
    >>> from sklearn.feature_selection import SelectFromModel
    >>> from sklearn.linear_model import LinearRegression
    >>> from sklearn.utils.metadata_routing import MetadataRouter, MethodMapping
    >>> set_config(enable_metadata_routing=True)
    >>> meta_estimator = SelectFromModel(
    ...     estimator=LinearRegression().set_fit_request(sample_weight=True)
    ... )
    >>> router = MetadataRouter(owner=meta_estimator).add(
    ...     estimator=meta_estimator.estimator,
    ...     method_mapping=MethodMapping()
    ...     .add(caller="partial_fit", callee="partial_fit")
    ...     .add(caller="fit", callee="fit"),
    ... )
    >>> pprint(router)
    {'estimator': {'mapping': [{'caller': 'partial_fit', 'callee': 'partial_fit'},
                           {'caller': 'fit', 'callee': 'fit'}],
               'router': {'fit': {'sample_weight': True},
                          'score': {'sample_weight': None}}}}
    >>> set_config(enable_metadata_routing=False)
    """

    # this is here for us to use this attribute's value instead of doing
    # `isinstance`` in our checks, so that we avoid issues when people vendor
    # this file instead of using it directly from scikit-learn.
    _type = "metadata_router"

    def __init__(self, owner):
        self._route_mappings = dict()
        # `_self_request` is used if the router is also a consumer.
        # _self_request, (added using `add_self_request()`) is treated
        # differently from the other consumer objects which are stored in
        # _route_mappings.
        self._self_request = None
        self.owner = owner

    def __sklearn_clone__(self):
        # `owner` is a reference to the estimator and is only used by
        # `_routing_repr` for display; see MethodMetadataRequest.__sklearn_clone__.
        new = MetadataRouter(owner=self.owner)
        new._self_request = (
            self._self_request.__sklearn_clone__()
            if self._self_request is not None
            else None
        )
        new._route_mappings = {
            name: RouterMappingPair(
                mapping=deepcopy(pair.mapping),
                router=pair.router.__sklearn_clone__(),
            )
            for name, pair in self._route_mappings.items()
        }
        return new

    def add_self_request(self, obj):
        """Add `self` (as a :term:`consumer`) to the `MetadataRouter`.

        This method is used if the :term:`router` is also a :term:`consumer`, and hence
        the router itself needs to be included in the routing. The passed object
        can be an estimator or a
        :class:`~sklearn.utils.metadata_routing.MetadataRequest`.

        A router should add itself using this method instead of `add` since it
        should be treated differently than the other consumer objects to which metadata
        is routed by the router.

        Parameters
        ----------
        obj : object
            This is typically the router instance, i.e. `self` in a
            ``get_metadata_routing()`` implementation. It can also be a
            ``MetadataRequest`` instance.

        Returns
        -------
        self : MetadataRouter
            Returns `self`.
        """
        if getattr(obj, "_type", None) == "metadata_request":
            self._self_request = obj.__sklearn_clone__()
        elif hasattr(obj, "_get_metadata_request"):
            self._self_request = obj._get_metadata_request().__sklearn_clone__()
        else:
            raise ValueError(
                "Given `obj` is neither a `MetadataRequest` nor does it implement the"
                " required API. Inheriting from `BaseEstimator` implements the required"
                " API."
            )
        return self

    def add(self, *, method_mapping, **objs):
        """Add :term:`consumers <consumer>` to the `MetadataRouter`.

        The estimators that consume metadata are passed as named objects along with a
        method mapping, that defines how their methods relate to those of the
        :term:`router`.

        Parameters
        ----------
        method_mapping : MethodMapping
            The mapping between the child (:term:`consumer`) and the parent's
            (:term:`router`'s) methods.

        **objs : dict
            A dictionary of objects, whose requests are extracted by calling
            :func:`~sklearn.utils.metadata_routing.get_routing_for_object` on them.

        Returns
        -------
        self : MetadataRouter
            Returns `self`.
        """
        method_mapping = deepcopy(method_mapping)

        for name, obj in objs.items():
            self._route_mappings[name] = RouterMappingPair(
                mapping=method_mapping, router=get_routing_for_object(obj)
            )
        return self

    def consumes(self, method, params):
        """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 for which to determine consumed parameters.

        params : iterable of str
            An iterable of parameter names to test for consumption.

        Returns
        -------
        consumed_params : set of str
            A subset of parameters from `params` which are consumed by this method.
        """
        consumed_params = set()
        if self._self_request:
            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:
                    consumed_params.update(
                        route_mapping.router.consumes(method=callee, params=params)
                    )

        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 \
            method.

        This method returns the names of all metadata, even the ``False``
        ones.

        Parameters
        ----------
        method : str
            The name of the method for which metadata names are requested.

        return_alias : bool
            Controls whether original or aliased names should be returned,
            which only applies to the stored `self`. If no `self` routing
            object is stored, this parameter has no effect.

        ignore_self_request : bool
            If `self._self_request` should be ignored. This is used in `_route_params`.
            If ``True``, ``return_alias`` has no effect.

        Returns
        -------
        names : set of str
            A set of strings with the names of all metadata.
        """
        res = set()
        if self._self_request and not ignore_self_request:
            res = res.union(
                self._self_request._get_param_names(
                    method=method, return_alias=return_alias
                )
            )

        for name, route_mapping in self._route_mappings.items():
            for caller, callee in route_mapping.mapping:
                if caller == method:
                    res = res.union(
                        route_mapping.router._get_param_names(
                            method=callee, return_alias=True, ignore_self_request=False
                        )
                    )
        return res

    def _route_params(self, *, params, method, parent, caller):
        """Prepare the given metadata to be passed to the method.

        This is used when a router is used as a child object of another router.
        The parent router then passes all parameters understood by the child
        object to it and delegates their validation to the child.

        The output of this method can be used directly as the input to the
        corresponding method as **kwargs.

        Parameters
        ----------
        params : dict
            A dictionary of provided metadata.

        method : str
            The name of the method for which the metadata is requested and routed.

        parent : object
            Parent class object, that routes the metadata.

        caller : str
            Method from the parent class object, where the metadata is routed from.

        Returns
        -------
        params : Bunch
            A :class:`~sklearn.utils.Bunch` of {metadata: value} which can be given to
            the corresponding method.
        """
        res = Bunch()
        if self._self_request:
            res.update(
                self._self_request._route_params(
                    params=params,
                    method=method,
                    parent=parent,
                    caller=caller,
                )
            )

        param_names = self._get_param_names(
            method=method, return_alias=True, ignore_self_request=True
        )
        child_params = {
            key: value for key, value in params.items() if key in param_names
        }
        for key in set(res.keys()).intersection(child_params.keys()):
            # conflicts are okay if the passed objects are the same, but it's
            # an issue if they're different objects.
            if child_params[key] is not res[key]:
                raise ValueError(
                    f"In {_routing_repr(self.owner)}, there is a conflict on {key}"
                    " between what is requested for this estimator and what is"
                    " requested by its children. You can resolve this conflict by"
                    " using an alias for the child estimators' requested metadata."
                )

        res.update(child_params)
        return res

    def route_params(self, *, caller, params):
        """Get the values of metadata requested by :term:`consumers <consumer>`.

        Returns a :class:`~sklearn.utils.Bunch` containing the metadata that this
        :term:`router`'s `caller` method needs to route, organized by each
        :term:`consumer` and their corresponding methods.

        This can be used to pass the required metadata to corresponding methods in
        consumers.

        Parameters
        ----------
        caller : str
            The name of the :term:`router`'s method through which the metadata is
            routed. For example, if called inside the :term:`fit` method of a router,
            this would be `"fit"`.

        params : dict
            A dictionary of provided metadata.

        Returns
        -------
        params : Bunch
            A :class:`~sklearn.utils.Bunch` of the form
            ``{"object_name": {"method_name": {metadata: value}}}``.
        """
        if self._self_request:
            self._self_request._check_warnings(params=params, method=caller)

        res = Bunch()
        for name, route_mapping in self._route_mappings.items():
            router, mapping = route_mapping.router, route_mapping.mapping

            res[name] = Bunch()
            for _caller, _callee in mapping:
                if _caller == caller:
                    res[name][_callee] = router._route_params(
                        params=params,
                        method=_callee,
                        parent=self.owner,
                        caller=caller,
                    )
        return res

    def validate_metadata(self, *, method, params):
        """Validate given metadata for a method.

        This raises a ``TypeError`` if some of the passed metadata are not
        understood by child objects.

        Parameters
        ----------
        method : str
            The name of the :term:`router`'s method through which the metadata is
            routed. For example, if called inside the :term:`fit` method of a router,
            this would be `"fit"`.

        params : dict
            A dictionary of provided metadata.
        """
        param_names = self._get_param_names(
            method=method, return_alias=False, ignore_self_request=False
        )
        if self._self_request:
            self_params = self._self_request._get_param_names(
                method=method, return_alias=False
            )
        else:
            self_params = set()
        extra_keys = set(params.keys()) - param_names - self_params
        if extra_keys:
            raise TypeError(
                f"{_routing_repr(self.owner)}.{method} got unexpected argument(s)"
                f" {extra_keys}, which are not routed to any object."
            )

    def _serialize(self):
        """Serialize the object.

        Returns
        -------
        obj : dict
            A serialized version of the instance in the form of a dictionary.
        """
        res = dict()
        if self._self_request:
            res["$self_request"] = self._self_request._serialize()
        for name, route_mapping in self._route_mappings.items():
            res[name] = dict()
            res[name]["mapping"] = route_mapping.mapping._serialize()
            res[name]["router"] = route_mapping.router._serialize()

        return res

    def __iter__(self):
        if self._self_request:
            method_mapping = MethodMapping()
            for method in METHODS:
                method_mapping.add(caller=method, callee=method)
            yield (
                "$self_request",
                RouterMappingPair(mapping=method_mapping, router=self._self_request),
            )
        for name, route_mapping in self._route_mappings.items():
            yield (name, route_mapping)

    def __repr__(self):
        return str(self._serialize())

    def __str__(self):
        return str(repr(self))


def get_routing_for_object(obj=None):
    """Get a ``Metadata{Router, Request}`` instance from the given object.

    This function returns a
    :class:`~sklearn.utils.metadata_routing.MetadataRouter` or a
    :class:`~sklearn.utils.metadata_routing.MetadataRequest` from the given input.

    This function always returns a copy or a new instance constructed from the
    input, such that changing the output of this function will not change the
    original object.

    .. versionadded:: 1.3

    Parameters
    ----------
    obj : object
        - If the object provides a `get_metadata_routing` method, return a copy
            of the output of that method.
        - If the object is already a
            :class:`~sklearn.utils.metadata_routing.MetadataRequest` or a
            :class:`~sklearn.utils.metadata_routing.MetadataRouter`, return a copy
            of that.
        - Returns an empty :class:`~sklearn.utils.metadata_routing.MetadataRequest`
            otherwise.

    Returns
    -------
    obj : MetadataRequest or MetadataRouter
        A ``MetadataRequest`` or a ``MetadataRouter`` taken or created from
        the given object.

    Examples
    --------
    >>> from sklearn.datasets import make_classification
    >>> from sklearn.pipeline import Pipeline
    >>> from sklearn.preprocessing import StandardScaler
    >>> from sklearn.linear_model import LogisticRegressionCV
    >>> from sklearn.utils.metadata_routing import get_routing_for_object
    >>> X, y = make_classification()
    >>> pipe = Pipeline(
    ...       [("scaler", StandardScaler()), ("lr_cv", LogisticRegressionCV())]
    ... )
    >>> pipe.fit(X, y) # doctest: +SKIP
    Pipeline(steps=[('scaler', StandardScaler()), ('lr_cv', LogisticRegressionCV())])
    >>> type(get_routing_for_object(pipe))
    <class 'sklearn.utils._metadata_requests.MetadataRouter'>
    >>> type(get_routing_for_object(pipe.named_steps.scaler))
    <class 'sklearn.utils._metadata_requests.MetadataRequest'>
    >>> type(get_routing_for_object(pipe.named_steps.lr_cv))
    <class 'sklearn.utils._metadata_requests.MetadataRouter'>
    """
    # doing this instead of a try/except since an AttributeError could be raised
    # for other reasons.
    if hasattr(obj, "get_metadata_routing"):
        return obj.get_metadata_routing().__sklearn_clone__()

    elif getattr(obj, "_type", None) in ["metadata_request", "metadata_router"]:
        return obj.__sklearn_clone__()

    return MetadataRequest(owner=None)


# Request method
# ==============
# This section includes what's needed for the `RequestMethod` descriptor and
# the dynamic generation of `set_{method}_request` methods in the `_MetadataRequester`
# mixin class.

# These strings are used to dynamically generate the docstrings for the methods.
REQUESTER_DOC_EMPTY = """        No-op.

        Calling this method has no effect.

"""
REQUESTER_DOC = """        Configure whether metadata should be requested to be \
passed to the ``{method}`` method.

        Note that this method is only relevant when this estimator is used as a
        sub-estimator within a :term:`meta-estimator` and metadata routing is enabled
        with ``enable_metadata_routing=True`` (see :func:`sklearn.set_config`).
        Please check the :ref:`User Guide <metadata_routing>` on how the routing
        mechanism works.

        The options for each parameter are:

        - ``True``: metadata is requested, and \
passed to ``{method}`` if provided. The request is ignored if \
metadata is not provided.

        - ``False``: metadata is not requested and the meta-estimator \
will not pass it to ``{method}``.

        - ``None``: metadata is not requested, and the meta-estimator \
will raise an error if the user provides it.

        - ``str``: metadata should be passed to the meta-estimator with \
this given alias instead of the original name.

        The default (``sklearn.utils.metadata_routing.UNCHANGED``) retains the
        existing request. This allows you to change the request for some
        parameters and not others.

        .. versionadded:: 1.3

"""
REQUESTER_DOC_PARAMS_SECTION = """        Parameters
        ----------
"""
REQUESTER_DOC_PARAM = """        {metadata} : str, True, False, or None, \
                    default=sklearn.utils.metadata_routing.UNCHANGED
            Metadata routing for ``{metadata}`` parameter in ``{method}``.

"""
REQUESTER_DOC_RETURN = """        Returns
        -------
        self : object
            The updated object.
"""


class RequestMethod:
    """
    Descriptor for defining `set_{method}_request` methods in estimators.

    .. versionadded:: 1.3

    Parameters
    ----------
    name : str
        The name of the method for which the request function should be
        created, e.g. ``"fit"`` would create a ``set_fit_request`` function.

    keys : list of str
        A list of strings which are accepted parameters by the created
        function, e.g. ``["sample_weight"]`` if the corresponding method
        accepts it as a metadata.

    validate_keys : bool, default=True
        Whether to check if the requested parameters fit the actual parameters
        of the method.

    Notes
    -----
    This class is a descriptor [1]_ and uses PEP-362 to set the signature of
    the returned function [2]_.

    References
    ----------
    .. [1] https://docs.python.org/3/howto/descriptor.html

    .. [2] https://www.python.org/dev/peps/pep-0362/
    """

    def __init__(self, name, keys, validate_keys=True):
        self.name = name
        self.keys = keys
        self.validate_keys = validate_keys

    def __get__(self, instance, owner):
        # we would want to have a method which accepts only the expected args
        def func(*args, **kw):
            """Updates the `_metadata_request` attribute of the consumer (`instance`)
            for the parameters provided as `**kw`.

            This docstring is overwritten below.
            See REQUESTER_DOC for expected functionality.
            """
            if not _routing_enabled():
                raise RuntimeError(
                    "This method is only available when metadata routing is enabled."
                    " You can enable it using"
                    " sklearn.set_config(enable_metadata_routing=True)."
                )

            if self.validate_keys and (set(kw) - set(self.keys)):
                raise TypeError(
                    f"Unexpected args: {set(kw) - set(self.keys)} in {self.name}. "
                    f"Accepted arguments are: {set(self.keys)}"
                )

            # This makes it possible to use the decorated method as an unbound method,
            # for instance when monkeypatching.
            # https://github.com/scikit-learn/scikit-learn/issues/28632
            if instance is None:
                _instance = args[0]
                args = args[1:]
            else:
                _instance = instance

            # Replicating python's behavior when positional args are given other than
            # `self`, and `self` is only allowed if this method is unbound.
            if args:
                raise TypeError(
                    f"set_{self.name}_request() takes 0 positional argument but"
                    f" {len(args)} were given"
                )

            requests = _instance._get_metadata_request()
            method_metadata_request = getattr(requests, self.name)

            for prop, alias in kw.items():
                if alias is not UNCHANGED:
                    method_metadata_request.add_request(param=prop, alias=alias)
            _instance._metadata_request = requests

            return _instance

        # Now we set the relevant attributes of the function so that it seems
        # like a normal method to the end user, with known expected arguments.
        func.__name__ = f"set_{self.name}_request"
        params = [
            inspect.Parameter(
                name="self",
                kind=inspect.Parameter.POSITIONAL_OR_KEYWORD,
                annotation=owner,
            )
        ]
        params.extend(
            [
                inspect.Parameter(
                    k,
                    inspect.Parameter.KEYWORD_ONLY,
                    default=UNCHANGED,
                    annotation=Optional[Union[bool, None, str]],
                )
                for k in self.keys
            ]
        )
        func.__signature__ = inspect.Signature(
            params,
            return_annotation=owner,
        )
        if self.keys:
            doc = REQUESTER_DOC.format(method=self.name)
            doc += REQUESTER_DOC_PARAMS_SECTION
            for metadata in self.keys:
                doc += REQUESTER_DOC_PARAM.format(metadata=metadata, method=self.name)
        else:
            doc = REQUESTER_DOC_EMPTY
        doc += REQUESTER_DOC_RETURN
        func.__doc__ = doc
        return func


class _MetadataRequester:
    """Mixin class for adding metadata request functionality.

    ``BaseEstimator`` inherits from this Mixin.

    .. versionadded:: 1.3
    """

    if TYPE_CHECKING:  # pragma: no cover
        # This code is never run in runtime, but it's here for type checking.
        # Type checkers fail to understand that the `set_{method}_request`
        # methods are dynamically generated, and they complain that they are
        # not defined. We define them here to make type checkers happy.
        # During type checking analyzers assume this to be True.
        # The following list of defined methods mirrors the list of methods
        # in SIMPLE_METHODS.
        # fmt: off
        def set_fit_request(self, **kwargs): pass
        def set_partial_fit_request(self, **kwargs): pass
        def set_predict_request(self, **kwargs): pass
        def set_predict_proba_request(self, **kwargs): pass
        def set_predict_log_proba_request(self, **kwargs): pass
        def set_decision_function_request(self, **kwargs): pass
        def set_score_request(self, **kwargs): pass
        def set_split_request(self, **kwargs): pass
        def set_transform_request(self, **kwargs): pass
        def set_inverse_transform_request(self, **kwargs): pass
        # fmt: on

    def __init_subclass__(cls, **kwargs):
        """Set the ``set_{method}_request`` methods.

        This uses PEP-487 [1]_ to set the ``set_{method}_request`` methods. It
        looks for the information available in the set default values which are
        set using ``__metadata_request__*`` class attributes, or inferred
        from method signatures.

        The ``__metadata_request__*`` class attributes are used when a method
        does not explicitly accept a metadata through its arguments or if the
        developer would like to specify a request value for those metadata
        which are different from the default ``None``.

        References
        ----------
        .. [1] https://www.python.org/dev/peps/pep-0487
        """

        def is_RequestMethod(obj, name: str):
            """Check if obj.name is a RequestMethod"""
            value = inspect.getattr_static(obj, name)
            return isinstance(value, RequestMethod)

        def _has_explicit_set_method_request(cls, name):
            # True if this class has a set_method_request defined or inherited
            # which is not a descriptor
            return hasattr(cls, name) and not is_RequestMethod(cls, name)

        def _needs_generated_set_request(cls, name, requests):
            # True if this class has requestable metadata or requests is empty but
            # a parent class hands down a RequestMethod
            if requests:
                return True
            return hasattr(cls, name) and is_RequestMethod(cls, name)

        try:
            for method in SIMPLE_METHODS:
                set_method_name = f"set_{method}_request"
                requests = cls._get_class_level_metadata_request_values(method)

                if _has_explicit_set_method_request(cls, set_method_name):
                    continue

                if _needs_generated_set_request(cls, set_method_name, requests):
                    setattr(
                        cls, set_method_name, RequestMethod(method, sorted(requests))
                    )

        except Exception:
            # if there are any issues here, it will be raised when
            # ``get_metadata_routing`` is called. Here we are going to ignore
            # all the issues and make sure class definition does not fail.
            pass
        super().__init_subclass__(**kwargs)

    @classmethod
    def _get_class_level_metadata_request_values(
        cls,
        method_name: str,
        method: Callable | None = None,
        ignore_params: Iterable[str] | None = None,
    ):
        """Get class level metadata request values.

        Parameters
        ----------
        method_name : str
            The name of the method to get the metadata request values for.

        method : callable, default=None
            The method to get the metadata request values for. If None, the method
            from the class with the name `method_name` is used.

        ignore_params : set, default=None
            A set of parameter names to ignore. The usual parameters
            `X`, `y`, `Y`, `Xt`, `yt` are always ignored.

        Returns
        -------
        requests : dict
            A dictionary of metadata request values.

        Notes
        -----
        This method first checks the `method`'s signature for passable metadata and then
        updates these with the metadata request values set at class level via the
        ``__metadata_request__{method}`` class attributes.

        This method (being a class-method), does not take request values set at
        instance level into account.
        """
        # Here we use `isfunction` instead of `ismethod` because calling `getattr`
        # on a class instead of an instance returns an unbound function.
        # If the given method doesn't exist or is not a function on the class, we simply
        # return early with an empty dict.
        if method is None and (
            not hasattr(cls, method_name)
            or not inspect.isfunction(getattr(cls, method_name))
        ):
            return dict()

        resolved_method: Callable = (
            method if method is not None else getattr(cls, method_name)
        )

        # ignore the first parameter of the method, which is usually "self".
        # In case of a callable which is usually passed from a scorer, we can still
        # safely ignore the first argument which is "y_true"
        signature_items = list(inspect.signature(resolved_method).parameters.items())[
            1:
        ]

        ignore_params = set() if ignore_params is None else set(ignore_params)
        ignore_params.update({"X", "y", "Y", "Xt", "yt"})

        params = defaultdict(
            str,
            {
                param_name: None
                for param_name, param_info in signature_items
                if param_name not in ignore_params
                and param_info.kind
                not in {param_info.VAR_POSITIONAL, param_info.VAR_KEYWORD}
            },
        )
        # Then overwrite those defaults with the ones provided in
        # `__metadata_request__{method}` class attributes, which take precedence over
        # signature sniffing.

        # need to go through the MRO since this is a classmethod and
        # ``vars`` doesn't report the parent class attributes. We go through
        # the reverse of the MRO so that child classes have precedence over
        # their parents.
        substr = f"__metadata_request__{method_name}"
        for base_class in reversed(inspect.getmro(cls)):
            # Copy is needed with free-threaded context to avoid
            # RuntimeError: dictionary changed size during iteration.
            # copy.deepcopy applied on an instance of base_class adds
            # __slotnames__ attribute to base_class.
            base_class_items = vars(base_class).copy().items()
            for attr, value in base_class_items:
                # we don't check for equivalence since python prefixes attrs
                # starting with __ with the `_ClassName`.
                if substr not in attr:
                    continue
                for prop, alias in value.items():
                    # Here we add request values specified via those class attributes
                    # to the result dictionary (params). Adding a request which already
                    # exists will override the previous one. Since we go through the
                    # MRO in reverse order, the one specified by the lowest most classes
                    # in the inheritance tree are the ones which take effect.
                    if prop not in params and alias == UNUSED:
                        raise ValueError(
                            f"Trying to remove parameter {prop} with UNUSED which"
                            " doesn't exist."
                        )

                    params[prop] = alias

        return {param: alias for param, alias in params.items() if alias is not UNUSED}

    def _get_metadata_request(self):
        """Get requested metadata for the instance.

        Please check :ref:`User Guide <metadata_routing>` on how the routing
        mechanism works.

        Returns
        -------
        request : MetadataRequest
            A :class:`~sklearn.utils.metadata_routing.MetadataRequest` instance.
        """
        if hasattr(self, "_metadata_request"):
            requests = get_routing_for_object(self._metadata_request)
        else:
            requests = MetadataRequest(owner=self)
            for method_name in SIMPLE_METHODS:
                setattr(
                    requests,
                    method_name,
                    MethodMetadataRequest(
                        owner=self,
                        method=method_name,
                        requests=self._get_class_level_metadata_request_values(
                            method_name
                        ),
                    ),
                )
        return requests

    def get_metadata_routing(self):
        """Get metadata routing of this object.

        Please check :ref:`User Guide <metadata_routing>` on how the routing
        mechanism works.

        Returns
        -------
        routing : MetadataRequest
            A :class:`~sklearn.utils.metadata_routing.MetadataRequest` encapsulating
            routing information.
        """
        return self._get_metadata_request()


# Process Routing in Routers
# ==========================
# This is almost always the only method used in routers to process and route
# given metadata. This is to minimize the boilerplate required in routers.


# Here the first two arguments are positional only which makes everything
# passed as keyword argument a metadata. The first two args also have an `_`
# prefix to reduce the chances of name collisions with the passed metadata, and
# since they're positional only, users will never type those underscores.
def process_routing(_obj, _method, /, **kwargs):
    """Validate and route metadata.

    This function is used inside a :term:`router`'s method, e.g. :term:`fit`,
    to validate the metadata and handle the routing.

    Assuming this signature of a router's fit method:
    ``fit(self, X, y, sample_weight=None, **fit_params)``,
    a call to this function would be:
    ``process_routing(self, "fit", sample_weight=sample_weight, **fit_params)``.

    Internally, the function uses the router's `MetadataRouter` object (as
    returned by a call to its `get_metadata_routing` method) to validate
    per method that the routed metadata had been requested by the underlying
    estimator, and extracts a mapping of the given metadata to the requested
    metadata based on the routing information defined by the `MetadataRouter`.

    Note that if routing is not enabled and ``kwargs`` is empty, then it
    returns an empty routing where ``process_routing(...).ANYTHING.ANY_METHOD``
    is always an empty dictionary.

    The output of this function is a :class:`~sklearn.utils.Bunch` that has a key for
    each consuming object and those hold keys for their consuming methods, which then
    contain keys for the metadata which should be routed to them.

    Read more on developing custom estimators that can route metadata in the
    :ref:`Metadata Routing Developing Guide
    <sphx_glr_auto_examples_miscellaneous_plot_metadata_routing.py>`.

    .. versionadded:: 1.3

    Parameters
    ----------
    _obj : object
        An object implementing ``get_metadata_routing``. Typically a
        :term:`meta-estimator`.

    _method : str
        The name of the router's method in which this function is called.

    **kwargs : dict
        Metadata to be routed.

    Returns
    -------
    routed_params : Bunch
        A :class:`~sklearn.utils.Bunch` of the form ``{"object_name":
        {"method_name": {metadata: value}}}`` which can be used to pass the
        required metadata to corresponding methods or corresponding child objects.
        The object names are those defined in `obj.get_metadata_routing()`.

    Examples
    --------
    >>> import numpy as np
    >>> from sklearn import set_config
    >>> from sklearn.utils.metadata_routing import process_routing
    >>> from sklearn.linear_model import Ridge
    >>> from sklearn.feature_selection import SelectFromModel
    >>> set_config(enable_metadata_routing=True)
    >>> process_routing(
    ...     SelectFromModel(Ridge().set_fit_request(sample_weight=True)),
    ...     "fit",
    ...     sample_weight=np.array([1, 1, 2]),
    ... )
    {'estimator': {'fit': {'sample_weight': array([1, 1, 2])}}}
    >>> set_config(enable_metadata_routing=False)
    """
    if not kwargs:
        # If routing is not enabled and kwargs are empty, then we don't have to
        # try doing any routing, we can simply return a structure which returns
        # an empty dict on routed_params.ANYTHING.ANY_METHOD.
        class EmptyRequest:
            def get(self, name, default=None):
                return Bunch(**{method: dict() for method in METHODS})

            def __getitem__(self, name):
                return Bunch(**{method: dict() for method in METHODS})

            def __getattr__(self, name):
                return Bunch(**{method: dict() for method in METHODS})

        return EmptyRequest()

    if not (hasattr(_obj, "get_metadata_routing") or isinstance(_obj, MetadataRouter)):
        raise AttributeError(
            f"The given object ({_routing_repr(_obj)}) needs to either"
            " implement the routing method `get_metadata_routing` or be a"
            " `MetadataRouter` instance."
        )
    if _method not in METHODS:
        raise TypeError(
            f"Can only route and process input on these methods: {METHODS}, "
            f"while the passed method is: {_method}."
        )

    request_routing = get_routing_for_object(_obj)
    request_routing.validate_metadata(params=kwargs, method=_method)
    routed_params = request_routing.route_params(params=kwargs, caller=_method)

    return routed_params
