New violation code D504 (#220)

jsh9 · web-flow · commit 20a40294f532 · 2025-03-09T01:14:46.000-05:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,14 @@
 # Change Log
 
+## [unpublished]
+
+- Changed
+  - Added `DOC504` and a config option
+    `--should-declare-assert-error-if-assert-statement-exists`. If this option
+    is True and a function has an `assert` statement, an `AssertError`
+    declaration is required in the docstring. Otherwise `DOC504` is raised.
+    (This changes the behavior introduced in v0.6.1.)
+
 ## [0.6.2] - 2025-02-17
 
 - Fixed
diff --git a/README.md b/README.md
@@ -202,7 +202,7 @@ _pydoclint_ currently has 7 categories of style violation codes:
 - `DOC2xx`: Violations about return argument(s)
 - `DOC3xx`: Violations about class docstring and class constructor
 - `DOC4xx`: Violations about "yield" statements
-- `DOC5xx`: Violations about "raise" statements
+- `DOC5xx`: Violations about "raise" and "assert" statements
 - `DOC6xx`: Violations about class attributes
 
 For detailed explanations of each violation code, please read this page:
diff --git a/docs/index.md b/docs/index.md
@@ -202,7 +202,7 @@ _pydoclint_ currently has 7 categories of style violation codes:
 - `DOC2xx`: Violations about return argument(s)
 - `DOC3xx`: Violations about class docstring and class constructor
 - `DOC4xx`: Violations about "yield" statements
-- `DOC5xx`: Violations about "raise" statements
+- `DOC5xx`: Violations about "raise" and "assert" statements
 - `DOC6xx`: Violations about class attributes
 
 For detailed explanations of each violation code, please read this page:
diff --git a/docs/violation_codes.md b/docs/violation_codes.md
@@ -10,7 +10,7 @@
 - [2. `DOC2xx`: Violations about return argument(s)](#2-doc2xx-violations-about-return-arguments)
 - [3. `DOC3xx`: Violations about class docstring and class constructor](#3-doc3xx-violations-about-class-docstring-and-class-constructor)
 - [4. `DOC4xx`: Violations about "yield" statements](#4-doc4xx-violations-about-yield-statements)
-- [5. `DOC5xx`: Violations about "raise" statements](#5-doc5xx-violations-about-raise-statements)
+- [5. `DOC5xx`: Violations about "raise" and "assert" statements](#5-doc5xx-violations-about-raise-and-assert-statements)
 - [6. `DOC6xx`: Violations about class attributes](#6-doc6xx-violations-about-class-attributes)
 
 <!--TOC-->
@@ -83,13 +83,14 @@ have a return section.
 | `DOC403` | Function/method has a "Yields" section in the docstring, but there are no "yield" statements, or the return annotation is not a Generator/Iterator/Iterable |
 | `DOC404` | The types in the docstring's Yields section and the return annotation in the signature are not consistent                                                   |
 
-## 5. `DOC5xx`: Violations about "raise" statements
+## 5. `DOC5xx`: Violations about "raise" and "assert" statements
 
-| Code     | Explanation                                                                                               |
-| -------- | --------------------------------------------------------------------------------------------------------- |
-| `DOC501` | Function/method has raise/assert statements, but the docstring does not have a "Raises" section           |
-| `DOC502` | Function/method has a "Raises" section in the docstring, but there are not "raise" statements in the body |
-| `DOC503` | Exceptions in the "Raises" section in the docstring do not match those in the function body               |
+| Code     | Explanation                                                                                                                               |
+| -------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `DOC501` | Function/method has raise statements, but the docstring does not have a "Raises" section                                                  |
+| `DOC502` | Function/method has a "Raises" section in the docstring, but there are not "raise" statements in the body                                 |
+| `DOC503` | Exceptions in the "Raises" section in the docstring do not match those in the function body                                               |
+| `DOC504` | Function/method has assert statements, but the docstring does not have a "Raises" section. (Assert statements could raise "AssertError".) |
 
 ## 6. `DOC6xx`: Violations about class attributes
 
diff --git a/pydoclint/flake8_entry.py b/pydoclint/flake8_entry.py
@@ -225,6 +225,18 @@ def add_options(cls, parser: Any) -> None:  # noqa: D102
                 ' appear in the docstring.'
             ),
         )
+        parser.add_option(
+            '-sdae',
+            '--should-declare-assert-error-if-assert-statement-exists',
+            action='store',
+            default='False',
+            help=(
+                'If True, we need to declare AssertError in the "Raises"'
+                ' section of the docstring if there are any "assert"'
+                ' statements in the function body. This is because an "assert"'
+                ' statement could raise an AssertError.'
+            ),
+        )
         parser.add_option(
             '-csm',
             '--check-style-mismatch',
diff --git a/pydoclint/main.py b/pydoclint/main.py
@@ -264,6 +264,19 @@ def validateStyleValue(
         ' appear in the docstring.'
     ),
 )
+@click.option(
+    '-sdae',
+    '--should-declare-assert-error-if-assert-statement-exists',
+    type=bool,
+    show_default=True,
+    default=False,
+    help=(
+        'If True, we need to declare AssertError in the "Raises"'
+        ' section of the docstring if there are any "assert"'
+        ' statements in the function body. This is because an "assert"'
+        ' statement could raise an AssertError.'
+    ),
+)
 @click.option(
     '-csm',
     '--check-style-mismatch',
@@ -379,6 +392,7 @@ def main(  # noqa: C901
         require_yield_section_when_yielding_nothing: bool,
         only_attrs_with_classvar_are_treated_as_class_attrs: bool,
         should_document_star_arguments: bool,
+        should_declare_assert_error_if_assert_statement_exists: bool,
         check_style_mismatch: bool,
         generate_baseline: bool,
         auto_regenerate_baseline: bool,
@@ -491,6 +505,9 @@ def main(  # noqa: C901
             require_yield_section_when_yielding_nothing
         ),
         shouldDocumentStarArguments=should_document_star_arguments,
+        shouldDeclareAssertErrorIfAssertStatementExists=(
+            should_declare_assert_error_if_assert_statement_exists
+        ),
         checkStyleMismatch=check_style_mismatch,
     )
 
@@ -628,6 +645,7 @@ def _checkPaths(
         requireReturnSectionWhenReturningNothing: bool = False,
         requireYieldSectionWhenYieldingNothing: bool = False,
         shouldDocumentStarArguments: bool = True,
+        shouldDeclareAssertErrorIfAssertStatementExists: bool = False,
         checkStyleMismatch: bool = False,
         quiet: bool = False,
         exclude: str = '',
@@ -689,6 +707,9 @@ def _checkPaths(
                 requireYieldSectionWhenYieldingNothing
             ),
             shouldDocumentStarArguments=shouldDocumentStarArguments,
+            shouldDeclareAssertErrorIfAssertStatementExists=(
+                shouldDeclareAssertErrorIfAssertStatementExists
+            ),
             checkStyleMismatch=checkStyleMismatch,
         )
         allViolations[filename.as_posix()] = violationsInThisFile
@@ -715,6 +736,7 @@ def _checkFile(
         requireReturnSectionWhenReturningNothing: bool = False,
         requireYieldSectionWhenYieldingNothing: bool = False,
         shouldDocumentStarArguments: bool = True,
+        shouldDeclareAssertErrorIfAssertStatementExists: bool = False,
         checkStyleMismatch: bool = False,
 ) -> list[Violation]:
     if not filename.is_file():  # sometimes folder names can end with `.py`
@@ -771,6 +793,9 @@ def _checkFile(
             requireYieldSectionWhenYieldingNothing
         ),
         shouldDocumentStarArguments=shouldDocumentStarArguments,
+        shouldDeclareAssertErrorIfAssertStatementExists=(
+            shouldDeclareAssertErrorIfAssertStatementExists
+        ),
         checkStyleMismatch=checkStyleMismatch,
     )
     visitor.visit(tree)
diff --git a/pydoclint/utils/return_yield_raise.py b/pydoclint/utils/return_yield_raise.py
@@ -98,15 +98,24 @@ def isThisNodeABareReturnStmt(node_: ast.AST) -> bool:
     return _hasExpectedStatements(node, isThisNodeABareReturnStmt)
 
 
-def hasRaiseOrAssertStatements(node: FuncOrAsyncFuncDef) -> bool:
-    """Check whether the function node has any raise or assert statements"""
+def hasRaiseStatements(node: FuncOrAsyncFuncDef) -> bool:
+    """Check whether the function node has any raise statements"""
 
     def isThisNodeARaiseStmt(node_: ast.AST) -> bool:
-        return isinstance(node_, (ast.Raise, ast.Assert))
+        return isinstance(node_, ast.Raise)
 
     return _hasExpectedStatements(node, isThisNodeARaiseStmt)
 
 
+def hasAssertStatements(node: FuncOrAsyncFuncDef) -> bool:
+    """Check whether the function node has any assert statements"""
+
+    def isThisNodeAnAssertStmt(node_: ast.AST) -> bool:
+        return isinstance(node_, ast.Assert)
+
+    return _hasExpectedStatements(node, isThisNodeAnAssertStmt)
+
+
 def getRaisedExceptions(node: FuncOrAsyncFuncDef) -> list[str]:
     """Get the raised exceptions in a function node as a sorted list"""
     return sorted(set(_getRaisedExceptions(node)))
diff --git a/pydoclint/utils/violation.py b/pydoclint/utils/violation.py
@@ -56,9 +56,10 @@
         ' https://jsh9.github.io/pydoclint/notes_generator_vs_iterator.html'
     ),
 
-    501: 'has raise/assert statements, but the docstring does not have a "Raises" section',
+    501: 'has raise statements, but the docstring does not have a "Raises" section',
     502: 'has a "Raises" section in the docstring, but there are not "raise" statements in the body',
     503: 'exceptions in the "Raises" section in the docstring do not match those in the function body.',
+    504: 'has assert statements, but the docstring does not have a "Raises" section. (Assert statements could raise "AssertError".)',
 
     601: 'Class docstring contains fewer class attributes than actual class attributes.',
     602: 'Class docstring contains more class attributes than in actual class attributes.',
diff --git a/pydoclint/visitor.py b/pydoclint/visitor.py
@@ -25,10 +25,11 @@
 from pydoclint.utils.return_arg import ReturnArg
 from pydoclint.utils.return_yield_raise import (
     getRaisedExceptions,
+    hasAssertStatements,
     hasBareReturnStatements,
     hasGeneratorAsReturnAnnotation,
     hasIteratorOrIterableAsReturnAnnotation,
-    hasRaiseOrAssertStatements,
+    hasRaiseStatements,
     hasReturnAnnotation,
     hasReturnStatements,
     hasYieldStatements,
@@ -76,6 +77,7 @@ def __init__(
             requireReturnSectionWhenReturningNothing: bool = False,
             requireYieldSectionWhenYieldingNothing: bool = False,
             shouldDocumentStarArguments: bool = True,
+            shouldDeclareAssertErrorIfAssertStatementExists: bool = False,
             checkStyleMismatch: bool = False,
     ) -> None:
         self.style: str = style
@@ -105,6 +107,9 @@ def __init__(
             requireYieldSectionWhenYieldingNothing
         )
         self.shouldDocumentStarArguments: bool = shouldDocumentStarArguments
+        self.shouldDeclareAssertErrorIfAssertStatementExists: bool = (
+            shouldDeclareAssertErrorIfAssertStatementExists
+        )
         self.checkStyleMismatch: bool = checkStyleMismatch
 
         self.parent: ast.AST = ast.Pass()  # keep track of parent node
@@ -875,7 +880,7 @@ def my_function(num: int) -> Generator[int, None, str]:
 
         return violations
 
-    def checkRaises(
+    def checkRaises(  # noqa: C901
             self,
             node: FuncOrAsyncFuncDef,
             parent: ast.AST,
@@ -890,19 +895,37 @@ def checkRaises(
         v501 = Violation(code=501, line=lineNum, msgPrefix=msgPrefix)
         v502 = Violation(code=502, line=lineNum, msgPrefix=msgPrefix)
         v503 = Violation(code=503, line=lineNum, msgPrefix=msgPrefix)
+        v504 = Violation(code=504, line=lineNum, msgPrefix=msgPrefix)
 
         docstringHasRaisesSection: bool = doc.hasRaisesSection
-        hasRaiseOrAssertStmt: bool = hasRaiseOrAssertStatements(node)
+        hasRaiseStmt: bool = hasRaiseStatements(node)
+        hasAssertStmt: bool = hasAssertStatements(node)
 
-        if hasRaiseOrAssertStmt and not docstringHasRaisesSection:
+        if hasRaiseStmt and not docstringHasRaisesSection:
             violations.append(v501)
 
-        if not hasRaiseOrAssertStmt and docstringHasRaisesSection:
-            if not self.isAbstractMethod:
+        if self.shouldDeclareAssertErrorIfAssertStatementExists:
+            if (
+                not hasAssertStmt
+                and not hasRaiseStmt
+                and docstringHasRaisesSection
+                and not self.isAbstractMethod
+            ):
+                violations.append(v502)
+        else:
+            if (
+                not hasRaiseStmt
+                and docstringHasRaisesSection
+                and not self.isAbstractMethod
+            ):
                 violations.append(v502)
 
+        if self.shouldDeclareAssertErrorIfAssertStatementExists:
+            if hasAssertStmt and not docstringHasRaisesSection:
+                violations.append(v504)
+
         # check that the raise statements match those in body.
-        if hasRaiseOrAssertStmt:
+        if hasRaiseStmt:
             docRaises: list[str] = []
 
             for raises in doc.parsed.raises:
diff --git a/tests/data/google/raises/cases.py b/tests/data/google/raises/cases.py
@@ -229,6 +229,8 @@ def func16(self) -> None:
 
     def func17(self) -> None:
         """
+        Assuming --should-declare-assert-error-if-assert-statement-exists True.
+
         It should pass.
 
         Raises:
@@ -238,6 +240,8 @@ def func17(self) -> None:
 
     def func18(self) -> None:
         """
+        Assuming --should-declare-assert-error-if-assert-statement-exists True.
+
         It should pass.
 
         Raises:
@@ -247,6 +251,8 @@ def func18(self) -> None:
 
     def func19(self) -> None:
         """
+        Assuming --should-declare-assert-error-if-assert-statement-exists True.
+
         Should fail, expects `AssertionError`.
 
         Returns:
@@ -256,6 +262,8 @@ def func19(self) -> None:
 
     def func20(self) -> None:
         """
+        When --should-declare-assert-error-if-assert-statement-exists is True:
+
         Should fail, expects `AssertionError`.
 
         Raises:
diff --git a/tests/data/numpy/raises/cases.py b/tests/data/numpy/raises/cases.py
@@ -285,6 +285,8 @@ def func16(self) -> None:
 
     def func17(self) -> None:
         """
+        When --should-declare-assert-error-if-assert-statement-exists is True:
+
         It should pass.
 
         Raises
@@ -296,6 +298,8 @@ def func17(self) -> None:
 
     def func18(self) -> None:
         """
+        When --should-declare-assert-error-if-assert-statement-exists is True:
+
         It should pass.
 
         Raises
@@ -307,6 +311,8 @@ def func18(self) -> None:
 
     def func19(self) -> None:
         """
+        When --should-declare-assert-error-if-assert-statement-exists is True:
+
         Should fail, expects `AssertionError`.
 
         Returns
@@ -317,6 +323,8 @@ def func19(self) -> None:
 
     def func20(self) -> None:
         """
+        When --should-declare-assert-error-if-assert-statement-exists is True:
+
         It should pass.
 
         Raises
diff --git a/tests/data/sphinx/raises/cases.py b/tests/data/sphinx/raises/cases.py
@@ -197,6 +197,8 @@ def func16(self) -> None:
 
     def func17(self) -> None:
         """
+        When --should-declare-assert-error-if-assert-statement-exists is True:
+
         It should pass.
 
         :raises AssertionError: every time, without a message.
@@ -205,6 +207,8 @@ def func17(self) -> None:
 
     def func18(self) -> None:
         """
+        When --should-declare-assert-error-if-assert-statement-exists is True:
+
         It should pass.
 
         :raises AssertionError: every time, with a message.
@@ -213,6 +217,8 @@ def func18(self) -> None:
 
     def func19(self) -> None:
         """
+        When --should-declare-assert-error-if-assert-statement-exists is True:
+
         Should fail, expects `AssertionError`.
 
         :return: None
@@ -222,6 +228,8 @@ def func19(self) -> None:
 
     def func20(self) -> None:
         """
+        When --should-declare-assert-error-if-assert-statement-exists is True:
+
         It should pass.
 
         :raises AssertionError123: every time, with a message.
diff --git a/tests/test_baseline.py b/tests/test_baseline.py
diff --git a/tests/test_main.py b/tests/test_main.py
diff --git a/tests/utils/test_returns_yields_raise.py b/tests/utils/test_returns_yields_raise.py
