sarj-python-lint 1.56.0__tar.gz → 1.57.0__tar.gz

{sarj_python_lint-1.56.0 → sarj_python_lint-1.57.0}/PKG-INFO

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

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

sarj_python_lint-1.57.0/src/sarj_python_lint/rules/_mapping_shape_callbacks.py

@@ -0,0 +1,260 @@
+from __future__ import annotations
+
+import ast
+from typing import TYPE_CHECKING, final
+
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from sarj_python_lint._file_context import PythonFileContext
+    from sarj_python_lint.rules._resource_provenance import ResourceProvenance
+
+
+type _Function = ast.FunctionDef | ast.AsyncFunctionDef
+_VALIDATORS = frozenset(
+    {
+        "pydantic.model_validator",
+        "pydantic.field_validator",
+        "pydantic.functional_validators.model_validator",
+        "pydantic.functional_validators.field_validator",
+    }
+)
+_DISCRIMINATORS = frozenset({"pydantic.Discriminator", "pydantic.types.Discriminator"})
+_RAW_METADATA = frozenset(
+    {
+        "pydantic.BeforeValidator",
+        "pydantic.WrapValidator",
+        "pydantic.functional_validators.BeforeValidator",
+        "pydantic.functional_validators.WrapValidator",
+    }
+)
+_MAX_DEPTH = 32
+
+
+@final
+class RawMappingCallbacks:
+    def __init__(
+        self,
+        context: PythonFileContext,
+        provenance: ResourceProvenance,
+        qualified: Callable[[ast.expr, ast.AST], str | None],
+        builtin: Callable[[ast.expr, str, ast.AST], bool],
+        shadowed: Callable[[str, ast.AST], bool],
+    ) -> None:
+        self.context = context
+        self.provenance = provenance
+        self.qualified = qualified
+        self.builtin = builtin
+        self.shadowed = shadowed
+        self.ownership: dict[_Function, bool] = {}
+        self.callbacks = {
+            binding
+            for call in context.nodes(ast.Call)
+            if (origin := qualified(call.func, call)) in _DISCRIMINATORS | _RAW_METADATA
+            if (argument := _callback_argument(call, origin)) is not None
+            if (binding := self.callback(argument)) is not None
+        }
+
+    def callback(self, node: ast.expr, *, seen: frozenset[ast.AST] = frozenset()) -> _Function | None:
+        if len(seen) >= _MAX_DEPTH:
+            return None
+        if isinstance(node, ast.Call):
+            return (
+                self._partial(node, seen)
+                if self.qualified(node.func, node) == "functools.partial"
+                else self._method(node, "__call__", seen)
+            )
+        if isinstance(node, ast.Attribute):
+            return self._method(node.value, node.attr, seen)
+        if not isinstance(node, ast.Name) or not self._stable(node.id) or self.shadowed(node.id, node):
+            return None
+        binding = self.provenance.binding(node.id, node)
+        if isinstance(binding, ast.FunctionDef | ast.AsyncFunctionDef):
+            return binding if not binding.decorator_list else None
+        if not isinstance(binding, ast.Name) or binding in seen:
+            return None
+        value = self.provenance.assignment_value(binding, node)
+        return self.callback(value, seen=seen | {binding}) if value is not None else None
+
+    def _partial(self, node: ast.Call, seen: frozenset[ast.AST]) -> _Function | None:
+        if len(node.args) != 1 or isinstance(node.args[0], ast.Starred):
+            return None
+        callback = self.callback(node.args[0], seen=seen | {node})
+        if callback is None or not (callback.args.posonlyargs or callback.args.args):
+            return None
+        configuration = {argument.arg for argument in callback.args.kwonlyargs}
+        return callback if all(keyword.arg in configuration for keyword in node.keywords) else None
+
+    def _stable(self, name: str) -> bool:
+        return name not in self.provenance.mutated | self.provenance.external_bindings
+
+    def _method(self, node: ast.expr, name: str, seen: frozenset[ast.AST]) -> ast.FunctionDef | None:
+        owner = self._owner(node, seen)
+        if owner is None:
+            return None
+        declaration, on_class = owner
+        if declaration.bases or declaration.keywords or declaration.type_params:
+            return None
+        if (
+            not isinstance(self.context.parents.get(declaration), ast.Module | ast.FunctionDef | ast.AsyncFunctionDef)
+            or not self._stable(declaration.name)
+            or any(
+                self.qualified(decorator, decorator) not in {"typing.final", "typing_extensions.final"}
+                for decorator in declaration.decorator_list
+            )
+        ):
+            return None
+        method = _plain_method(declaration, name)
+        if method is None:
+            return None
+        if not method.decorator_list:
+            return method if not on_class else None
+        if len(method.decorator_list) != 1:
+            return None
+        decorator = method.decorator_list[0]
+        return (
+            method
+            if any(self.builtin(decorator, kind, decorator) for kind in ("staticmethod", "classmethod"))
+            else None
+        )
+
+    def _owner(self, node: ast.expr, seen: frozenset[ast.AST]) -> tuple[ast.ClassDef, bool] | None:
+        if len(seen) >= _MAX_DEPTH:
+            return None
+        if isinstance(node, ast.Call):
+            if node.args or node.keywords or not isinstance(node.func, ast.Name):
+                return None
+            owner = self._owner(node.func, seen | {node})
+            return (owner[0], False) if owner is not None and owner[1] else None
+        if not isinstance(node, ast.Name) or not self._stable(node.id) or self.shadowed(node.id, node):
+            return None
+        binding = self.provenance.binding(node.id, node)
+        if isinstance(binding, ast.ClassDef):
+            return binding, True
+        if not isinstance(binding, ast.Name) or binding in seen:
+            return None
+        value = self.provenance.assignment_value(binding, node)
+        return self._owner(value, seen | {binding}) if value is not None else None
+
+    def owns(self, node: ast.AST) -> bool:
+        function = self._function(node)
+        return function is not None and self._owned(function, frozenset())
+
+    def _function(self, node: ast.AST) -> _Function | None:
+        current = self.context.parents.get(node)
+        while current is not None:
+            if isinstance(current, ast.FunctionDef | ast.AsyncFunctionDef):
+                return current
+            if isinstance(current, ast.ClassDef | ast.Lambda):
+                return None
+            current = self.context.parents.get(current)
+        return None
+
+    def _owned(self, function: _Function, seen: frozenset[ast.AST]) -> bool:
+        if function in self.ownership:
+            return self.ownership[function]
+        if function in seen or len(seen) >= _MAX_DEPTH:
+            return False
+        result = self._raw_validator(function)
+        if not result:
+            owner = self._function(function)
+            result = owner is not None and self._owned(owner, seen | {function}) and self._local_helper(function, owner)
+        self.ownership[function] = result
+        return result
+
+    def _local_helper(self, function: _Function, owner: _Function) -> bool:
+        if (
+            function.decorator_list
+            or self.context.parents.get(function) is not owner
+            or not self._stable(function.name)
+        ):
+            return False
+        reads = [
+            read
+            for read in self.provenance.reads.get(function.name, ())
+            if self.provenance.binding(function.name, read) is function
+        ]
+        return bool(reads) and all(
+            isinstance(parent := self.context.parents.get(read), ast.Call)
+            and parent.func is read
+            and self._function(read) in {owner, function}
+            for read in reads
+        )
+
+    def _raw_validator(self, function: _Function) -> bool:
+        if function in self.callbacks:
+            return True
+        return any(
+            isinstance(decorator, ast.Call)
+            and self.qualified(decorator.func, decorator) in _VALIDATORS
+            and any(
+                keyword.arg == "mode" and self._mode(keyword.value) in {"before", "wrap"}
+                for keyword in decorator.keywords
+            )
+            for decorator in function.decorator_list
+        )
+
+    def _mode(self, node: ast.expr, *, seen: frozenset[ast.AST] = frozenset()) -> str | None:
+        if isinstance(node, ast.Constant) and isinstance(node.value, str):
+            return node.value
+        if (
+            len(seen) >= _MAX_DEPTH
+            or not isinstance(node, ast.Name)
+            or not self._stable(node.id)
+            or self.shadowed(node.id, node)
+        ):
+            return None
+        binding = self.provenance.binding(node.id, node)
+        if not isinstance(binding, ast.Name) or binding in seen:
+            return None
+        statement = self.context.parents.get(binding)
+        if not isinstance(statement, ast.Assign | ast.AnnAssign):
+            return None
+        if (
+            (isinstance(statement, ast.Assign) and len(statement.targets) != 1)
+            or statement.value is None
+            or statement.lineno >= node.lineno
+            or not isinstance(
+                self.context.parents.get(statement), ast.Module | ast.ClassDef | ast.FunctionDef | ast.AsyncFunctionDef
+            )
+        ):
+            return None
+        return self._mode(statement.value, seen=seen | {binding})
+
+
+def _callback_argument(call: ast.Call, qualified: str | None) -> ast.expr | None:
+    if call.args:
+        return call.args[0]
+    parameter = "discriminator" if qualified in _DISCRIMINATORS else "func"
+    return next((keyword.value for keyword in call.keywords if keyword.arg == parameter), None)
+
+
+def _plain_method(node: ast.ClassDef, name: str) -> ast.FunctionDef | None:
+    method: ast.FunctionDef | None = None
+    for statement in node.body:
+        match statement:
+            case ast.FunctionDef(name=declared) if declared == name and method is None:
+                method = statement
+            case ast.Assign(value=value, targets=targets) if all(
+                isinstance(target, ast.Name) and target.id != name and _inert_attribute(target.id, value)
+                for target in targets
+            ):
+                continue
+            case ast.AnnAssign(target=ast.Name(id=attribute), value=value) if attribute != name and _inert_attribute(
+                attribute, value
+            ):
+                continue
+            case ast.Pass() | ast.Expr(value=ast.Constant(value=str())):
+                continue
+            case _:
+                return None
+    return method
+
+
+def _inert_attribute(name: str, value: ast.expr | None) -> bool:
+    if name == "__slots__":
+        return isinstance(value, ast.Tuple) and not value.elts
+    return (name == "__name__" or not (name.startswith("__") and name.endswith("__"))) and (
+        value is None or isinstance(value, ast.Constant)
+    )

