From abcd37c77b5494c4b3a4981e449f24564ddca4da Mon Sep 17 00:00:00 2001 From: Lucas Colley Date: Sat, 14 Dec 2024 16:59:53 +0000 Subject: [PATCH] ignore some errors at module level --- numpydoc/__main__.py | 2 +- numpydoc/hooks/validate_docstrings.py | 4 +++ numpydoc/tests/hooks/test_validate_hook.py | 2 -- numpydoc/tests/test_main.py | 16 ++++------ numpydoc/validate.py | 34 +++++++++++++--------- 5 files changed, 31 insertions(+), 27 deletions(-) diff --git a/numpydoc/__main__.py b/numpydoc/__main__.py index b3b6d159..08125e0e 100644 --- a/numpydoc/__main__.py +++ b/numpydoc/__main__.py @@ -1,5 +1,5 @@ """ -Implementing `python -m numpydoc` functionality. +Implementing `python -m numpydoc` functionality """ from .cli import main diff --git a/numpydoc/hooks/validate_docstrings.py b/numpydoc/hooks/validate_docstrings.py index 562a1f09..f5251522 100644 --- a/numpydoc/hooks/validate_docstrings.py +++ b/numpydoc/hooks/validate_docstrings.py @@ -60,6 +60,10 @@ def name(self) -> str: def is_function_or_method(self) -> bool: return isinstance(self.node, (ast.FunctionDef, ast.AsyncFunctionDef)) + @property + def is_mod(self) -> bool: + return self.is_module + @property def is_generator_function(self) -> bool: if not self.is_function_or_method: diff --git a/numpydoc/tests/hooks/test_validate_hook.py b/numpydoc/tests/hooks/test_validate_hook.py index ab71a871..18b03818 100644 --- a/numpydoc/tests/hooks/test_validate_hook.py +++ b/numpydoc/tests/hooks/test_validate_hook.py @@ -29,8 +29,6 @@ def test_validate_hook(example_module, config, capsys): +-------------------------------------------+-------------------------------------+---------+----------------------------------------------------+ | file | item | check | description | +===========================================+=====================================+=========+====================================================+ - | numpydoc/tests/hooks/example_module.py:1 | example_module | EX01 | No examples section found | - +-------------------------------------------+-------------------------------------+---------+----------------------------------------------------+ | numpydoc/tests/hooks/example_module.py:4 | example_module.some_function | ES01 | No extended summary found | +-------------------------------------------+-------------------------------------+---------+----------------------------------------------------+ | numpydoc/tests/hooks/example_module.py:4 | example_module.some_function | PR01 | Parameters {'name'} not documented | diff --git a/numpydoc/tests/test_main.py b/numpydoc/tests/test_main.py index 12c06840..bd06be3f 100644 --- a/numpydoc/tests/test_main.py +++ b/numpydoc/tests/test_main.py @@ -117,7 +117,7 @@ def test_validate_perfect_docstring(): assert exit_status == 0 -@pytest.mark.parametrize("args", [[], ["--ignore", "ES01", "SA01", "EX01"]]) +@pytest.mark.parametrize("args", [[], ["--ignore", "SS03"]]) def test_lint(capsys, args): argv = ["lint", "numpydoc/__main__.py"] + args if args: @@ -126,15 +126,11 @@ def test_lint(capsys, args): else: expected = inspect.cleandoc( """ - +------------------------+----------+---------+----------------------------+ - | file | item | check | description | - +========================+==========+=========+============================+ - | numpydoc/__main__.py:1 | __main__ | ES01 | No extended summary found | - +------------------------+----------+---------+----------------------------+ - | numpydoc/__main__.py:1 | __main__ | SA01 | See Also section not found | - +------------------------+----------+---------+----------------------------+ - | numpydoc/__main__.py:1 | __main__ | EX01 | No examples section found | - +------------------------+----------+---------+----------------------------+ + +------------------------+----------+---------+------------------------------------+ + | file | item | check | description | + +========================+==========+=========+====================================+ + | numpydoc/__main__.py:1 | __main__ | SS03 | Summary does not end with a period | + +------------------------+----------+---------+------------------------------------+ """ ) expected_status = 1 diff --git a/numpydoc/validate.py b/numpydoc/validate.py index 138e9d48..caa64c50 100644 --- a/numpydoc/validate.py +++ b/numpydoc/validate.py @@ -276,6 +276,10 @@ def type(self): @property def is_function_or_method(self): return inspect.isfunction(self.obj) + + @property + def is_mod(self): + return inspect.ismodule(self.obj) @property def is_generator_function(self): @@ -690,7 +694,7 @@ def validate(obj_name, validator_cls=None, **validator_kwargs): if doc.num_summary_lines > 1: errs.append(error("SS06")) - if not doc.extended_summary: + if not doc.is_mod and not doc.extended_summary: errs.append(("ES01", "No extended summary found")) # PR01: Parameters not documented @@ -742,20 +746,22 @@ def validate(obj_name, validator_cls=None, **validator_kwargs): if not doc.yields and doc.is_generator_function: errs.append(error("YD01")) - if not doc.see_also: - errs.append(error("SA01")) - else: - for rel_name, rel_desc in doc.see_also.items(): - if rel_desc: - if not rel_desc.endswith("."): - errs.append(error("SA02", reference_name=rel_name)) - if rel_desc[0].isalpha() and not rel_desc[0].isupper(): - errs.append(error("SA03", reference_name=rel_name)) - else: - errs.append(error("SA04", reference_name=rel_name)) + if not doc.is_mod: + + if not doc.see_also: + errs.append(error("SA01")) + else: + for rel_name, rel_desc in doc.see_also.items(): + if rel_desc: + if not rel_desc.endswith("."): + errs.append(error("SA02", reference_name=rel_name)) + if rel_desc[0].isalpha() and not rel_desc[0].isupper(): + errs.append(error("SA03", reference_name=rel_name)) + else: + errs.append(error("SA04", reference_name=rel_name)) - if not doc.examples: - errs.append(error("EX01")) + if not doc.examples: + errs.append(error("EX01")) errs = [err for err in errs if err[0] not in ignore_validation_comments]