sarj-python-lint 1.67.0__tar.gz → 1.68.0__tar.gz

{sarj_python_lint-1.67.0 → sarj_python_lint-1.68.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sarj-python-lint
-Version: 1.67.0
+Version: 1.68.0
 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.67.0 → sarj_python_lint-1.68.0}/pyproject.toml

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

sarj_python_lint-1.68.0/src/sarj_python_lint/rules/_declared_contracts.py

@@ -0,0 +1,243 @@
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from sarj_python_lint.rules._annotation_semantics import AnnotationSemantics
+from sarj_python_lint.rules._imports import ImportIndex
+from sarj_python_lint.rules._project_index import ProjectIndexSet, SourceUnit, SymbolRef
+
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from sarj_python_lint._file_context import PythonFileContext
+
+
+MODEL_BASES = frozenset({"pydantic.BaseModel", "pydantic.main.BaseModel"})
+SETTINGS_BASES = frozenset({"pydantic_settings.BaseSettings", "pydantic_settings.main.BaseSettings"})
+_MAX_DEPTH = 8
+_TYPING_SOURCES = frozenset({"typing", "typing_extensions"})
+
+
+@dataclass(frozen=True)
+class DeclaredClass:
+    unit: SourceUnit
+    declaration: ast.ClassDef
+
+
+def _class_metadata_annotation(annotation: ast.expr, semantics: AnnotationSemantics) -> bool:
+    pending = [annotation]
+    seen: set[str] = set()
+    while pending:
+        node = semantics.parse(pending.pop())
+        if node is None:
+            return True
+        for member in ast.walk(node):
+            if isinstance(member, ast.Subscript) and semantics.imports.resolved_symbol(
+                member.value, sources=_TYPING_SOURCES
+            ) in {"ClassVar", "Final"}:
+                return True
+            if isinstance(member, ast.Name) and member.id in semantics.aliases and member.id not in seen:
+                seen.add(member.id)
+                pending.append(semantics.aliases[member.id])
+    return False
+
+
+class DeclaredContracts:
+    def __init__(self, context: PythonFileContext) -> None:
+        self.context = context
+        self._field_cache: dict[ast.ClassDef, dict[str, ast.AnnAssign]] = {}
+        self._module_annotations: dict[Path, AnnotationSemantics] = {}
+        self.project = context.session.project or ProjectIndexSet.single(context.path, context.source)
+        self.unit = self.project.unit(context.path)
+        if self.unit is not None and self.unit.tree is not context.tree:
+            self.unit = SourceUnit(self.unit.path, self.unit.module, self.unit.source, context.tree, self.unit.imports)
+            self.project = self.project.with_unit(self.unit)
+        if self.unit is not None and self.unit.module is None:
+            self.unit = SourceUnit(
+                context.path,
+                "__snippet__",
+                context.source,
+                context.tree,
+                {
+                    name: SymbolRef(target.module, target.symbol or "")
+                    for name, target in context.module_imports.bindings.items()
+                },
+            )
+            self.project = self.project.with_unit(self.unit)
+
+    def class_type(
+        self, expression: ast.expr, unit: SourceUnit | None = None, *, at: ast.AST | None = None
+    ) -> DeclaredClass | None:
+        owner = unit or self.unit
+        if owner is None or not self._lookup_allowed(expression, owner, at):
+            return None
+        summary = self.project.class_for(owner, expression)
+        source = self.project.source_unit(summary.symbol.module) if summary is not None else None
+        if source is None or source.tree is None or summary is None:
+            return None
+        declaration = self._stable_declaration(source, summary.symbol.name)
+        return DeclaredClass(source, declaration) if declaration is not None else None
+
+    def _lookup_allowed(self, expression: ast.expr, owner: SourceUnit, at: ast.AST | None) -> bool:
+        if owner is not self.unit or (at or expression) not in self.context.parents:
+            return True
+        root = expression
+        while isinstance(root, ast.Attribute):
+            root = root.value
+        if not isinstance(root, ast.Name):
+            return True
+        binding = self.context.static_resource_provenance.binding(root.id, at or expression)
+        return (
+            isinstance(binding, ast.alias | ast.ClassDef)
+            and root.id not in self.context.static_resource_provenance.mutated
+        )
+
+    def _stable_declaration(self, source: SourceUnit, name: str) -> ast.ClassDef | None:
+        if source.tree is None:
+            return None
+        declarations = [node for node in source.tree.body if isinstance(node, ast.ClassDef) and node.name == name]
+        if len(declarations) != 1 or declarations[0].keywords:
+            return None
+        if not self._identity_decorators(source, declarations[0]):
+            return None
+        if any(
+            isinstance(node, ast.Name) and node.id == name and isinstance(node.ctx, ast.Store | ast.Del)
+            for statement in source.tree.body
+            if not isinstance(statement, ast.ClassDef | ast.FunctionDef | ast.AsyncFunctionDef)
+            for node in ast.walk(statement)
+        ):
+            return None
+        return declarations[0]
+
+    def _identity_decorators(self, source: SourceUnit, declaration: ast.ClassDef) -> bool:
+        if not declaration.decorator_list:
+            return True
+        if source.tree is None:
+            return False
+        imports = (
+            self.context.module_imports
+            if source.path == self.context.path
+            else ImportIndex.from_tree(source.tree, module_scope_only=True)
+        )
+        return all(
+            imports.resolves(decorator, sources=_TYPING_SOURCES, symbol="final")
+            for decorator in declaration.decorator_list
+        )
+
+    def inherits(self, model: DeclaredClass, bases: frozenset[str]) -> bool:
+        return self.project.class_inherits_from(model.unit, model.declaration.name, bases)
+
+    def model_fields(self, model: DeclaredClass) -> dict[str, ast.AnnAssign]:
+        if model.unit.tree is None:
+            return {}
+        cached = self._field_cache.get(model.declaration)
+        if cached is not None:
+            return cached
+        semantics = self._module_semantics(model.unit)
+        fields = {
+            node.target.id: node
+            for node in model.declaration.body
+            if isinstance(node, ast.AnnAssign)
+            and isinstance(node.target, ast.Name)
+            and not node.target.id.startswith("_")
+            and node.target.id != "model_config"
+            and not _class_metadata_annotation(node.annotation, semantics)
+        }
+        self._field_cache[model.declaration] = fields
+        return fields
+
+    def _module_semantics(self, unit: SourceUnit) -> AnnotationSemantics:
+        if unit.tree is None:
+            return self.context.annotation_semantics
+        semantics = self._module_annotations.get(unit.path)
+        if semantics is None:
+            imports = (
+                self.context.module_imports
+                if unit.path == self.context.path
+                else ImportIndex.from_tree(unit.tree, module_scope_only=True)
+            )
+            semantics = AnnotationSemantics.from_imports(unit.tree, imports)
+            self._module_annotations[unit.path] = semantics
+        return semantics
+
+    def annotation(self, expression: ast.expr, unit: SourceUnit | None = None) -> DeclaredClass | None:
+        semantics = self.context.annotation_semantics
+        if unit is not None and unit is not self.unit and unit.tree is not None:
+            semantics = self._module_semantics(unit)
+        candidates = [
+            model
+            for member in semantics.transparent_members(expression)
+            if (model := self.class_type(member, unit, at=expression)) is not None
+        ]
+        return candidates[0] if len(candidates) == 1 else None
+
+    def value(self, expression: ast.expr, *, depth: int = 0) -> DeclaredClass | None:
+        if depth > _MAX_DEPTH:
+            return None
+        match expression:
+            case ast.Await():
+                return self.value(expression.value, depth=depth + 1)
+            case ast.Name():
+                return self._local_value(expression, depth)
+            case ast.Call():
+                return self.class_type(expression.func) or self._call_result(expression, depth)
+            case _:
+                return None
+
+    def _local_value(self, expression: ast.Name, depth: int) -> DeclaredClass | None:
+        binding = self.context.static_resource_provenance.binding(expression.id, expression)
+        if isinstance(binding, ast.arg) and binding.annotation is not None:
+            return self.annotation(binding.annotation)
+        parent = self.context.parents.get(binding) if binding is not None else None
+        if isinstance(parent, ast.AnnAssign):
+            return self.annotation(parent.annotation)
+        if isinstance(binding, ast.Name):
+            value = self.context.static_resource_provenance.assignment_value(binding, expression)
+            return self.value(value, depth=depth + 1) if value is not None else None
+        return None
+
+    def _call_result(self, expression: ast.Call, depth: int) -> DeclaredClass | None:
+        match expression.func:
+            case ast.Name():
+                binding = self.context.static_resource_provenance.binding(expression.func.id, expression)
+                if isinstance(binding, ast.FunctionDef | ast.AsyncFunctionDef) and binding.returns is not None:
+                    return self.annotation(binding.returns)
+                return None
+            case ast.Attribute():
+                return self._method_result(expression.func, depth)
+            case _:
+                return None
+
+    def _method_result(self, target: ast.Attribute, depth: int) -> DeclaredClass | None:
+        model = self.class_type(target.value) or self.value(target.value, depth=depth + 1)
+        if model is None:
+            return None
+        if target.attr in {"model_validate", "model_validate_json", "model_copy"} and self.inherits(
+            model, MODEL_BASES | SETTINGS_BASES
+        ):
+            return model
+        methods = [
+            node
+            for node in model.declaration.body
+            if isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef) and node.name == target.attr
+        ]
+        if len(methods) == 1 and methods[0].returns is not None and not methods[0].decorator_list:
+            return self.annotation(methods[0].returns, model.unit)
+        return None
+
+
+def ordinary_pytest_test(function: ast.FunctionDef | ast.AsyncFunctionDef, context: PythonFileContext) -> bool:
+    if not function.name.startswith("test_"):
+        return False
+    owner = context.parents.get(function)
+    if isinstance(owner, ast.ClassDef) and (owner.bases or owner.decorator_list or owner.keywords):
+        return False
+    for decorator in function.decorator_list:
+        target = decorator.func if isinstance(decorator, ast.Call) else decorator
+        qualified = context.imports.resolved_qualified_name(target)
+        if qualified is None or not qualified.startswith("pytest.mark."):
+            return False
+    return True

