sarj-python-lint 1.47.0__tar.gz → 1.49.0__tar.gz

{sarj_python_lint-1.47.0 → sarj_python_lint-1.49.0}/PKG-INFO

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

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

{sarj_python_lint-1.47.0 → sarj_python_lint-1.49.0}/src/sarj_python_lint/rules/_registry.py

@@ -43,6 +43,7 @@ from sarj_python_lint.rules.no_cors_wildcard_with_credentials import (
 )
 from sarj_python_lint.rules.no_database_programmability import NoDatabaseProgrammability
 from sarj_python_lint.rules.no_delete_statement import NoDeleteStatement
+from sarj_python_lint.rules.no_discarded_validation_result import NoDiscardedValidationResult
 from sarj_python_lint.rules.no_dunder_all import NoDunderAll
 from sarj_python_lint.rules.no_duplicate_dunder_all_entry import NoDuplicateDunderAllEntry
 from sarj_python_lint.rules.no_excessive_cognitive_complexity import NoExcessiveCognitiveComplexity
@@ -221,14 +222,20 @@ from sarj_python_lint.rules.no_invalid_pydantic_validator_return import NoInvali
 from sarj_python_lint.rules.no_partial_type_is import NoPartialTypeIs
 from sarj_python_lint.rules.no_shallow_record_type_guard import NoShallowRecordTypeGuard
 from sarj_python_lint.rules.no_unknown_pydantic_validator_field import NoUnknownPydanticValidatorField
+from sarj_python_lint.rules.prefer_bulk_upsert import PreferBulkUpsert
 from sarj_python_lint.rules.prefer_discriminated_model_union import PreferDiscriminatedModelUnion
+from sarj_python_lint.rules.prefer_psycopg_executemany import PreferPsycopgExecutemany
 from sarj_python_lint.rules.redundant_test_constructor_forwarder import RedundantTestConstructorForwarder
 from sarj_python_lint.rules.repeated_unimplemented_test_contract import RepeatedUnimplementedTestContract
