sarj-python-lint 1.16.3__tar.gz → 1.16.4__tar.gz

{sarj_python_lint-1.16.3 → sarj_python_lint-1.16.4}/PKG-INFO

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

{sarj_python_lint-1.16.3 → sarj_python_lint-1.16.4}/pyproject.toml

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

{sarj_python_lint-1.16.3 → sarj_python_lint-1.16.4}/src/sarj_python_lint/rules/prefer_match_type_dispatch.py

@@ -101,7 +101,8 @@ class PreferMatchTypeDispatch(Rule):
         limitations=(
             "General dispatch requires three or more adjacent, unguarded `isinstance` branches over the same simple name. Two arms are checked only for an exact `ast.Name.id` / `ast.Attribute.attr` projection followed by a None-returning fallback.",
             "A terminating sibling prefix may precede a two-arm if/elif tail whose bodies can fall through. Preserve nested checks inside case bodies rather than moving them into case guards.",
-            "The checked types must be unshadowed builtins, undecorated module-local classes without an explicit metaclass, or proven stdlib ast classes; unresolved imports, runtime type groups, repeated type references, generated files, and non-terminating sibling checks are excluded.",
+            "The checked types must be unshadowed builtins, undecorated module-local classes without an explicit or known locally inherited custom metaclass, or proven stdlib ast classes; unresolved imports, runtime type groups, repeated type references, generated files, and non-terminating sibling checks are excluded.",
+            "Local ancestry must resolve to stable undeclared-metaclass classes or proven builtin/stdlib ast bases. External bases, runtime base aliases, and parameterized base expressions remain excluded because their metaclass or __class_getitem__ effects are unproven.",
             "Nested attribute-validation guards are excluded: converting them to keyword class patterns can turn attribute errors into match fallthrough, and an imported isinstance operand may be a runtime tuple rather than a class.",
             "A terminal-looking context-manager body does not prove a sibling branch terminates: exceptions can be suppressed. An unconditional return or raise after the context manager remains eligible.",
             "Declared support for Python before 3.10 suppresses this recommendation when proven by the nearest project metadata or exact installed-distribution ownership. Missing or ambiguous target metadata retains advisory behavior; it does not prove a modern target.",
@@ -239,20 +240,20 @@ class PreferMatchTypeDispatch(Rule):
             return []
         imports = context.imports
         all_nodes = tuple(context.nodes(ast.AST))
-        unsafe_bindings = _unsafe_local_bound_names(tree, all_nodes) | frozenset(
+        unsafe_bindings = _unsafe_local_bound_names(tree, all_nodes, imports) | frozenset(
             qualified
             for node in all_nodes
             if isinstance(node, ast.Attribute)
             and isinstance(node.ctx, (ast.Store, ast.Del))
             and (qualified := imports.resolved_qualified_name(node)) is not None
-            and qualified.startswith("ast.")
+            and qualified.startswith(("ast.", "builtins."))
         )
         has_wildcard_import = any(
             isinstance(node, ast.ImportFrom) and any(alias.name == "*" for alias in node.names) for node in all_nodes
         )
         if not imports.builtin_is_unshadowed("isinstance") or "isinstance" in unsafe_bindings or has_wildcard_import:
             return []
-        local_classes = _unshadowed_module_classes(tree, all_nodes)
+        local_classes = _unshadowed_module_classes(tree, all_nodes, imports, unsafe_bindings)
         findings = _ladder_findings(
             all_nodes,
             path,
@@ -287,14 +288,10 @@ class PreferMatchTypeDispatch(Rule):
         return findings
 
 
-def _unshadowed_module_classes(tree: ast.Module, all_nodes: tuple[ast.AST, ...]) -> frozenset[str]:
-    classes = [
-        statement.name
-        for statement in tree.body
-        if isinstance(statement, ast.ClassDef)
-        and not statement.decorator_list
-        and not any(keyword.arg in {"metaclass", None} for keyword in statement.keywords)
-    ]
+def _unshadowed_module_classes(
+    tree: ast.Module, all_nodes: tuple[ast.AST, ...], imports: ImportIndex, unsafe_bindings: frozenset[str]
+) -> frozenset[str]:
+    declarations = [statement for statement in tree.body if isinstance(statement, ast.ClassDef)]
     rebound: set[str] = set()
     for node in all_nodes:
         match node:
@@ -310,17 +307,83 @@ def _unshadowed_module_classes(tree: ast.Module, all_nodes: tuple[ast.AST, ...])
             case _:
                 pass
     _add_module_import_bindings(tree, rebound)
-    return frozenset(name for name in classes if classes.count(name) == 1 and name not in rebound)
+    names = [declaration.name for declaration in declarations]
+    stable = [
+        declaration
+        for declaration in declarations
+        if names.count(declaration.name) == 1 and declaration.name not in rebound
+    ]
+    nominal = _nominal_class_ancestry(stable, imports, unsafe_bindings)
+    return frozenset(
+        declaration.name
+        for declaration in stable
+        if declaration.name in nominal
+        and not any(keyword.arg in {"metaclass", None} for keyword in declaration.keywords)
+    )
 
 
-def _unsafe_local_bound_names(tree: ast.Module, all_nodes: tuple[ast.AST, ...]) -> frozenset[str]:
-    module_imports = {id(statement) for statement in tree.body if isinstance(statement, (ast.Import, ast.ImportFrom))}
-    names = {
-        alias.asname or alias.name.partition(".")[0]
-        for statement in all_nodes
-        if isinstance(statement, (ast.Import, ast.ImportFrom)) and id(statement) not in module_imports
-        for alias in statement.names
-    }
+def _nominal_class_ancestry(
+    declarations: list[ast.ClassDef], imports: ImportIndex, unsafe_bindings: frozenset[str]
+) -> frozenset[str]:
+    proven: frozenset[str] = frozenset()
+    while True:
+        nominal = frozenset(
+            declaration.name
+            for declaration in declarations
+            if not declaration.decorator_list
+            and not _unproven_metaclass_header(declaration, imports, unsafe_bindings)
+            and all(_nominal_base(base, imports, proven, unsafe_bindings) for base in declaration.bases)
+        )
+        if nominal <= proven:
+            return proven
+        proven |= nominal
+
+
+def _nominal_base(
+    expression: ast.expr, imports: ImportIndex, local_classes: frozenset[str], unsafe_bindings: frozenset[str]
+) -> bool:
+    if isinstance(expression, ast.Subscript):
+        return False
+    return _type_reference(expression, imports, local_classes, unsafe_bindings) is not None or (
+        _builtin_class_reference(expression, imports, unsafe_bindings) is not None
+    )
+
+
+def _unproven_metaclass_header(
+    declaration: ast.ClassDef, imports: ImportIndex, unsafe_bindings: frozenset[str]
+) -> bool:
+    for keyword in declaration.keywords:
+        if keyword.arg is None:
+            return True
+        if keyword.arg != "metaclass":
+            continue
+        if _builtin_class_reference(keyword.value, imports, unsafe_bindings) == "type":
+            continue
+        return True
+    return False
+
+
+def _builtin_class_reference(expression: ast.expr, imports: ImportIndex, unsafe_bindings: frozenset[str]) -> str | None:
+    root = expression
+    while isinstance(root, ast.Attribute):
+        root = root.value
+    if not isinstance(root, ast.Name) or root.id in unsafe_bindings:
+        return None
+    if (
+        isinstance(expression, ast.Name)
+        and expression.id in _BUILTIN_TYPES
+        and imports.builtin_is_unshadowed(expression.id)
+        and f"builtins.{expression.id}" not in unsafe_bindings
+    ):
+        return expression.id
+    symbol = imports.resolved_symbol(expression, sources=frozenset({"builtins"}))
+    if symbol in _BUILTIN_TYPES and f"builtins.{symbol}" not in unsafe_bindings:
+        return symbol
+    return None
+
+
+def _unsafe_local_bound_names(tree: ast.Module, all_nodes: tuple[ast.AST, ...], imports: ImportIndex) -> frozenset[str]:
+    names = _unsafe_import_bound_names(tree, all_nodes, imports)
     names.update(
         candidate.name
         for candidate in all_nodes
@@ -334,6 +397,31 @@ def _unsafe_local_bound_names(tree: ast.Module, all_nodes: tuple[ast.AST, ...])
     return frozenset(names)
 
 
+def _unsafe_import_bound_names(tree: ast.Module, all_nodes: tuple[ast.AST, ...], imports: ImportIndex) -> set[str]:
+    module_imports = {id(statement) for statement in tree.body if isinstance(statement, (ast.Import, ast.ImportFrom))}
+    names: set[str] = set()
+    for statement in all_nodes:
+        if not isinstance(statement, (ast.Import, ast.ImportFrom)):
+            continue
+        relative = isinstance(statement, ast.ImportFrom) and statement.level > 0
+        if id(statement) in module_imports and not relative:
+            continue
+        for alias in statement.names:
+            if not _preserves_indexed_import(statement, alias, imports):
+                names.add(alias.asname or alias.name.partition(".")[0])
+    return names
+
+
+def _preserves_indexed_import(statement: ast.Import | ast.ImportFrom, alias: ast.alias, imports: ImportIndex) -> bool:
+    local = alias.asname or alias.name.partition(".")[0]
+    target = imports.bindings.get(local)
+    if target is None:
+        return False
+    if isinstance(statement, ast.ImportFrom):
+        return not statement.level and target.module == statement.module and target.symbol == alias.name
+    return target.module == alias.name and target.symbol is None
+
+
 def _ladder_findings(
     all_nodes: tuple[ast.AST, ...],
     path: Path,
@@ -632,6 +720,7 @@ def _type_reference(
             expression.id in _BUILTIN_TYPES
             and imports.builtin_is_unshadowed(expression.id)
             and expression.id not in unsafe_bindings
+            and f"builtins.{expression.id}" not in unsafe_bindings
         ):
             return expression.id
         if expression.id in local_classes and expression.id not in unsafe_bindings:

{sarj_python_lint-1.16.3 → sarj_python_lint-1.16.4}/src/sarj_python_lint/rules/require_public_dependency_contract.py

@@ -116,7 +116,7 @@ class RequirePublicDependencyContract(ProjectRule):
         if implementation is None:
             return None
         contract = _existing_substitutable_contract(implementation, project)
-        members = _dependency_members(node, fields)
+        members = _dependency_members(node, fields, context)
         if contract is None or members is None or not members <= _public_operations(contract):
             return None
         return Diagnostic(
@@ -230,11 +230,15 @@ def _declaration(unit: SourceUnit, name: str) -> ast.ClassDef | None:
     return next((node for node in unit.tree.body if isinstance(node, ast.ClassDef) and node.name == name), None)
 
 
-def _dependency_members(node: ast.ClassDef, fields: frozenset[str]) -> frozenset[str] | None:
+def _dependency_members(
+    node: ast.ClassDef, fields: frozenset[str], context: PythonFileContext
+) -> frozenset[str] | None:
     members: set[str] = set()
     called = False
     for method in class_methods(node):
         for child in ast.walk(method):
+            if _dependency_field_escapes(child, fields, context):
+                return None
             target = child.func if isinstance(child, ast.Call) else child
             if (
                 isinstance(target, ast.Attribute)
@@ -246,3 +250,16 @@ def _dependency_members(node: ast.ClassDef, fields: frozenset[str]) -> frozenset
                 members.add(target.attr)
                 called |= isinstance(child, ast.Call) and not method.name.startswith("_")
     return frozenset(members) if called else None
+
+
+def _dependency_field_escapes(node: ast.AST, fields: frozenset[str], context: PythonFileContext) -> bool:
+    if not (
+        isinstance(node, ast.Attribute)
+        and isinstance(node.ctx, ast.Load)
+        and isinstance(node.value, ast.Name)
+        and node.value.id == "self"
+        and node.attr in fields
+    ):
+        return False
+    parent = context.parents.get(node)
+    return not (isinstance(parent, ast.Attribute) and parent.value is node)