sarj-python-lint 1.31.0__tar.gz → 1.32.0__tar.gz

{sarj_python_lint-1.31.0 → sarj_python_lint-1.32.0}/PKG-INFO

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

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

{sarj_python_lint-1.31.0 → sarj_python_lint-1.32.0}/src/sarj_python_lint/_file_context.py

@@ -9,6 +9,7 @@ from sarj_python_lint._source import symbol_prefilter_source
 from sarj_python_lint.rules._ast_index import NodeIndex
 from sarj_python_lint.rules._fastapi import FastapiIndex
 from sarj_python_lint.rules._imports import ImportIndex
+from sarj_python_lint.rules._namespace_access import dynamic_namespace_access
 from sarj_python_lint.rules._paths import is_generated
 
 
@@ -90,6 +91,10 @@ class PythonFileContext:
     def module_imports(self) -> ImportIndex:
         return ImportIndex.from_tree(self._valid_tree(), module_scope_only=True)
 
+    @cached_property
+    def dynamic_namespace(self) -> bool:
+        return dynamic_namespace_access(self.nodes(ast.AST), self.imports, self.parents)
+
     @cached_property
     def fastapi(self) -> FastapiIndex:
         return FastapiIndex(self._valid_tree(), path=self.path)

{sarj_python_lint-1.31.0 → sarj_python_lint-1.32.0}/src/sarj_python_lint/_python_target.py

@@ -23,25 +23,38 @@ class PythonTargetFacts:
         self._projects: dict[Path, str | None] = {}
         self._installed: dict[Path, dict[Path, str | None]] = {}
         self._witnesses: dict[tuple[str, tuple[int, int]], bool] = {}
+        self._minimums: dict[tuple[str, tuple[int, int]], bool] = {}
 
     def has_declared_support_before(self, path: Path, minimum: tuple[int, int]) -> bool:
+        declaration = self._declared_target(path)
+        if not declaration:
+            return False
+        key = declaration, minimum
+        if key not in self._witnesses:
+            self._witnesses[key] = _has_legacy_witness(declaration, minimum)
+        return self._witnesses[key]
+
+    def has_declared_minimum(self, path: Path, minimum: tuple[int, int]) -> bool:
+        declaration = self._declared_target(path)
+        if not declaration:
+            return False
+        key = declaration, minimum
+        if key not in self._minimums:
+            self._minimums[key] = _proves_minimum(declaration, minimum)
+        return self._minimums[key]
+
+    def _declared_target(self, path: Path) -> str | None:
         try:
             absolute = path.absolute()
             resolved = path.resolve()
         except OSError, RuntimeError:
-            return False
+            return None
         if absolute not in self._declarations:
             try:
                 self._declarations[absolute] = self._declaration(absolute, resolved)
             except OSError, RuntimeError:
                 self._declarations[absolute] = None
-        declaration = self._declarations[absolute]
-        if not declaration:
-            return False
-        key = declaration, minimum
-        if key not in self._witnesses:
-            self._witnesses[key] = _has_legacy_witness(declaration, minimum)
-        return self._witnesses[key]
+        return self._declarations[absolute]
 
     def _declaration(self, absolute: Path, resolved: Path) -> str | None:
         ancestors = [*list(absolute.parents)[:_MAX_ANCESTORS], *list(resolved.parents)[:_MAX_ANCESTORS]]
@@ -142,3 +155,21 @@ def _has_legacy_witness(declaration: str, minimum: tuple[int, int]) -> bool:
         and specifiers.contains(candidate, prereleases=False)
         for candidate in candidates
     )
+
+
+def _proves_minimum(declaration: str, minimum: tuple[int, int]) -> bool:
+    try:
+        specifiers = SpecifierSet(declaration)
+    except InvalidSpecifier:
+        return False
+    threshold = Version(".".join(map(str, minimum)))
+    for specifier in specifiers:
+        if specifier.operator not in {">=", ">", "==", "~="}:
+            continue
+        try:
+            boundary = Version(specifier.version.removesuffix(".*"))
+        except InvalidVersion:
+            continue
+        if not boundary.epoch and boundary >= threshold:
+            return True
+    return False

sarj_python_lint-1.32.0/src/sarj_python_lint/rules/_closed_helpers.py