{sarj_python_lint-1.56.0 → sarj_python_lint-1.57.0}/src/sarj_python_lint/rules/require_pydantic_for_mapping_shape.py

@@ -18,6 +18,7 @@ from sarj_python_lint.rule_base import (
 )
 from sarj_python_lint.rules._annotation_semantics import AnnotationSemantics
 from sarj_python_lint.rules._imports import ImportIndex
+from sarj_python_lint.rules._mapping_shape_callbacks import RawMappingCallbacks
 from sarj_python_lint.rules._paths import is_test_path
 from sarj_python_lint.rules._resource_provenance import ResourceProvenance
 
@@ -39,23 +40,6 @@ _MAPPINGS = frozenset(
     }
 )
 _WRAPPERS = frozenset({"Annotated", "Final", "ClassVar", "Required", "NotRequired", "ReadOnly", "Optional"})
-_VALIDATORS = frozenset(
-    {
-        "pydantic.model_validator",
-        "pydantic.field_validator",
-        "pydantic.functional_validators.model_validator",
-        "pydantic.functional_validators.field_validator",
-    }
-)
-_DISCRIMINATORS = frozenset({"pydantic.Discriminator", "pydantic.types.Discriminator"})
-_RAW_METADATA = frozenset(
-    {
-        "pydantic.BeforeValidator",
-        "pydantic.WrapValidator",
-        "pydantic.functional_validators.BeforeValidator",
-        "pydantic.functional_validators.WrapValidator",
-    }
-)
 _MAX_DEPTH = 32
 _MAPPING_ARITY = 2
 _BAD = (
@@ -102,8 +86,8 @@ class RequirePydanticForMappingShape(Rule):
         limitations=(
             "Checks literal-string get/subscript reads on parameters or local names annotated as standard string mappings with object, Any or pydantic.JsonValue values. Stable module type aliases, quoted annotations, wrappers and local value aliases are recognized with bounded resolution.",
             "A field must feed builtin isinstance/type checks, literal comparisons, truth tests or a constrained match pattern. Ordinary reads/forwarding, dynamic keys, homogeneous typed maps, imported application aliases, attributes and ambiguous/rebound assignments are excluded.",
-            "Import-resolved Pydantic before/wrap decorator or metadata validators and explicitly registered Discriminator callbacks own raw input normalization and are excluded. Stable callback function aliases and simple local callable instances/bound __call__ methods are recognized. Prefer declarative fields before introducing such callbacks.",
-            "Callable classes must be unique undecorated local declarations with no bases, class options, custom constructor or descriptor hooks; only an undecorated __call__ method and inert class data are admitted. Imported, inherited, decorated, rebound and directly mutated callback classes/instances abstain.",
+            "Import-resolved Pydantic before/wrap decorators with literal or stable local mode aliases, metadata validators and registered Discriminator callbacks own raw normalization. Stable function aliases, functools.partial binding only keyword-only configuration and simple bound/static/class methods are recognized. Prefer declarative fields before introducing callbacks.",
+            "Callback classes must be stable direct local declarations with no bases, class options, custom constructor or descriptor hooks. Import-proven typing.final and empty __slots__ preserve ownership. Other decorators, imported/inherited classes and directly mutated callback owners abstain. Nonescaping direct local helpers inherit raw ownership; escaped helpers remain checked. Generic type parameters shadow matching builtin/import annotation names.",
             "Parsing helpers in authored tests are checked, but assert-contained test oracles are excluded. Generated/vendor sources and dynamic namespaces are excluded. This is a warning with no automatic rewrite because coercion, missing-field handling and error policy can differ.",
         ),
         examples=(
@@ -168,58 +152,20 @@ class _Facts:
             node: ImportIndex.from_tree(ast.Module(body=[node], type_ignores=[]))
             for node in context.nodes(ast.Import, ast.ImportFrom)
         }
-        self.callbacks = {
-            binding
-            for call in context.nodes(ast.Call)
-            if (qualified := self.qualified(call.func, call)) in _DISCRIMINATORS | _RAW_METADATA
-            if (argument := _callback_argument(call, qualified)) is not None
-            if (binding := self.callback(argument)) is not None
-        }
+        self.callbacks = RawMappingCallbacks(context, self.provenance, self.qualified, self.builtin, self.shadowed)
 
-    def callback(self, node: ast.expr, *, seen: frozenset[ast.AST] = frozenset()) -> ast.AST | None:
-        if len(seen) >= _MAX_DEPTH:
-            return None
-        if isinstance(node, ast.Call):
-            return self.callable_method(node, seen=seen)
-        if isinstance(node, ast.Attribute) and node.attr == "__call__":
-            return self.callable_method(node.value, seen=seen)
-        if not isinstance(node, ast.Name) or node.id in self.provenance.mutated | self.provenance.external_bindings:
-            return None
-        binding = self.provenance.binding(node.id, node)
-        if isinstance(binding, ast.FunctionDef | ast.AsyncFunctionDef):
-            return binding if not binding.decorator_list else None
-        if not isinstance(binding, ast.Name) or binding in seen:
-            return None
-        value = self.provenance.assignment_value(binding, node)
-        return self.callback(value, seen=seen | {binding}) if value is not None else None
-
-    def callable_method(self, node: ast.expr, *, seen: frozenset[ast.AST]) -> ast.FunctionDef | None:
-        if len(seen) >= _MAX_DEPTH:
-            return None
-        if isinstance(node, ast.Name):
-            if node.id in self.provenance.mutated | self.provenance.external_bindings:
-                return None
-            binding = self.provenance.binding(node.id, node)
-            if not isinstance(binding, ast.Name) or binding in seen:
-                return None
-            value = self.provenance.assignment_value(binding, node)
-            return self.callable_method(value, seen=seen | {binding}) if value is not None else None
-        if not isinstance(node, ast.Call) or node.args or node.keywords or not isinstance(node.func, ast.Name):
-            return None
-        if node.func.id in self.provenance.mutated | self.provenance.external_bindings:
-            return None
-        binding = self.provenance.binding(node.func.id, node)
-        if not isinstance(binding, ast.ClassDef) or not isinstance(
-            self.context.parents.get(binding), ast.Module | ast.FunctionDef | ast.AsyncFunctionDef
-        ):
-            return None
-        return _plain_callable_method(binding)
+    def shadowed(self, name: str, at: ast.AST) -> bool:
+        return _type_parameter_shadow(name, at, self.context)
 
     def qualified(self, node: ast.expr, at: ast.AST) -> str | None:
         root = node
         while isinstance(root, ast.Attribute):
             root = root.value
-        if not isinstance(root, ast.Name) or root.id in self.provenance.mutated | self.provenance.external_bindings:
+        if (
+            not isinstance(root, ast.Name)
+            or root.id in self.provenance.mutated | self.provenance.external_bindings
+            or _type_parameter_shadow(root.id, at, self.context)
+        ):
             return None
         binding = self.provenance.binding(root.id, at)
         parent = self.context.parents.get(binding) if binding is not None else None
@@ -231,6 +177,7 @@ class _Facts:
             self.provenance.builtin_namespace_untouched
             and isinstance(node, ast.Name)
             and node.id == name
+            and not _type_parameter_shadow(name, at, self.context)
             and self.provenance.binding(name, at) is None
         )
 
