sarj-python-lint 1.28.3__tar.gz → 1.28.4__tar.gz

{sarj_python_lint-1.28.3 → sarj_python_lint-1.28.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sarj-python-lint
-Version: 1.28.3
+Version: 1.28.4
 Summary: Custom Python lint rules — AST-based, pre-commit-friendly, hypermodern defaults
 Project-URL: Homepage, https://code-standards.sarj.ai/rules/python/
 Project-URL: Documentation, https://code-standards.sarj.ai/rules/python/

{sarj_python_lint-1.28.3 → sarj_python_lint-1.28.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sarj-python-lint"
-version = "1.28.3"
+version = "1.28.4"
 description = "Custom Python lint rules — AST-based, pre-commit-friendly, hypermodern defaults"
 readme = "README.md"
 authors = [{ name = "sarj-ai" }]

{sarj_python_lint-1.28.3 → sarj_python_lint-1.28.4}/src/sarj_python_lint/_file_context.py

@@ -61,6 +61,12 @@ class PythonFileContext:
     def has_wildcard_import(self) -> bool:
         return any(alias.name == "*" for node in self.nodes(ast.ImportFrom) for alias in node.names)
 
+    @cached_property
+    def consumed_docstring_names(self) -> frozenset[str]:
+        from sarj_python_lint.rules._docstrings import consumed_docstring_names  # ruff: ignore[import-outside-top-level] -- share runtime docstring analysis only when requested.
+
+        return consumed_docstring_names(self._valid_tree(), node_index=self.node_index)
+
     @property
     def parents(self) -> Mapping[ast.AST, ast.AST]:
         return self.node_index.parents

{sarj_python_lint-1.28.3 → sarj_python_lint-1.28.4}/src/sarj_python_lint/rules/_docstrings.py

@@ -5,12 +5,17 @@ from itertools import starmap
 import re
 from typing import TYPE_CHECKING, NamedTuple
 
+from sarj_python_lint.rules._ast_index import walk as walk_ast
 from sarj_python_lint.rules._comments import split_identifier, stem
 
 
 if TYPE_CHECKING:
     from collections.abc import Iterable
 
+    from sarj_python_lint.rules._ast_index import NodeIndex
+
+
+_GETATTR_MIN_ARGS = 2
 
 # Docstring filler that says nothing about *which* thing is being described.
 _BASE_STOPWORDS = frozenset(
@@ -325,3 +330,88 @@ def restates(text: str, known: Iterable[str]) -> bool:
     if not content:
         return False
     return all(stem(word) in known_stems for word in content)
+
+
+def consumed_docstring_names(tree: ast.Module, *, node_index: NodeIndex | None = None) -> frozenset[str]:
+    consumed: set[str] = set()
+    aliases: dict[str, set[str]] = {}
+    for node in walk_ast(tree, index=node_index):
+        _record_docstring_use(node, consumed, aliases)
+    changed = True
+    while changed:
+        changed = False
+        for alias, originals in aliases.items():
+            if alias not in consumed:
+                continue
+            before = len(consumed)
+            consumed.update(originals)
+            changed |= len(consumed) != before
+    return frozenset(consumed)
+
+
+def _terminal_name(node: ast.expr) -> str | None:
+    match node:
+        case ast.Name():
+            return node.id
+        case ast.Attribute():
+            return node.attr
+        case _:
+            return None
+
+
+def _record_docstring_use(node: ast.AST, consumed: set[str], aliases: dict[str, set[str]]) -> None:
+    if isinstance(node, ast.Attribute) and node.attr == "__doc__":
+        if name := _terminal_name(node.value):
+            consumed.add(name)
+    elif isinstance(node, ast.Call) and _is_docstring_reader(node):
+        if name := _terminal_name(node.args[0]):
+            consumed.add(name)
+    elif isinstance(node, ast.Subscript):
+        if name := _subscripted_docstring_owner(node):
+            consumed.add(name)
+    else:
+        _record_docstring_alias(node, aliases)
+
+
+def _subscripted_docstring_owner(node: ast.Subscript) -> str | None:
+    if not isinstance(node.slice, ast.Constant) or node.slice.value != "__doc__":
+        return None
+    value = node.value
+    if isinstance(value, ast.Attribute) and value.attr == "__dict__":
+        return _terminal_name(value.value)
+    if isinstance(value, ast.Call) and isinstance(value.func, ast.Name) and value.func.id == "vars" and value.args:
+        return _terminal_name(value.args[0])
+    return None
+
+
+def _is_docstring_reader(node: ast.Call) -> bool:
+    if not node.args:
+        return False
+    function = node.func
+    if isinstance(function, ast.Name) and function.id == "help":
+        return True
+    if isinstance(function, ast.Attribute) and function.attr in {"getdoc", "render_doc"}:
+        return True
+    return (
+        isinstance(function, ast.Name)
+        and function.id == "getattr"
+        and len(node.args) >= _GETATTR_MIN_ARGS
+        and isinstance(node.args[1], ast.Constant)
+        and node.args[1].value == "__doc__"
+    )
+
+
+def _record_docstring_alias(node: ast.AST, aliases: dict[str, set[str]]) -> None:
+    if isinstance(node, ast.Assign) and isinstance(node.value, (ast.Name, ast.Attribute)):
+        original = _terminal_name(node.value)
+        for target in node.targets:
+            if isinstance(target, ast.Name) and original is not None:
+                aliases.setdefault(target.id, set()).add(original)
+    elif (
+        isinstance(node, ast.AnnAssign)
+        and isinstance(node.target, ast.Name)
+        and isinstance(node.value, (ast.Name, ast.Attribute))
+    ):
+        original = _terminal_name(node.value)
+        if original is not None:
+            aliases.setdefault(node.target.id, set()).add(original)

{sarj_python_lint-1.28.3 → sarj_python_lint-1.28.4}/src/sarj_python_lint/rules/redundant_class_docstring.py

@@ -17,7 +17,6 @@ from sarj_python_lint.rule_base import (
     Severity,
     is_suppressed,
 )
-from sarj_python_lint.rules._ast_index import walk as walk_ast
 from sarj_python_lint.rules._comments import is_protected, stem
 from sarj_python_lint.rules._docstrings import (
     VALUE_MARKER_RE,
@@ -27,11 +26,9 @@ from sarj_python_lint.rules._docstrings import (
 
 if TYPE_CHECKING:
     from sarj_python_lint._file_context import PythonFileContext
-    from sarj_python_lint.rules._ast_index import NodeIndex
 
 
 _GRAMMATICAL_FILLER = frozenset({"a", "an", "class", "the"})
-_GETATTR_MIN_ARGS = 2
 _DOCSTRING_TOKEN_RE = re.compile(r"[^\W\d_]+(?:'[^\W\d_]+)?|\d+")
 
 
@@ -93,7 +90,7 @@ class RedundantClassDocstring(Rule):
         if tree is None:
             return []
         source_lines = context.source_lines
-        consumed_docstrings = _consumed_docstring_names(tree, node_index=context.node_index)
+        consumed_docstrings = context.consumed_docstring_names
         diags: list[Diagnostic] = []
         for node in context.nodes(ast.ClassDef):
             if node.name not in consumed_docstrings and self._is_ceremony(node):
@@ -128,88 +125,3 @@ class RedundantClassDocstring(Rule):
             if (word := match.group(0).lower()) not in _GRAMMATICAL_FILLER
         ]
         return bool(content) and all(stem(word) in known for word in content)
-
-
-def _consumed_docstring_names(tree: ast.Module, *, node_index: NodeIndex | None = None) -> set[str]:
-    consumed: set[str] = set()
-    aliases: dict[str, set[str]] = {}
-    for node in walk_ast(tree, index=node_index):
-        _record_docstring_use(node, consumed, aliases)
-    changed = True
-    while changed:
-        changed = False
-        for alias, originals in aliases.items():
-            if alias not in consumed:
-                continue
-            before = len(consumed)
-            consumed.update(originals)
-            changed |= len(consumed) != before
-    return consumed
-
-
-def _terminal_name(node: ast.expr) -> str | None:
-    match node:
-        case ast.Name():
-            return node.id
-        case ast.Attribute():
-            return node.attr
-        case _:
-            return None
-
-
-def _record_docstring_use(node: ast.AST, consumed: set[str], aliases: dict[str, set[str]]) -> None:
-    if isinstance(node, ast.Attribute) and node.attr == "__doc__":
-        if name := _terminal_name(node.value):
-            consumed.add(name)
-    elif isinstance(node, ast.Call) and _is_docstring_reader(node):
-        if name := _terminal_name(node.args[0]):
-            consumed.add(name)
-    elif isinstance(node, ast.Subscript):
-        if name := _subscripted_docstring_owner(node):
-            consumed.add(name)
-    else:
-        _record_docstring_alias(node, aliases)
-
-
-def _subscripted_docstring_owner(node: ast.Subscript) -> str | None:
-    if not isinstance(node.slice, ast.Constant) or node.slice.value != "__doc__":
-        return None
-    value = node.value
-    if isinstance(value, ast.Attribute) and value.attr == "__dict__":
-        return _terminal_name(value.value)
-    if isinstance(value, ast.Call) and isinstance(value.func, ast.Name) and value.func.id == "vars" and value.args:
-        return _terminal_name(value.args[0])
-    return None
-
-
-def _is_docstring_reader(node: ast.Call) -> bool:
-    if not node.args:
-        return False
-    function = node.func
-    if isinstance(function, ast.Name) and function.id == "help":
-        return True
-    if isinstance(function, ast.Attribute) and function.attr in {"getdoc", "render_doc"}:
-        return True
-    return (
-        isinstance(function, ast.Name)
-        and function.id == "getattr"
-        and len(node.args) >= _GETATTR_MIN_ARGS
-        and isinstance(node.args[1], ast.Constant)
-        and node.args[1].value == "__doc__"
-    )
-
-
-def _record_docstring_alias(node: ast.AST, aliases: dict[str, set[str]]) -> None:
-    if isinstance(node, ast.Assign) and isinstance(node.value, (ast.Name, ast.Attribute)):
-        original = _terminal_name(node.value)
-        for target in node.targets:
-            if isinstance(target, ast.Name) and original is not None:
-                aliases.setdefault(target.id, set()).add(original)
-    elif (
-        isinstance(node, ast.AnnAssign)
-        and isinstance(node.target, ast.Name)
-        and isinstance(node.value, (ast.Name, ast.Attribute))
-    ):
-        original = _terminal_name(node.value)
-        if original is not None:
-            aliases.setdefault(node.target.id, set()).add(original)

{sarj_python_lint-1.28.3 → sarj_python_lint-1.28.4}/src/sarj_python_lint/rules/redundant_docstring.py

@@ -18,7 +18,7 @@ from sarj_python_lint.rule_base import (
     Severity,
     is_suppressed,
 )
-from sarj_python_lint.rules._ast_index import children, walk as walk_ast
+from sarj_python_lint.rules._ast_index import children
 from sarj_python_lint.rules._comments import is_protected, split_identifier, stem
 from sarj_python_lint.rules._docstrings import (
     VALUE_MARKER_RE,
@@ -28,12 +28,10 @@ from sarj_python_lint.rules._docstrings import (
 
 if TYPE_CHECKING:
     from sarj_python_lint._file_context import PythonFileContext
-    from sarj_python_lint.rules._ast_index import NodeIndex
 
 
 _DOCSTRING_TOKEN_RE = re.compile(r"[^\W\d_]+(?:'[^\W\d_]+)?|\d+")
 _GRAMMATICAL_FILLER = frozenset({"a", "an", "function", "method", "the"})
-_GETATTR_MIN_ARGS = 2
 _MULTI_PARAMETER_MIN = 2
 
 
@@ -41,7 +39,7 @@ _MULTI_PARAMETER_MIN = 2
 class _ScanContext:
     path: Path
     source_lines: list[str]
-    consumed_docstrings: set[str]
+    consumed_docstrings: frozenset[str]
     diagnostics: list[Diagnostic]
 
 
@@ -105,7 +103,7 @@ class RedundantDocstring(Rule):
         if tree is None:
             return []
         source_lines = context.source_lines
-        consumed_docstrings = _consumed_docstring_names(tree, node_index=context.node_index)
+        consumed_docstrings = context.consumed_docstring_names
         diags: list[Diagnostic] = []
         analysis_context = _ScanContext(path, source_lines, consumed_docstrings, diags)
         self._walk(tree, analysis_context)
@@ -190,88 +188,3 @@ def _parameters_are_distinguished(groups: list[set[str]], content: set[str]) ->
         if not distinguishing or distinguishing.isdisjoint(content):
             return False
     return True
-
-
-def _consumed_docstring_names(tree: ast.Module, *, node_index: NodeIndex | None = None) -> set[str]:
-    consumed: set[str] = set()
-    aliases: dict[str, set[str]] = {}
-    for node in walk_ast(tree, index=node_index):
-        _record_docstring_use(node, consumed, aliases)
-    changed = True
-    while changed:
-        changed = False
-        for alias, originals in aliases.items():
-            if alias not in consumed:
-                continue
-            before = len(consumed)
-            consumed.update(originals)
-            changed |= len(consumed) != before
-    return consumed
-
-
-def _terminal_name(node: ast.expr) -> str | None:
-    match node:
-        case ast.Name():
-            return node.id
-        case ast.Attribute():
-            return node.attr
-        case _:
-            return None
-
-
-def _record_docstring_use(node: ast.AST, consumed: set[str], aliases: dict[str, set[str]]) -> None:
-    if isinstance(node, ast.Attribute) and node.attr == "__doc__":
-        if name := _terminal_name(node.value):
-            consumed.add(name)
-    elif isinstance(node, ast.Call) and _is_docstring_reader(node):
-        if name := _terminal_name(node.args[0]):
-            consumed.add(name)
-    elif isinstance(node, ast.Subscript):
-        if name := _subscripted_docstring_owner(node):
-            consumed.add(name)
-    else:
-        _record_docstring_alias(node, aliases)
-
-
-def _subscripted_docstring_owner(node: ast.Subscript) -> str | None:
-    if not isinstance(node.slice, ast.Constant) or node.slice.value != "__doc__":
-        return None
-    value = node.value
-    if isinstance(value, ast.Attribute) and value.attr == "__dict__":
-        return _terminal_name(value.value)
-    if isinstance(value, ast.Call) and isinstance(value.func, ast.Name) and value.func.id == "vars" and value.args:
-        return _terminal_name(value.args[0])
-    return None
-
-
-def _is_docstring_reader(node: ast.Call) -> bool:
-    if not node.args:
-        return False
-    function = node.func
-    if isinstance(function, ast.Name) and function.id == "help":
-        return True
-    if isinstance(function, ast.Attribute) and function.attr in {"getdoc", "render_doc"}:
-        return True
-    return (
-        isinstance(function, ast.Name)
-        and function.id == "getattr"
-        and len(node.args) >= _GETATTR_MIN_ARGS
-        and isinstance(node.args[1], ast.Constant)
-        and node.args[1].value == "__doc__"
-    )
-
-
-def _record_docstring_alias(node: ast.AST, aliases: dict[str, set[str]]) -> None:
-    if isinstance(node, ast.Assign) and isinstance(node.value, (ast.Name, ast.Attribute)):
-        original = _terminal_name(node.value)
-        for target in node.targets:
-            if isinstance(target, ast.Name) and original is not None:
-                aliases.setdefault(target.id, set()).add(original)
-    elif (
-        isinstance(node, ast.AnnAssign)
-        and isinstance(node.target, ast.Name)
-        and isinstance(node.value, (ast.Name, ast.Attribute))
-    ):
-        original = _terminal_name(node.value)
-        if original is not None:
-            aliases.setdefault(node.target.id, set()).add(original)