@@ -0,0 +1,185 @@
+from __future__ import annotations
+
+import ast
+from typing import TYPE_CHECKING
+
+from sarj_python_lint.rules._ast_index import nodes
+from sarj_python_lint.rules._pydantic_field_contract import (
+    inert_annotation,
+    inert_class_value,
+    inert_signature,
+    literal_value,
+)
+
+
+if TYPE_CHECKING:
+    from sarj_python_lint._file_context import PythonFileContext
+    from sarj_python_lint.rules._ast_index import NodeIndex
+    from sarj_python_lint.rules._resource_provenance import ResourceProvenance
+
+
+_DYNAMIC_NAMES = frozenset(
+    {"globals", "locals", "vars", "eval", "exec", "getattr", "setattr", "delattr", "__import__", "__all__"}
+)
+
+
+def dynamic_namespace(context: PythonFileContext) -> bool:
+    return (
+        context.dynamic_namespace
+        or any(node.id in _DYNAMIC_NAMES for node in context.nodes(ast.Name))
+        or any(node.attr in _DYNAMIC_NAMES | {"__dict__"} for node in context.nodes(ast.Attribute))
+        or any(node.name == "*" for node in context.nodes(ast.alias))
+    )
+
+
+def executable_body(function: ast.FunctionDef) -> list[ast.stmt]:
+    body = function.body
+    return (
+        body[1:]
+        if body
+        and isinstance(body[0], ast.Expr)
+        and isinstance(body[0].value, ast.Constant)
+        and isinstance(body[0].value.value, str)
+        else body
+    )
+
+
+def closed_references(
+    context: PythonFileContext, function: ast.FunctionDef, provenance: ResourceProvenance
+) -> list[ast.Name] | None:
+    if (
+        context.parents.get(function) is not context.tree
+        or not function.name.startswith("_")
+        or function.name.startswith("__")
+        or function.decorator_list
+        or function.type_params
+    ):
+        return None
+    if has_member_import(context.tree, function.name, node_index=context.node_index):
+        return None
+    if (
+        function.args.vararg is not None
+        or function.args.kwarg is not None
+        or dynamic_namespace(context)
+        or any(node.attr == function.name for node in context.nodes(ast.Attribute))
+        or any(
+            isinstance(node.value, str) and function.name in node.value.split(".")
+            for node in context.nodes(ast.Constant)
+        )
+    ):
+        return None
+    references = [node for node in context.nodes(ast.Name) if node.id == function.name]
+    if not references or any(
+        not isinstance(node.ctx, ast.Load) or provenance.binding(node.id, node) is not function for node in references
+    ):
+        return None
+    return references
+
+
+def has_member_import(tree: ast.Module | None, name: str, *, node_index: NodeIndex | None = None) -> bool:
+    return tree is None or any(
+        alias.name == name for node in nodes(tree, ast.ImportFrom, index=node_index) for alias in node.names
+    )
+
+
+def direct_call(reference: ast.Name, context: PythonFileContext) -> ast.Call | None:
+    parent = context.parents.get(reference)
+    if not isinstance(parent, ast.Call) or parent.func is not reference:
+        return None
+    if any(isinstance(argument, ast.Starred) for argument in parent.args) or any(
+        keyword.arg is None for keyword in parent.keywords
+    ):
+        return None
+    return parent
+
+
+def call_matches(function: ast.FunctionDef, call: ast.Call) -> bool:
+    positional = [*function.args.posonlyargs, *function.args.args]
+    keywords = {arg.arg for arg in (*function.args.args, *function.args.kwonlyargs)}
+    required = {arg.arg for arg in positional[: len(positional) - len(function.args.defaults)]}
+    required.update(
+        arg.arg
+        for arg, default in zip(function.args.kwonlyargs, function.args.kw_defaults, strict=True)
+        if default is None
+    )
+    supplied = {arg.arg for arg in positional[: len(call.args)]}
+    if len(call.args) > len(positional):
+        return False
+    for keyword in call.keywords:
+        if keyword.arg not in keywords or keyword.arg in supplied:
+            return False
+        supplied.add(keyword.arg)
+    return required <= supplied
+
+
+def stable_class(context: PythonFileContext, declaration: ast.ClassDef, provenance: ResourceProvenance) -> bool:
+    if declaration.decorator_list or declaration.keywords or context.parents.get(declaration) is not context.tree:
+        return False
+    return provenance.bindings.get(context.tree, {}).get(declaration.name) == [declaration]
+
+
+def plain_class_members(
+    context: PythonFileContext,
+    declaration: ast.ClassDef,
+    provenance: ResourceProvenance,
+    *,
+    pydantic_fields: bool = False,
+) -> bool:
+    return all(
+        _plain_class_member(context, member, provenance, pydantic_fields=pydantic_fields) for member in declaration.body
+    )
+
+
+def _plain_class_member(
+    context: PythonFileContext, member: ast.stmt, provenance: ResourceProvenance, *, pydantic_fields: bool
+) -> bool:
+    match member:
+        case ast.FunctionDef() | ast.AsyncFunctionDef():
+            if member.name.startswith("__"):
+                return False
+            return inert_signature(member, context) and all(
+                _plain_decorator(context, decorator, provenance, pydantic_fields=pydantic_fields)
+                for decorator in member.decorator_list
+            )
+        case ast.AnnAssign(target=ast.Name(), annotation=annotation, value=value):
+            return inert_annotation(annotation, context) and (
+                value is None or inert_class_value(context, value, provenance, pydantic_fields=pydantic_fields)
+            )
+        case ast.Assign(targets=targets, value=value):
+            return all(isinstance(target, ast.Name) for target in targets) and inert_class_value(
+                context, value, provenance, pydantic_fields=pydantic_fields
+            )
+        case ast.Pass() | ast.Expr(value=ast.Constant(value=str())):
+            return True
+        case _:
+            return False
+
+
+def _plain_decorator(
+    context: PythonFileContext, decorator: ast.expr, provenance: ResourceProvenance, *, pydantic_fields: bool
+) -> bool:
+    if isinstance(decorator, ast.Name) and decorator.id in {"classmethod", "staticmethod", "property"}:
+        return context.imports.builtin_is_unshadowed(decorator.id) and provenance.builtin_namespace_untouched
+    target = decorator.func if isinstance(decorator, ast.Call) else decorator
+    qualified = context.module_imports.resolved_qualified_name(target)
+    if qualified in {"typing.final", "typing_extensions.final"} and not isinstance(decorator, ast.Call):
+        return provenance.imported(target, qualified)
+    if (
+        not pydantic_fields
+        or not isinstance(decorator, ast.Call)
+        or qualified
+        not in {
+            "pydantic.model_validator",
+            "pydantic.field_validator",
+            "pydantic.functional_validators.model_validator",
+            "pydantic.functional_validators.field_validator",
+        }
+        or not provenance.imported(target, qualified)
+    ):
+        return False
+    return all(literal_value(argument) for argument in decorator.args) and all(
+        keyword.arg is not None
+        and literal_value(keyword.value)
+        and not (keyword.arg == "mode" and isinstance(keyword.value, ast.Constant) and keyword.value.value == "wrap")
+        for keyword in decorator.keywords
+    )

