Skip to content

MNT Add ignore_types to assert_docstring_consistency #30944

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Apr 28, 2025
Merged

MNT Add ignore_types to assert_docstring_consistency #30944

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
41d794e
add skip type
lucyleeow Mar 5, 2025
a001aff
Merge branch 'main' into ds_type_ignore
lucyleeow Mar 19, 2025
6101cbc
review
lucyleeow Mar 19, 2025
f234c49
Merge branch 'main' into ds_type_ignore
lucyleeow Apr 28, 2025
284544f
review
lucyleeow Apr 28, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 18 additions & 1 deletion sklearn/tests/test_docstring_parameters_consistency.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,27 @@
import pytest

from sklearn import metrics
from sklearn.ensemble import StackingClassifier, StackingRegressor
from sklearn.ensemble import (
BaggingClassifier,
BaggingRegressor,
IsolationForest,
StackingClassifier,
StackingRegressor,
)
from sklearn.utils._testing import assert_docstring_consistency, skip_if_no_numpydoc

CLASS_DOCSTRING_CONSISTENCY_CASES = [
{
"objects": [BaggingClassifier, BaggingRegressor, IsolationForest],
"include_params": ["max_samples"],
"exclude_params": None,
"include_attrs": False,
"exclude_attrs": None,
"include_returns": False,
"exclude_returns": None,
"descr_regex_pattern": r"The number of samples to draw from X to train each.*",
"ignore_types": ("max_samples"),
},
{
"objects": [StackingClassifier, StackingRegressor],
"include_params": ["cv", "n_jobs", "passthrough", "verbose"],
Expand Down
48 changes: 46 additions & 2 deletions sklearn/utils/_testing.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -686,12 +686,42 @@ def _get_diff_msg(docstrings_grouped):


def _check_consistency_items(
items_docs, type_or_desc, section, n_objects, descr_regex_pattern=""
items_docs,
type_or_desc,
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we document that the possible values for type_or_desc is "type specification" and "description"?

Copy link
Member Author

@lucyleeow lucyleeow Apr 28, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks this function was definitely worth a parameter docstring section.

section,
n_objects,
descr_regex_pattern="",
ignore_types=tuple(),
):
"""Helper to check docstring consistency of all `items_docs`.

If item is not present in all objects, checking is skipped and warning raised.
If `regex` provided, match descriptions to all descriptions.

Parameters
----------
items_doc : dict of dict of str
Dictionary where the key is the string type or description, value is
a dictionary where the key is "type description" or "description"
and the value is a list of object names with the same string type or
description.

type_or_desc : {"type description", "description"}
Whether to check type description or description between objects.

section : {"Parameters", "Attributes", "Returns"}
Name of the section type.

n_objects : int
Total number of objects.

descr_regex_pattern : str, default=""
Regex pattern to match for description of all objects.
Ignored when `type_or_desc="type description".

ignore_types : tuple of str, default=()
Tuple of parameter/attribute/return names for which type description
matching is ignored. Ignored when `type_or_desc="description".
"""
skipped = []
for item_name, docstrings_grouped in items_docs.items():
Expand All @@ -710,6 +740,9 @@ def _check_consistency_items(
f" does not match 'descr_regex_pattern': {descr_regex_pattern} "
)
raise AssertionError(msg)
# Skip type checking for items in `ignore_types`
elif type_or_desc == "type specification" and item_name in ignore_types:
continue
# Otherwise, if more than one key, docstrings not consistent between objects
elif len(docstrings_grouped.keys()) > 1:
msg_diff = _get_diff_msg(docstrings_grouped)
Expand Down Expand Up @@ -738,6 +771,7 @@ def assert_docstring_consistency(
include_returns=False,
exclude_returns=None,
descr_regex_pattern=None,
ignore_types=tuple(),
):
r"""Check consistency between docstring parameters/attributes/returns of objects.

Expand Down Expand Up @@ -786,6 +820,10 @@ def assert_docstring_consistency(
parameters/attributes/returns. If None, will revert to default behavior
of comparing descriptions between objects.

ignore_types : tuple of str, default=tuple()
Tuple of parameter/attribute/return names to exclude from type description
matching between objects.

Examples
--------
>>> from sklearn.metrics import (accuracy_score, classification_report,
Expand Down Expand Up @@ -849,7 +887,13 @@ def _create_args(include, exclude, arg_name, section_name):
type_items[item_name][type_def].append(obj_name)
desc_items[item_name][desc].append(obj_name)

_check_consistency_items(type_items, "type specification", section, n_objects)
_check_consistency_items(
type_items,
"type specification",
section,
n_objects,
ignore_types=ignore_types,
)
_check_consistency_items(
desc_items,
"description",
Expand Down