Repository: scikit-learn/scikit-learn
File: sklearn/utils/_metadata_requests.py (Python)

Code before:
    <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
    >>> from sklearn.linear_model import LogisticRegression
    >>> set_config(enable_metadata_routing=True)
    >>> lr = (
    ...     LogisticRegression()
    ...     .set_fit_request(sample_weight=True)
    ...     .set_score_request(sample_weight=False)
    ... )
    >>> lr._metadata_request
    {'fit': {'sample_weight': True}, 'score': {'sample_weight': False}}
    >>> type(lr._metadata_request)
    <class 'sklearn.utils._metadata_requests.MetadataRequest'>
    >>> 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 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

Review comment (suggestion):
I feel a example of creating a `MetadataRequest` and pprint it (like the example for `MethodMapping` and `MetadataRouter`) would be more appropriate here. Because here I feel that to understand the example, one needs to be familiar with the `_MetadataRequester` mixin, the `_metadata_request` attribute etc.

Code after:

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