{sarj_python_lint-1.31.0 → sarj_python_lint-1.32.0}/src/sarj_python_lint/rules/_copy_on_write.py

@@ -2,23 +2,28 @@ from __future__ import annotations
 
 import ast
 from dataclasses import dataclass, replace
+from functools import cached_property
 from types import MappingProxyType
 from typing import TYPE_CHECKING, final
 
+from sarj_python_lint._analysis_session import AnalysisSession
+from sarj_python_lint._file_context import PythonFileContext
 from sarj_python_lint.rules._annotation_semantics import AnnotationSemantics, scope_bound_names
+from sarj_python_lint.rules._closed_helpers import plain_class_members
 from sarj_python_lint.rules._imports import ImportIndex
-from sarj_python_lint.rules._project_index import ProjectIndexSet, SourceUnit, SymbolRef
+from sarj_python_lint.rules._project_index import ProjectIndexSet, SourceUnit, SymbolRef, imports_outside
+from sarj_python_lint.rules._resource_provenance import ResourceProvenance
 
 
 if TYPE_CHECKING:
     from collections.abc import Mapping
-
-    from sarj_python_lint._file_context import PythonFileContext
+    from pathlib import Path
 
 
 type _Function = ast.FunctionDef | ast.AsyncFunctionDef
 _MODEL_BASES = frozenset({"pydantic.BaseModel", "pydantic.main.BaseModel"})
 _PYDANTIC = frozenset({"pydantic", "pydantic.functional_validators"})
+_MAX_BEFORE_VALIDATOR_DECORATORS = 2
 _TYPING = frozenset({"typing", "typing_extensions"})
 _COLLECTIONS = frozenset({"collections.abc", "typing", "typing_extensions"})
 _TWO_ARGUMENTS = 2
@@ -62,6 +67,12 @@ class Mutation:
     before_validator: bool
 
 
+@dataclass(frozen=True, slots=True)
+class _ValidationOwner:
+    context: PythonFileContext
+    provenance: ResourceProvenance
+
+
 @final
 class _Models:
     def __init__(self, context: PythonFileContext) -> None:
@@ -81,11 +92,28 @@ class _Models:
                 },
             )
         )