@@ -240,6 +187,8 @@ class _Facts:
         parsed = self.semantics.parse(node)
         if parsed is None:
             return False
+        if isinstance(parsed, ast.Name) and _type_parameter_shadow(parsed.id, at, self.context):
+            return False
         if isinstance(parsed, ast.Name) and parsed.id in self.semantics.aliases:
             return self.alias_annotation(parsed, at, mapping=mapping, depth=depth)
         if isinstance(parsed, ast.BinOp) and isinstance(parsed.op, ast.BitOr):
@@ -320,27 +269,34 @@ class _Facts:
         return None
 
     def raw_boundary(self, node: ast.AST) -> bool:
-        current: ast.AST | None = node
-        while current is not None:
-            if isinstance(current, ast.FunctionDef | ast.AsyncFunctionDef) and self.raw_validator(current):
-                return True
-            current = self.context.parents.get(current)
-        return False
+        return self.callbacks.owns(node)
 
-    def raw_validator(self, function: ast.FunctionDef | ast.AsyncFunctionDef) -> bool:
-        if function in self.callbacks:
+
+def _type_parameter_shadow(name: str, at: ast.AST, context: PythonFileContext) -> bool:
+    outside: set[ast.AST] = set()
+    current = at
+    while (parent := context.parents.get(current)) is not None:
+        if (
+            isinstance(parent, ast.arguments)
+            and (current in parent.defaults or current in parent.kw_defaults)
+            and (owner := context.parents.get(parent)) is not None
+        ):
+            outside.add(owner)
+        if (
+            isinstance(parent, ast.FunctionDef | ast.AsyncFunctionDef | ast.ClassDef | ast.TypeAlias)
+            and parent not in outside
+            and not (
+                isinstance(parent, ast.FunctionDef | ast.AsyncFunctionDef | ast.ClassDef)
+                and current in parent.decorator_list
+            )
+            and any(
+                isinstance(parameter, ast.TypeVar | ast.ParamSpec | ast.TypeVarTuple) and parameter.name == name
+                for parameter in parent.type_params
+            )
+        ):
             return True