{sarj_python_lint-1.67.0 → sarj_python_lint-1.68.0}/src/sarj_python_lint/rules/_registry.py

@@ -237,8 +237,13 @@ from sarj_python_lint.rules.no_slash_collection_root_under_prefix import NoSlash
 from sarj_python_lint.rules.no_unknown_pydantic_validator_field import NoUnknownPydanticValidatorField
 from sarj_python_lint.rules.no_work_verb_get_route import NoWorkVerbGetRoute
 from sarj_python_lint.rules.prefer_bulk_upsert import PreferBulkUpsert
+from sarj_python_lint.rules.prefer_direct_import_module import PreferDirectImportModule
 from sarj_python_lint.rules.prefer_discriminated_model_union import PreferDiscriminatedModelUnion
+from sarj_python_lint.rules.prefer_precise_object_contract import PreferPreciseObjectContract
 from sarj_python_lint.rules.prefer_psycopg_executemany import PreferPsycopgExecutemany
+from sarj_python_lint.rules.prefer_pydantic_model_assertion import PreferPydanticModelAssertion
+from sarj_python_lint.rules.prefer_pytest_dependency_fixtures import PreferPytestDependencyFixtures
+from sarj_python_lint.rules.prefer_typed_settings_field import PreferTypedSettingsField
 from sarj_python_lint.rules.pytest_fixture_returns_closed_resource import PytestFixtureReturnsClosedResource
 from sarj_python_lint.rules.redundant_test_constructor_forwarder import RedundantTestConstructorForwarder
 from sarj_python_lint.rules.repeated_unimplemented_test_contract import RepeatedUnimplementedTestContract