+        if (
+            (unit is None or unit.module is None)
+            and self.unit.tree is not None
+            and any(isinstance(node, ast.ClassDef) for node in self.unit.tree.body)
+        ):
+            self.indexes = self.indexes.with_unit(self.unit)
+        self._validation_session = AnalysisSession()
+        self._validation_session.project = self.indexes
+        self._validation_owners: dict[Path, _ValidationOwner] = {}
         self._classes: dict[SymbolRef, tuple[SourceUnit, ast.ClassDef] | None] = {}
         self._ancestry: dict[SymbolRef, bool] = {}
         self._fields: dict[tuple[SymbolRef, str], _Shape | None] = {}
         self._annotations: dict[str | None, AnnotationSemantics] = {}
 
+    def validation_owner(self, unit: SourceUnit) -> _ValidationOwner:
+        if unit.path not in self._validation_owners:
+            context = PythonFileContext(unit.path, unit.source, self._validation_session)
+            self._validation_owners[unit.path] = _ValidationOwner(
+                context, ResourceProvenance(context, require_static_namespace=True)
+            )
+        return self._validation_owners[unit.path]
+
     def annotations(self, unit: SourceUnit) -> AnnotationSemantics:
         if unit.module not in self._annotations:
             tree = unit.tree if unit.tree is not None else ast.Module(body=[], type_ignores=[])
@@ -180,6 +208,39 @@ class _Models:
             for base in bases
         )
 