-        for decorator in function.decorator_list:
-            if not isinstance(decorator, ast.Call) or self.qualified(decorator.func, decorator) not in _VALIDATORS:
-                continue
-            if any(
-                keyword.arg == "mode"
-                and isinstance(keyword.value, ast.Constant)
-                and keyword.value.value in {"before", "wrap"}
-                for keyword in decorator.keywords
-            ):
-                return True
-        return False
+        current = parent
+    return False
 
 
 def _string(node: ast.expr) -> bool:
@@ -368,40 +324,6 @@ def _get_receiver(node: ast.expr) -> ast.expr | None:
     return node.func.value
 
 
-def _callback_argument(call: ast.Call, qualified: str | None) -> ast.expr | None:
-    if call.args:
-        return call.args[0]
-    parameter = "discriminator" if qualified in _DISCRIMINATORS else "func"
-    return next((keyword.value for keyword in call.keywords if keyword.arg == parameter), None)
-
-
-def _plain_callable_method(node: ast.ClassDef) -> ast.FunctionDef | None:
-    if node.bases or node.keywords or node.decorator_list or node.type_params:
-        return None
-    method: ast.FunctionDef | None = None
-    for statement in node.body:
-        match statement:
-            case ast.FunctionDef(name="__call__", decorator_list=[]) if method is None:
-                method = statement
-            case ast.Assign(value=ast.Constant(), targets=targets) if all(
-                isinstance(target, ast.Name) and _inert_callable_attribute(target.id) for target in targets
-            ):
-                continue
-            case ast.AnnAssign(target=ast.Name(id=name), value=None | ast.Constant()) if _inert_callable_attribute(
-                name
-            ):
-                continue
-            case ast.Pass() | ast.Expr(value=ast.Constant(value=str())):
-                continue
-            case _:
-                return None
-    return method
-
-
-def _inert_callable_attribute(name: str) -> bool:
-    return name == "__name__" or not (name.startswith("__") and name.endswith("__"))
-
-
 def _probe_sources(node: ast.AST, facts: _Facts) -> Iterator[ast.expr]:
     match node:
         case ast.Call(func=func, args=[value, _], keywords=[]) if facts.builtin(func, "isinstance", node):