@@ -251,6 +256,11 @@ REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
     {
         PytestFixtureReturnsClosedResource.id: PytestFixtureReturnsClosedResource,
         DuplicatePytestFixtureParams.id: DuplicatePytestFixtureParams,
+        PreferTypedSettingsField.id: PreferTypedSettingsField,
+        PreferDirectImportModule.id: PreferDirectImportModule,
+        PreferPreciseObjectContract.id: PreferPreciseObjectContract,
+        PreferPydanticModelAssertion.id: PreferPydanticModelAssertion,
+        PreferPytestDependencyFixtures.id: PreferPytestDependencyFixtures,
         PreferBulkUpsert.id: PreferBulkUpsert,
         PreferPsycopgExecutemany.id: PreferPsycopgExecutemany,
         StoreFieldUpdateReusesUpsert.id: StoreFieldUpdateReusesUpsert,

{sarj_python_lint-1.67.0 → sarj_python_lint-1.68.0}/src/sarj_python_lint/rules/_test_composition.py

@@ -65,7 +65,13 @@ def _class_owner(
     return unit, owner
 
 
-def constructor(context: PythonFileContext, expression: ast.expr, project: ProjectIndexSet) -> Constructor | None:
+def constructor(
+    context: PythonFileContext,
+    expression: ast.expr,
+    project: ProjectIndexSet,
+    *,
+    minimum_collaborators: int = _MIN_COLLABORATORS,
+) -> Constructor | None:
     resolved = _class_owner(context, expression, project)
     if resolved is None:
         return None
@@ -87,7 +93,7 @@ def constructor(context: PythonFileContext, expression: ast.expr, project: Proje
         and _is_port(project, unit, parameter.annotation)
         and stored.get(parameter.arg) in invoked
     )
-    if len(collaborators) < _MIN_COLLABORATORS:
+    if len(collaborators) < minimum_collaborators:
         return None
     return Constructor(
         SymbolRef(unit.module, owner.name),

{sarj_python_lint-1.67.0 → sarj_python_lint-1.68.0}/src/sarj_python_lint/rules/excessive_commentary.py

@@ -14,8 +14,10 @@ from sarj_python_lint.rule_base import (
     RuleCategory,
     RuleDocumentation,
     RuleExample,
+    Severity,
 )
 from sarj_python_lint.rules._ast_index import walk as walk_ast
+from sarj_python_lint.rules._comments import has_external_reference
 from sarj_python_lint.rules._prose_budget import (
     groups,
     has_technical_anchor,
@@ -27,8 +29,10 @@ if TYPE_CHECKING:
     from sarj_python_lint.rules._ast_index import NodeIndex
 
 
-_MIN_LINES = 4
-_MIN_WORDS = 28
+_MIN_LINES = 3
+_MIN_WORDS = 20
+_ERROR_MIN_LINES = 4
+_ERROR_MIN_WORDS = 28
 _RATIONALE_RE = re.compile(
     r"\b(?:because|otherwise|therefore|must|never|cannot|can't|required?|invariant|"
     r"compatibility|security|race|atomic|deadlock|rollback|lock|data loss)\b",
@@ -45,21 +49,24 @@ class ExcessiveCommentary(Rule):
     id = "excessive-commentary"
     code = "SARJ434"
     documentation = RuleDocumentation(
-        summary="Long standalone implementation commentary — make the code self-documenting and retain only durable constraints.",
+        summary="Review long implementation comments; express behavior through code and keep constraints concise.",
         rationale=(
             "A paragraph that narrates nearby implementation behavior competes with the code and can drift independently "
             "from it."
         ),
         remediation=(
-            "Delete the narration and clarify names, types, or structure. Keep concise comments that record a durable "
-            "constraint or externally owned contract."
+            "Make behavior clear through names, types, validators and cohesive functions. Shorten remaining explanation "
+            "to a concise constraint or protocol reference. Keep necessary detail with an explained exact-code "
+            "exception; never delete a required constraint or create abstraction solely to satisfy this warning."
         ),
         category=RuleCategory.MAINTAINABILITY,
         autofix=AutofixPolicy.NONE,
         limitations=(
-            "Only contiguous standalone line-comment blocks with at least four non-empty lines and 28 words are inspected.",
-            "The paragraph must immediately precede an empty local collection that is then populated by at least two consecutive accumulator calls.",
-            "Generated files, directives, licenses, structured lists, docstrings, inline comments, rationale markers, and concrete technical anchors are excluded.",
+            "Contiguous standalone implementation comment blocks with at least three non-empty lines and 20 words are inspected.",
+            "The paragraph must immediately precede executable implementation code; narrative comments in tests and module setup are included.",
+            "The previously shipped accumulator pattern remains an error; expanded implementation commentary is a warning requiring review, with no automatic deletion.",
+            "Rationale, technical vocabulary and external citations do not exempt a long paragraph from warning-level review. Their existing protection against accumulator errors remains intact.",
+            "Generated files, directives, licenses, structured lists, docstrings, inline comments and short constraints are excluded.",
         ),
         examples=(
             RuleExample(
@@ -111,24 +118,31 @@ class ExcessiveCommentary(Rule):
         tree = context.tree
         if tree is None:
             return []
+        implementation_lines = {
+            node.lineno
+            for node in context.nodes(ast.stmt)
+            if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef, ast.Import, ast.ImportFrom))
+        }
         accumulator_lines = _narrated_accumulator_lines(tree, node_index=context.node_index)
         findings: list[Diagnostic] = []
         for group in groups(path, source):
             lines = tuple(stripped for line in group.text.splitlines() if (stripped := line.strip()))
-            if group.kind != "comment" or len(lines) < _MIN_LINES or len(group.text.split()) < _MIN_WORDS:
+            words = len(group.text.split())
+            if group.kind != "comment" or len(lines) < _MIN_LINES or words < _MIN_WORDS:
                 continue
             comment_end_line = group.line + len(group.text.splitlines()) - 1
-            if comment_end_line + 1 not in accumulator_lines:
+            if comment_end_line + 1 not in implementation_lines:
                 continue
-            if any(
+            if _BULLET_RE.search(group.text):
+                continue
+            review_only = any(
                 (
-                    _BULLET_RE.search(group.text),
                     has_technical_anchor(group.text),
+                    has_external_reference(group.text),
                     _RATIONALE_RE.search(group.text),
                     _RATIONALE_SO_RE.search(group.text),
                 )
-            ):
-                continue
+            )
             findings.append(
                 Diagnostic(
                     path,
@@ -136,6 +150,14 @@ class ExcessiveCommentary(Rule):
                     group.col,
                     self.code,
                     self.description,
+                    severity=(
+                        Severity.ERROR
+                        if not review_only
+                        and comment_end_line + 1 in accumulator_lines
+                        and len(lines) >= _ERROR_MIN_LINES
+                        and words >= _ERROR_MIN_WORDS
+                        else Severity.WARNING
+                    ),
                     column_encoding=group.column_encoding,
                 )
             )

sarj_python_lint-1.68.0/src/sarj_python_lint/rules/prefer_direct_import_module.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+import ast
+from pathlib import PurePosixPath
+from typing import TYPE_CHECKING, final, override
+
+from sarj_python_lint.rule_base import (
+    AutofixPolicy,
+    Diagnostic,
+    ExampleFile,
+    ExampleOutcome,
+    Rule,
+    RuleCategory,
+    RuleDocumentation,
+    RuleExample,
+    Severity,
+)
+
+
+if TYPE_CHECKING:
+    from sarj_python_lint._file_context import PythonFileContext
+
+
+@final
+class PreferDirectImportModule(Rule):
+    id = "prefer-direct-import-module"
+    code = "SARJ529"
+    documentation = RuleDocumentation(
+        default_level=Severity.WARNING,
+        summary="Import import_module directly instead of accessing importlib.import_module.",
+        rationale="A focused import makes the loader dependency explicit and removes repeated module qualification.",
+        remediation="Use 'from importlib import import_module' and annotate importer callables with 'Callable[[str], ModuleType]'. Keep intentional module patching behind an explained local exception.",
+        category=RuleCategory.STYLE,
+        autofix=AutofixPolicy.NONE,
+        limitations=(
+            "Only provenance-resolved importlib.import_module attribute reads are checked. Other importlib APIs, direct imports, shadowed or mutated namespaces and generated code are preserved. No automatic rewrite because changing the lookup can change monkeypatch behavior.",
+        ),
+        examples=(
+            RuleExample(
+                example_id="qualified-loader",
+                title="The module loader is qualified at each use",
+                outcome=ExampleOutcome.MATCH,
+                files=(ExampleFile.python("app.py", "import importlib\nloader = importlib.import_module\n"),),
+                focus_path=PurePosixPath("app.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="focused-loader",
+                title="Import only the loader",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(ExampleFile.python("app.py", "from importlib import import_module\nloader = import_module\n"),),
+                focus_path=PurePosixPath("app.py"),
+                expected_count=0,
+                public=True,
+            ),
+        ),
+    )
+    description = documentation.summary
+
+    @override
+    def check_context(self, context: PythonFileContext) -> list[Diagnostic]:
+        if context.generated or context.tree is None or "import_module" not in context.symbol_source:
+            return []
+        provenance = context.static_resource_provenance
+        return [
+            Diagnostic(
+                context.path,
+                node.lineno,
+                node.col_offset + 1,
+                self.code,
+                "Use 'from importlib import import_module' and call 'import_module(...)' directly.",
+                severity=Severity.WARNING,
+            )
+            for node in context.nodes(ast.Attribute)
+            if node.attr == "import_module"
+            and isinstance(node.ctx, ast.Load)
+            and context.imports.resolved_qualified_name(node) == "importlib.import_module"
+            and isinstance(node.value, ast.Name)
+            and isinstance(provenance.binding(node.value.id, node), ast.alias)
+            and node.value.id not in provenance.mutated
+            and not provenance.wildcard
+        ]

{sarj_python_lint-1.67.0 → sarj_python_lint-1.68.0}/src/sarj_python_lint/rules/prefer_namedtuple_over_tuple_return.py

@@ -54,7 +54,8 @@ class PreferNamedtupleOverTupleReturn(Rule):
         aliases=("prefer-namedtuple-over-tuple-return",),
         limitations=(
             "Generated files and documentation examples are excluded.",
-            "Explicit provenance-resolved builtin or typing fixed tuple return annotations with at least two slots are reported; variadic tuples remain valid collections.",
+            "Provenance-resolved builtin or typing fixed tuple return annotations with at least two slots are reported, including stable local aliases, quoted annotations, Annotated wrappers and optional unions in test helpers and fixtures; variadic tuples remain valid collections.",
+            "Existing direct tuple records remain errors; newly resolved local aliases and optional-union records start as warnings for adoption review.",
             "Classes with explicit bases, including object, are excluded without requiring an override decorator. Local base declarations do not prove runtime member ownership remains closed; class construction, native hooks and escaped handles can change inheritance. Independent module functions and plain classes remain eligible.",
         ),
         examples=(
@@ -109,7 +110,10 @@ class PreferNamedtupleOverTupleReturn(Rule):
         for node in context.nodes(ast.AST):
             if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)) or node.returns is None:
                 continue
-            if not _is_public_record_tuple(node.returns, imports):
+            if not any(
+                _is_public_record_tuple(member, imports)
+                for member in context.annotation_semantics.transparent_members(node.returns)
+            ):
                 continue
             if inherited_contract(context.parents.get(node)):
                 continue
@@ -120,7 +124,7 @@ class PreferNamedtupleOverTupleReturn(Rule):
                     col=node.col_offset + 1,
                     code=self.code,
                     message=_MSG,
-                    severity=Severity.ERROR,
+                    severity=Severity.ERROR if _is_public_record_tuple(node.returns, imports) else Severity.WARNING,
                 )
             )
         return diagnostics