+    def plain_validation(self, symbol: SymbolRef, seen: frozenset[SymbolRef] = frozenset()) -> bool:
+        if (
+            symbol in seen
+            or self.indexes.nominal_membership_is_dynamic(symbol)
+            or (resolved := self.class_node(symbol)) is None
+        ):
+            return False
+        unit, node = resolved
+        if node.decorator_list or (
+            unit.module == "__copy_source__" and imports_outside(unit.tree, _PYDANTIC | _TYPING)
+        ):
+            return False
+        owner = self.validation_owner(unit)
+        if not plain_class_members(owner.context, node, owner.provenance, pydantic_fields=True):
+            return False
+        if any(
+            name
+            in {
+                "__init_subclass__",
+                "__pydantic_init_subclass__",
+                "__pydantic_on_complete__",
+                "__get_pydantic_core_schema__",
+            }
+            for name in scope_bound_names(node.body)
+        ):
+            return False
+        bases = [self.symbol(base, unit) for base in node.bases]
+        return bool(bases) and all(
+            base is not None
+            and (f"{base.module}.{base.name}" in _MODEL_BASES or self.plain_validation(base, seen | {symbol}))
+            for base in bases
+        )
+
     def shape(
         self,
         annotation: ast.expr | None,
@@ -314,6 +375,10 @@ class CopyOnWriteAnalysis:
         for function in context.nodes(ast.FunctionDef, ast.AsyncFunctionDef):
             self._function(function)
 
+    @cached_property
+    def _validator_provider(self) -> ResourceProvenance:
+        return ResourceProvenance(self.context, require_static_namespace=True)
+
     def _function(self, function: _Function) -> None:
         parameters = [*function.args.posonlyargs, *function.args.args, *function.args.kwonlyargs]
         names = {parameter.arg for parameter in parameters}
@@ -343,9 +408,11 @@ class CopyOnWriteAnalysis:
         receiver = self._receiver(function, parameters)
         for parameter in parameters:
             shape = self.models.shape(parameter.annotation, blocked=self._blocked)
-            if receiver is not None and parameter is parameters[0]:
+            if parameter.arg == before_input:
+                bindings[parameter.arg] = _Value(shape, borrowed=True, shared_children=True)
+            elif receiver is not None and parameter is parameters[0]:
                 bindings[parameter.arg] = receiver
-            elif _contains_model(shape) or parameter.arg == before_input:
+            elif _contains_model(shape):
                 bindings[parameter.arg] = _Value(shape, borrowed=True, shared_children=True)
         return bindings
 
@@ -362,26 +429,76 @@ class CopyOnWriteAnalysis:
 
     def _validator_input(self, function: _Function) -> str | None:
         parent = self.context.parents.get(function)
-        class_bindings: set[str] = scope_bound_names(parent.body) if isinstance(parent, ast.ClassDef) else set()
-        if not any(
-            isinstance(decorator, ast.Call)
-            and not any(isinstance(node, ast.Name) and node.id in class_bindings for node in ast.walk(decorator.func))
-            and self.context.module_imports.resolved_symbol(decorator.func, sources=_PYDANTIC)
-            in {"model_validator", "field_validator"}
-            and any(
-                keyword.arg == "mode" and isinstance(keyword.value, ast.Constant) and keyword.value.value == "before"
-                for keyword in decorator.keywords
-            )
-            for decorator in function.decorator_list
+        if (
+            not isinstance(parent, ast.ClassDef)
+            or self.context.parents.get(parent) is not self.context.tree
+            or not function.decorator_list
+            or self.context.dynamic_namespace
         ):
             return None
+        decorator = self._before_decorator(function)
+        if decorator is None:
+            return None
+        symbol = self.models.symbol(ast.Name(id=parent.name))
+        if symbol is None or not self.models.plain_validation(symbol):
+            return None
+        if function.name in scope_bound_names([member for member in parent.body if member is not function]):
+            return None
+        class_bindings = scope_bound_names(parent.body)
+        if any(isinstance(node, ast.Name) and node.id in class_bindings for node in ast.walk(decorator.func)):
+            return None
+        descriptor = self._validator_descriptor(function, class_bindings)
+        if descriptor is None:
+            return None
         parameters = [*function.args.posonlyargs, *function.args.args]
-        is_classmethod = any(
-            isinstance(decorator, ast.Name) and decorator.id == "classmethod" for decorator in function.decorator_list
+        qualified = self.context.module_imports.resolved_qualified_name(decorator.func)
+        if qualified is None or not self._validator_provider.imported(decorator.func, qualified):
+            return None
+        offset = int(
+            descriptor == "builtins.classmethod"
+            or (descriptor == "auto" and bool(parameters and parameters[0].arg == "cls"))
         )
-        offset = int(is_classmethod or bool(parameters and parameters[0].arg == "cls"))
         return parameters[offset].arg if len(parameters) > offset else None
 
+    def _before_decorator(self, function: _Function) -> ast.Call | None:
+        decorator = function.decorator_list[0]
+        if not isinstance(decorator, ast.Call) or len(function.decorator_list) > _MAX_BEFORE_VALIDATOR_DECORATORS:
+            return None
+        if self.context.module_imports.resolved_symbol(decorator.func, sources=_PYDANTIC) not in {
+            "model_validator",
+            "field_validator",
+        }:
+            return None
+        return (
+            decorator
+            if any(
+                keyword.arg == "mode" and isinstance(keyword.value, ast.Constant) and keyword.value.value == "before"
+                for keyword in decorator.keywords
+            )
+            else None
+        )
+
+    def _validator_descriptor(self, function: _Function, class_bindings: set[str]) -> str | None:
+        if not self._validator_provider.builtin_namespace_untouched:
+            return None
+        if len(function.decorator_list) == _MAX_BEFORE_VALIDATOR_DECORATORS:
+            inner = function.decorator_list[1]
+            qualified = self.context.module_imports.resolved_qualified_name(inner)
+            if (
+                isinstance(inner, ast.Name)
+                and inner.id in {"classmethod", "staticmethod"}
+                and (
+                    inner.id not in class_bindings
+                    and inner.id not in self.context.module_imports.shadowed_names
+                    and inner.id not in self.context.module_imports.bindings
+                )
+            ):
+                qualified = f"builtins.{inner.id}"
+            if qualified not in {"builtins.classmethod", "builtins.staticmethod"}:
+                return None
+            return qualified
+        return "auto"
+
     def _value(self, node: ast.expr, bindings: Mapping[str, _Value]) -> _Value | None:
         match node:
             case ast.Name(id=name):

{sarj_python_lint-1.31.0 → sarj_python_lint-1.32.0}/src/sarj_python_lint/rules/_namespace_access.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import ast
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Final
 
 
 if TYPE_CHECKING:
@@ -27,11 +27,13 @@ _DYNAMIC_MEMBERS = frozenset(
         "f_builtins",
     }
 )
-_MODULE_APIS = {
+_MODULE_APIS: Final[dict[str, frozenset[str]]] = {
     "sys": frozenset({"modules", "_getframe"}),
+    "inspect": frozenset({"currentframe"}),
     "importlib": frozenset({"import_module"}),
     "builtins": _NAMESPACE_APIS,
 }
+_RESOLVED_MEMBERS = _NAMESPACE_APIS | {"modules", "import_module"}
 
 
 def dynamic_namespace_access(
@@ -72,6 +74,8 @@ def _namespace_reference(
     if isinstance(node, ast.Attribute):
         if node.attr in _DYNAMIC_MEMBERS:
             return True
+        if node.attr not in _RESOLVED_MEMBERS:
+            return False
         qualified = imports.resolved_qualified_name(node)
         return qualified in {"sys.modules", "importlib.import_module"} or (
             imports.resolved_symbol(node, sources=frozenset({"builtins"})) in _NAMESPACE_APIS