+from sarj_python_lint.rules.store_field_update_reuses_upsert import StoreFieldUpdateReusesUpsert
 from sarj_python_lint.rules.test_without_explicit_oracle import NoExplicitTestOracle
 
 
 REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
     {
+        PreferBulkUpsert.id: PreferBulkUpsert,
+        PreferPsycopgExecutemany.id: PreferPsycopgExecutemany,
+        StoreFieldUpdateReusesUpsert.id: StoreFieldUpdateReusesUpsert,
         NoExplicitTestOracle.id: NoExplicitTestOracle,
         PreferDiscriminatedModelUnion.id: PreferDiscriminatedModelUnion,
         NoInvalidPydanticBypass.id: NoInvalidPydanticBypass,
@@ -243,6 +250,7 @@ REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
         NoFixedSleepInLoop.id: NoFixedSleepInLoop,
         NoInterpreterSourceArguments.id: NoInterpreterSourceArguments,
         NoUnusedCopyResult.id: NoUnusedCopyResult,
+        NoDiscardedValidationResult.id: NoDiscardedValidationResult,
         NoBeforeValidatorInputMutation.id: NoBeforeValidatorInputMutation,
         NoInputModelMutation.id: NoInputModelMutation,
         NoDatabaseProgrammability.id: NoDatabaseProgrammability,

{sarj_python_lint-1.47.0 → sarj_python_lint-1.49.0}/src/sarj_python_lint/rules/_resource_provenance.py

@@ -8,9 +8,12 @@ from typing import TYPE_CHECKING, final
 
 from sarj_python_lint.rules._ast_index import has_own_yield
 from sarj_python_lint.rules._namespace_access import dynamic_namespace_access
+from sarj_python_lint.rules._runtime_bindings import RuntimeBindings
 
 
 if TYPE_CHECKING:
+    from pathlib import Path
+
     from sarj_python_lint._file_context import PythonFileContext
 
 
@@ -76,6 +79,7 @@ class ResourceProvenance:
         self.escape_cache: dict[tuple[ast.AST, bool], bool] = {}
         self.async_contract_cache: dict[ast.AsyncFunctionDef, bool] = {}
         self.import_contract_cache: dict[str, bool] = {}
+        self.runtime_import_cache: dict[ast.alias, bool] = {}
         self.wildcard = False
         self.mutated: set[str] = set()
         self.external_bindings: set[str] = set()
@@ -133,6 +137,113 @@ class ResourceProvenance:
             scope = self.scope(scope)
         return None
 
+    @cached_property
+    def runtime_bindings(self) -> RuntimeBindings:
+        return RuntimeBindings(self.context, self.bindings)
+
+    def runtime_binding(self, name: str, at: ast.AST) -> ast.AST | None:
+        nodes = self.runtime_bindings.lookup(self.scope(at), name)
+        if not nodes:
+            return None
+        return nodes[0] if len(nodes) == 1 or self._same_import_bindings(list(nodes)) else None
+
+    def runtime_import_name(self, node: ast.expr) -> str | None:
+        root = _root_name(node)
+        if self.wildcard or self.dynamic_namespace or root is None or root in self.mutated:
+            return None
+        binding = self.runtime_binding(root, node)
+        if not isinstance(binding, ast.alias):
+            return None
+        qualified = _runtime_import_name(node, binding, self.context.parents.get(binding))
+        if qualified is None or not self._owner_namespace_untouched(qualified.partition(".")[0]):
+            return None
+        if binding not in self.runtime_import_cache:
+            self.runtime_import_cache[binding] = all(
+                self.runtime_binding(root, read) is not binding or self._safe_import_use(read)
+                for read in self.reads.get(root, ())
+            )
+        return qualified if self.runtime_import_cache[binding] else None
+
+    @cached_property
+    def mock_namespace_patching(self) -> bool:
+        return any(
+            self.runtime_import_name(node.func)
+            in {
+                "unittest.mock.patch",
+                "unittest.mock.patch.object",
+                "unittest.mock.patch.multiple",
+                "unittest.mock.patch.dict",
+            }
+            for node in self.context.nodes(ast.Call)
+        )
+
+    @cached_property
+    def imported_namespace_hazards(self) -> frozenset[Path]:
+        hazards: set[Path] = set()
+        for node in self.context.nodes(ast.Name, ast.Attribute):
+            match node:
+                case ast.Attribute(value=value, ctx=ast.Store() | ast.Del()):
+                    hazards.update(self._namespace_paths(value, include_root=True))
+                case ast.Name(ctx=ast.Load()) | ast.Attribute(ctx=ast.Load()) if not self._safe_import_use(node):
+                    hazards.update(self._namespace_paths(node, include_root=False))
+                case _:
+                    pass
+        return frozenset(hazards)
+
+    @cached_property
+    def _namespace_aliases(self) -> dict[str, tuple[ast.alias, ...]]:
+        aliases: dict[str, list[ast.alias]] = defaultdict(list)
+        for binding in self.context.nodes(ast.alias):
+            parent = self.context.parents.get(binding)
+            name = binding.asname or (
+                binding.name.partition(".")[0] if isinstance(parent, ast.Import) else binding.name
+            )
+            aliases[name].append(binding)
+        return {name: tuple(bindings) for name, bindings in aliases.items()}
+
+    def _namespace_paths(self, expression: ast.expr, *, include_root: bool) -> set[Path]:
+        attributes: list[str] = []
+        root = expression
+        while isinstance(root, ast.Attribute):
+            attributes.append(root.attr)
+            root = root.value
+        if not isinstance(root, ast.Name):
+            return set()
+        binding = self.runtime_binding(root.id, expression)
+        aliases: tuple[ast.alias, ...]
+        match binding:
+            case ast.alias():
+                aliases = (binding,)
+            case None:
+                aliases = self._namespace_aliases.get(root.id, ())
+            case _:
+                return set()
+        paths: set[Path] = set()
+        for alias in aliases:
+            path = self._namespace_module_path(alias, tuple(reversed(attributes)))
+            if path is not None:
+                paths.add(path)
+            if include_root and attributes:
+                base = self._namespace_module_path(alias, ())
+                if base is not None:
+                    paths.add(base)
+        return paths
+
+    def _namespace_module_path(self, binding: ast.alias, attributes: tuple[str, ...]) -> Path | None:
+        parent = self.context.parents.get(binding)
+        match parent:
+            case ast.Import():
+                prefix = binding.name if binding.asname else binding.name.partition(".")[0]
+                level = 0
+            case ast.ImportFrom(module=module, level=level):
+                prefix = ".".join(part for part in (module, binding.name) if part)
+            case _:
+                return None
+        module = ".".join((prefix, *attributes))
+        return self.context.session.local_source.resolve_module(
+            self.context.path, module, level, facts=self.context.session.first_party
+        )
+
     def _same_import_bindings(self, nodes: list[ast.AST]) -> bool:
         targets: set[tuple[str, str | None, int, str]] = set()
         for node in nodes:
@@ -417,6 +528,21 @@ def _root_name(node: ast.expr) -> str | None:
     return node.id if isinstance(node, ast.Name) else None
 
 
+def _runtime_import_name(expression: ast.expr, binding: ast.alias, parent: ast.AST | None) -> str | None:
+    attributes: list[str] = []
+    while isinstance(expression, ast.Attribute):
+        attributes.append(expression.attr)
+        expression = expression.value
+    match parent:
+        case ast.Import():
+            prefix = binding.name if binding.asname else binding.name.partition(".")[0]
+        case ast.ImportFrom(module=str(module), level=0):
+            prefix = f"{module}.{binding.name}"
+        case _:
+            return None
+    return ".".join((prefix, *reversed(attributes)))
+
+
 def _bound_names(node: ast.AST) -> tuple[str, ...]:
     match node:
         case ast.Name(id=name, ctx=ast.Store() | ast.Del()) | ast.arg(arg=name):

sarj_python_lint-1.49.0/src/sarj_python_lint/rules/_runtime_bindings.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+import ast
+from collections import defaultdict
+import symtable
+from typing import TYPE_CHECKING, final
+
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping, Sequence
+
+    from sarj_python_lint._file_context import PythonFileContext
+
+
+@final
+class RuntimeBindings:
+    def __init__(
+        self, context: PythonFileContext, bindings: Mapping[ast.AST | None, Mapping[str, Sequence[ast.AST]]]
+    ) -> None:
+        self.bindings = bindings
+        self.tables: dict[int, symtable.SymbolTable] = {}
+        self.parents: dict[int, int | None] = {}
+        self.by_scope: dict[ast.AST, int] = {}
+        self.scopes: dict[int, ast.AST] = {}
+        self.mutable: set[tuple[int, str]] = set()
+        self.module: int | None = None
+        tree = context.tree
+        if tree is None:
+            return
+        try:
+            root = symtable.symtable(context.source, str(context.path), "exec")
+        except SyntaxError, UnicodeError, RecursionError:
+            return
+        self.module = root.get_id()
+        self._collect(root)
+        self._map_scopes(context, tree, root)
+        self._index_writes()
+
+    def lookup(self, scope: ast.AST | None, name: str) -> Sequence[ast.AST] | None:
+        if scope is None or (table_id := self.by_scope.get(scope)) is None:
+            return None
+        symbol = _symbol(self.tables[table_id], name)
+        if symbol is None or (owner := self._owner(table_id, symbol)) is None or (owner, name) in self.mutable:
+            return None
+        owner_scope = self.scopes.get(owner)
+        return self.bindings.get(owner_scope, {}).get(name) if owner_scope is not None else None
+
+    def _collect(self, root: symtable.SymbolTable) -> None:
+        pending: list[tuple[symtable.SymbolTable, int | None]] = [(root, None)]
+        while pending:
+            table, parent = pending.pop()
+            identity = table.get_id()
+            self.tables[identity] = table
+            self.parents[identity] = parent
+            pending.extend((child, identity) for child in table.get_children())
+
+    def _map_scopes(self, context: PythonFileContext, tree: ast.Module, root: symtable.SymbolTable) -> None:
+        candidates: dict[tuple[symtable.SymbolTableType, str, int], list[int]] = defaultdict(list)
+        for identity, table in self.tables.items():
+            candidates[table.get_type(), table.get_name(), table.get_lineno()].append(identity)
+        self.by_scope[tree] = root.get_id()
+        self.scopes[root.get_id()] = tree
+        for node in context.nodes(ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef):
+            kind = (
+                symtable.SymbolTableType.CLASS if isinstance(node, ast.ClassDef) else symtable.SymbolTableType.FUNCTION
+            )
+            matches = candidates.get((kind, node.name, node.lineno), ())
+            if len(matches) == 1:
+                [identity] = matches
+                self.by_scope[node] = identity
+                self.scopes[identity] = node
+
+    def _index_writes(self) -> None:
+        for identity, table in self.tables.items():
+            if identity == self.module:
+                continue
+            for symbol in table.get_symbols():
+                if not (symbol.is_global() or symbol.is_nonlocal()):
+                    continue
+                if not (symbol.is_assigned() or symbol.is_imported() or symbol.is_namespace()):
+                    continue
+                owner = self._owner(identity, symbol)
+                if owner is not None:
+                    self.mutable.add((owner, symbol.get_name()))
+
+    def _owner(self, identity: int, symbol: symtable.Symbol) -> int | None:
+        if symbol.is_global():
+            return self.module
+        if symbol.is_local():
+            return identity
+        if not symbol.is_free():
+            return None
+        parent = self.parents.get(identity)
+        while parent is not None:
+            table = self.tables[parent]
+            if table.get_type() is symtable.SymbolTableType.MODULE:
+                break
+            if table.get_type() is symtable.SymbolTableType.CLASS and symbol.get_name() == "__class__":
+                # The compiler binds this cell to the lexically defined class.
+                return None
+            if table.get_type() is not symtable.SymbolTableType.CLASS:
+                ancestor = _symbol(table, symbol.get_name())
+                if ancestor is not None and ancestor.is_local():
+                    return parent
+            parent = self.parents.get(parent)
+        return None
+
+
+def _symbol(table: symtable.SymbolTable, name: str) -> symtable.Symbol | None:
+    try:
+        return table.lookup(name)
+    except KeyError:
+        return None

sarj_python_lint-1.49.0/src/sarj_python_lint/rules/_store_writes.py

@@ -0,0 +1,319 @@
+from __future__ import annotations
+
+import ast
+from types import MappingProxyType
+from typing import TYPE_CHECKING
+
+import sqlglot
+from sqlglot import exp
+from sqlglot.errors import SqlglotError
+
+from sarj_python_lint.rules._annotation_semantics import AnnotationSemantics
+from sarj_python_lint.rules._ast_index import walk
+from sarj_python_lint.rules._paths import is_generated
+from sarj_python_lint.rules._project_index import ProjectIndexSet
+from sarj_python_lint.rules._resource_provenance import ResourceProvenance
+
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+    from sarj_python_lint._file_context import PythonFileContext
+    from sarj_python_lint.rules._imports import ImportIndex
+
+
+type Function = ast.FunctionDef | ast.AsyncFunctionDef
+_COLLECTIONS = frozenset(
+    {
+        "collections.abc.Collection",
+        "collections.abc.Iterable",
+        "collections.abc.Sequence",
+        "typing.Collection",
+        "typing.Iterable",
+        "typing.Sequence",
+        "typing.List",
+    }
+)
+_NEUTRAL_DECORATORS = frozenset({"abc.abstractmethod", "typing.override", "typing_extensions.override"})
+
+
+def method_parameters(method: Function) -> list[ast.arg] | None:
+    args = method.args
+    positional = [*args.posonlyargs, *args.args]
+    if not positional or positional[0].arg != "self":
+        return None
+    if args.vararg or args.kwarg or args.defaults or any(args.kw_defaults):
+        return None
+    return [*positional[1:], *args.kwonlyargs]
+
+
+def methods(owner: ast.ClassDef) -> dict[str, Function]:
+    result: dict[str, Function] = {}
+    ambiguous: set[str] = set()
+    for node in owner.body:
+        if isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef):
+            if node.name in result:
+                ambiguous.add(node.name)
+            result[node.name] = node
+    return {name: method for name, method in result.items() if name not in ambiguous}
+
+
+def upsert_pair(owner: ast.ClassDef, imports: ImportIndex) -> tuple[Function, Function] | None:
+    declared = methods(owner)
+    single, bulk = declared.get("upsert"), declared.get("upsert_many")
+    if (
+        single is None
+        or bulk is None
+        or isinstance(single, ast.AsyncFunctionDef) != isinstance(bulk, ast.AsyncFunctionDef)
+    ):
+        return None
+    if any(
+        imports.resolved_qualified_name(decorator) not in _NEUTRAL_DECORATORS
+        for method in (single, bulk)
+        for decorator in method.decorator_list
+    ):
+        return None
+    one, many = method_parameters(single), method_parameters(bulk)
+    if one is None or many is None or len(one) != 1 or len(many) != 1:
+        return None
+    item = collection_item(many[0].annotation, imports)
+    result = collection_item(bulk.returns, imports)
+    if (
+        item is None
+        or result is None
+        or not same_type(one[0].annotation, item)
+        or not same_type(single.returns, result)
+    ):
+        return None
+    return single, bulk
+
+
+def collection_item(annotation: ast.expr | None, imports: ImportIndex) -> ast.expr | None:
+    annotation = AnnotationSemantics(imports, MappingProxyType({})).parse(annotation)
+    if not isinstance(annotation, ast.Subscript):
+        return None
+    container = annotation.value
+    if isinstance(container, ast.Name) and container.id == "list" and imports.builtin_is_unshadowed("list"):
+        return annotation.slice
+    if imports.resolved_qualified_name(container) in _COLLECTIONS:
+        return annotation.slice
+    return None
+
+
+def same_type(left: ast.expr | None, right: ast.expr | None) -> bool:
+    return (
+        left is not None
+        and right is not None
+        and ast.dump(left, include_attributes=False) == ast.dump(right, include_attributes=False)
+    )
+
+
+def own_nodes(node: ast.AST) -> Iterator[ast.AST]:
+    pending = [node]
+    while pending:
+        current = pending.pop()
+        yield current
+        pending.extend(
+            child
+            for child in reversed(list(ast.iter_child_nodes(current)))
+            if not isinstance(child, ast.FunctionDef | ast.AsyncFunctionDef | ast.ClassDef | ast.Lambda)
+        )
+
+
+def discarded_call(loop: ast.For) -> tuple[ast.Call, bool] | None:
+    if loop.orelse or len(loop.body) != 1 or not isinstance(loop.body[0], ast.Expr):
+        return None
+    if (
+        isinstance(loop.iter, ast.List | ast.Tuple | ast.Set)
+        and len(loop.iter.elts) <= 1
+        and not any(isinstance(item, ast.Starred) for item in loop.iter.elts)
+    ):
+        return None
+    value = loop.body[0].value
+    awaited = isinstance(value, ast.Await)
+    value = value.value if awaited else value
+    return (value, awaited) if isinstance(value, ast.Call) else None
+
+
+def depends_on_target(expression: ast.expr, target: ast.expr) -> bool:
+    names = {node.id for node in walk(target) if isinstance(node, ast.Name)}
+    return any(isinstance(node, ast.Name) and node.id in names for node in own_nodes(expression))
+
+
+class StoreOwners:
+    def __init__(self, context: PythonFileContext) -> None:
+        self.context = context
+        self.provenance = ResourceProvenance(context)
+        self.project = context.session.project
+
+    def receiver(self, expression: ast.expr, at: ast.AST) -> tuple[ast.ClassDef, ImportIndex] | None:
+        if isinstance(expression, ast.Name):
+            binding = self.provenance.binding(expression.id, at)
+            if isinstance(binding, ast.arg) and binding.annotation is not None:
+                return self.annotation(binding.annotation)
+            return None
+        if (
+            not isinstance(expression, ast.Attribute)
+            or not isinstance(expression.value, ast.Name)
+            or expression.value.id != "self"
+        ):
+            return None
+        if not isinstance(self.provenance.binding("self", at), ast.arg):
+            return None
+        annotation = self._injected_annotation(expression.attr, at)
+        return self.annotation(annotation) if annotation is not None else None
+
+    def _injected_annotation(self, attribute: str, at: ast.AST) -> ast.expr | None:
+        parent = self.context.parents.get(at)
+        while parent is not None and not isinstance(parent, ast.ClassDef):
+            parent = self.context.parents.get(parent)
+        if parent is None:
+            return None
+        constructor = methods(parent).get("__init__")
+        if constructor is None:
+            return None
+        assignments = [
+            node
+            for method in methods(parent).values()
+            for node in own_nodes(method)
+            if _writes_self_attribute(node, attribute)
+        ]
+        if len(assignments) != 1:
+            return None
+        for statement in constructor.body:
+            if (
+                not isinstance(statement, ast.Assign)
+                or not isinstance(statement.value, ast.Name)
+                or assignments[0] not in statement.targets
+            ):
+                continue
+            return _injected_parameter(constructor, statement.value, self.provenance)
+        return None
+
+    def annotation(self, expression: ast.expr | None) -> tuple[ast.ClassDef, ImportIndex] | None:
+        original = expression
+        expression = AnnotationSemantics(self.context.module_imports, MappingProxyType({})).parse(expression)
+        if expression is None or self.context.tree is None:
+            return None
+        root = expression.value if isinstance(expression, ast.Attribute) else expression
+        if (
+            not isinstance(root, ast.Name)
+            or original is None
+            or not isinstance(self.provenance.binding(root.id, original), ast.ClassDef | ast.alias)
+        ):
+            return None
+        if root.id in self.provenance.mutated:
+            return None
+        if isinstance(expression, ast.Name):
+            declaration = _declared_class(self.context.tree, expression.id)
+            if declaration is not None:
+                return declaration, self.context.module_imports
+        return self._imported_annotation(expression)
+
+    def _imported_annotation(self, expression: ast.expr) -> tuple[ast.ClassDef, ImportIndex] | None:
+        if self.project is None or self.context.tree is None:
+            return None
+        unit = self.project.unit_or_source(self.context.path, self.context.source, self.context.tree)
+        symbol = ProjectIndexSet.resolve(unit, expression) if unit is not None else None
+        owner = self.project.source_unit(symbol.module) if symbol is not None else None
+        if symbol is None or owner is None or owner.tree is None or is_generated(owner.path, owner.source):
+            return None
+        declaration = _declared_class(owner.tree, symbol.name)
+        if declaration is None:
+            return None
+        from sarj_python_lint._file_context import PythonFileContext  # ruff: ignore[import-outside-top-level] -- defer to avoid the rule registry's context import cycle.
+
+        definition = PythonFileContext(owner.path, owner.source, self.context.session)
+        provenance = ResourceProvenance(definition)
+        if provenance.binding(symbol.name, declaration) is not declaration or symbol.name in provenance.mutated:
+            return None
+        return declaration, definition.module_imports
+
+
+def _writes_self_attribute(node: ast.AST, attribute: str) -> bool:
+    return (
+        isinstance(node, ast.Attribute)
+        and node.attr == attribute
+        and isinstance(node.value, ast.Name)
+        and node.value.id == "self"
+        and isinstance(node.ctx, ast.Store | ast.Del)
+    )
+
+
+def _injected_parameter(constructor: Function, value: ast.Name, provenance: ResourceProvenance) -> ast.expr | None:
+    parameter = next(
+        (
+            arg
+            for arg in (*constructor.args.posonlyargs, *constructor.args.args, *constructor.args.kwonlyargs)
+            if arg.arg == value.id
+        ),
+        None,
+    )
+    if parameter is None or provenance.binding(parameter.arg, value) is not parameter:
+        return None
+    return parameter.annotation
+
+
+def _declared_class(tree: ast.Module, name: str) -> ast.ClassDef | None:
+    candidates = [node for node in tree.body if isinstance(node, ast.ClassDef) and node.name == name]
+    return candidates[0] if len(candidates) == 1 and not candidates[0].decorator_list else None
+
+
+def sql_query(node: ast.expr, imports: ImportIndex) -> exp.Expr | None:
+    if (
+        isinstance(node, ast.Call)
+        and imports.resolved_qualified_name(node.func) == "psycopg.sql.SQL"
+        and len(node.args) == 1
+        and not node.keywords
+    ):
+        node = node.args[0]
+    if not isinstance(node, ast.Constant) or not isinstance(node.value, str):
+        return None
+    try:
+        statements = sqlglot.parse(node.value, read="postgres")
+    except SqlglotError:
+        return None
+    return statements[0] if len(statements) == 1 else None
+
+
+def executed_queries(method: Function, imports: ImportIndex) -> list[exp.Expr]:
+    queries: list[exp.Expr] = []
+    calls = [
+        node
+        for statement in method.body
+        if not isinstance(statement, ast.FunctionDef | ast.AsyncFunctionDef | ast.ClassDef)
+        for node in own_nodes(statement)
+        if isinstance(node, ast.Call)
+        and isinstance(node.func, ast.Attribute)
+        and node.func.attr in {"execute", "executemany"}
+    ]
+    for call in calls:
+        if not call.args or (query := sql_query(call.args[0], imports)) is None:
+            return []
+        queries.append(query)
+    return queries
+
+
+def sql_arg(node: exp.Expr, key: str) -> exp.Expr | None:
+    return next((child for child in node.iter_expressions() if child.arg_key == key), None)
+
+
+def sql_args(node: exp.Expr, key: str) -> tuple[exp.Expr, ...]:
+    return tuple(child for child in node.iter_expressions() if child.arg_key == key)
+
+
+def sql_identifier(node: exp.Expr | None) -> str | None:
+    if isinstance(node, exp.Column):
+        node = sql_arg(node, "this")
+    if not isinstance(node, exp.Identifier):
+        return None
+    return node.name if node.quoted else node.name.lower()
+
+
+def sql_table(node: exp.Expr | None) -> tuple[str | None, ...] | None:
+    if not isinstance(node, exp.Table) or sql_arg(node, "alias") is not None:
+        return None
+    return tuple(
+        sql_identifier(value) if (value := sql_arg(node, key)) is not None else None
+        for key in ("catalog", "db", "this")
+    )