import re from inspect import signature from typing import Optional import pytest # make it possible to discover experimental estimators when calling `all_estimators` from sklearn.experimental import enable_iterative_imputer # noqa from sklearn.experimental import enable_halving_search_cv # noqa from sklearn.utils.discovery import all_estimators from sklearn.utils.discovery import all_displays from sklearn.utils.discovery import all_functions numpydoc_validation = pytest.importorskip("numpydoc.validate") def get_all_methods(): estimators = all_estimators() displays = all_displays() for name, Klass in estimators + displays: if name.startswith("_"): # skip private classes continue methods = [] for name in dir(Klass): if name.startswith("_"): continue method_obj = getattr(Klass, name) if hasattr(method_obj, "__call__") or isinstance(method_obj, property): methods.append(name) methods.append(None) for method in sorted(methods, key=str): yield Klass, method def get_all_functions_names(): functions = all_functions() for _, func in functions: # exclude functions from utils.fixex since they come from external packages if "utils.fixes" not in func.__module__: yield f"{func.__module__}.{func.__name__}" def filter_errors(errors, method, Klass=None): """ Ignore some errors based on the method type. These rules are specific for scikit-learn.""" for code, message in errors: # We ignore following error code, # - RT02: The first line of the Returns section # should contain only the type, .. # (as we may need refer to the name of the returned # object) # - GL01: Docstring text (summary) should start in the line # immediately after the opening quotes (not in the same line, # or leaving a blank line in between) # - GL02: If there's a blank line, it should be before the # first line of the Returns section, not after (it allows to have # short docstrings for properties). if code in ["RT02", "GL01", "GL02"]: continue # Ignore PR02: Unknown parameters for properties. We sometimes use # properties for ducktyping, i.e. SGDClassifier.predict_proba # Ignore GL08: Parsing of the method signature failed, possibly because this is # a property. Properties are sometimes used for deprecated attributes and the # attribute is already documented in the class docstring. # # All error codes: # https://numpydoc.readthedocs.io/en/latest/validation.html#built-in-validation-checks if code in ("PR02", "GL08") and Klass is not None and method is not None: method_obj = getattr(Klass, method) if isinstance(method_obj, property): continue # Following codes are only taken into account for the # top level class docstrings: # - ES01: No extended summary found # - SA01: See Also section not found # - EX01: No examples section found if method is not None and code in ["EX01", "SA01", "ES01"]: continue yield code, message def repr_errors(res, Klass=None, method: Optional[str] = None) -> str: """Pretty print original docstring and the obtained errors Parameters ---------- res : dict result of numpydoc.validate.validate Klass : {Estimator, Display, None} estimator object or None method : str if estimator is not None, either the method name or None. Returns ------- str String representation of the error. """ if method is None: if hasattr(Klass, "__init__"): method = "__init__" elif Klass is None: raise ValueError("At least one of Klass, method should be provided") else: raise NotImplementedError if Klass is not None: obj = getattr(Klass, method) try: obj_signature = str(signature(obj)) except TypeError: # In particular we can't parse the signature of properties obj_signature = ( "\nParsing of the method signature failed, " "possibly because this is a property." ) obj_name = Klass.__name__ + "." + method else: obj_signature = "" obj_name = method msg = "\n\n" + "\n\n".join( [ str(res["file"]), obj_name + obj_signature, res["docstring"], "# Errors", "\n".join( " - {}: {}".format(code, message) for code, message in res["errors"] ), ] ) return msg @pytest.mark.parametrize("function_name", get_all_functions_names()) def test_function_docstring(function_name, request): """Check function docstrings using numpydoc.""" res = numpydoc_validation.validate(function_name) res["errors"] = list(filter_errors(res["errors"], method="function")) if res["errors"]: msg = repr_errors(res, method=f"Tested function: {function_name}") raise ValueError(msg) @pytest.mark.parametrize("Klass, method", get_all_methods()) def test_docstring(Klass, method, request): base_import_path = Klass.__module__ import_path = [base_import_path, Klass.__name__] if method is not None: import_path.append(method) import_path = ".".join(import_path) res = numpydoc_validation.validate(import_path) res["errors"] = list(filter_errors(res["errors"], method, Klass=Klass)) if res["errors"]: msg = repr_errors(res, Klass, method) raise ValueError(msg) if __name__ == "__main__": import sys import argparse parser = argparse.ArgumentParser(description="Validate docstring with numpydoc.") parser.add_argument("import_path", help="Import path to validate") args = parser.parse_args() res = numpydoc_validation.validate(args.import_path) import_path_sections = args.import_path.split(".") # When applied to classes, detect class method. For functions # method = None. # TODO: this detection can be improved. Currently we assume that we have # class # methods if the second path element before last is in camel case. if len(import_path_sections) >= 2 and re.match( r"(?:[A-Z][a-z]*)+", import_path_sections[-2] ): method = import_path_sections[-1] else: method = None res["errors"] = list(filter_errors(res["errors"], method)) if res["errors"]: msg = repr_errors(res, method=args.import_path) print(msg) sys.exit(1) else: print("All docstring checks passed for {}!".format(args.import_path))