sarj-python-lint 1.61.0__tar.gz → 1.62.0__tar.gz

{sarj_python_lint-1.61.0 → sarj_python_lint-1.62.0}/PKG-INFO

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

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

sarj_python_lint-1.62.0/src/sarj_python_lint/cast_access.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Literal
+
+from sarj_python_lint._file_context import PythonFileContext
+from sarj_python_lint.rules._resource_provenance import ResourceProvenance
+
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+_TYPING = frozenset({"typing", "typing_extensions"})
+_GETATTR_ARITIES = frozenset({2, 3})
+
+
+@dataclass(frozen=True, slots=True)
+class CastAccess:
+    node: ast.Call | ast.ImportFrom
+    qualified_api: str
+    kind: Literal["wildcard", "reflection"]
+
+
+def indirect_typing_cast_accesses(path: Path, source: str) -> tuple[CastAccess, ...]:
+    context = PythonFileContext(path, source)
+    if "*" not in source and "getattr" not in context.symbol_source:
+        return ()
+    if context.tree is None:
+        return ()
+    accesses = [
+        CastAccess(node, f"{node.module}.cast", "wildcard")
+        for node in context.nodes(ast.ImportFrom)
+        if node.level == 0 and node.module in _TYPING and any(alias.name == "*" for alias in node.names)
+    ]
+    provenance = ResourceProvenance(context, require_static_namespace=True)
+    if provenance.wildcard or provenance.dynamic_namespace or not provenance.builtin_namespace_untouched:
+        return tuple(accesses)
+    for call in context.nodes(ast.Call):
+        if not _getattr_call(call, provenance):
+            continue
+        module = _typing_receiver(call.args[0], provenance)
+        if module is not None:
+            accesses.append(CastAccess(call, f"{module}.cast", "reflection"))
+    return tuple(sorted(accesses, key=lambda access: (access.node.lineno, access.node.col_offset)))
+
+
+def _getattr_call(call: ast.Call, provenance: ResourceProvenance) -> bool:
+    if not (
+        isinstance(call.func, ast.Name)
+        and call.func.id == "getattr"
+        and len(call.args) in _GETATTR_ARITIES
+        and not call.keywords
+        and isinstance(call.args[1], ast.Constant)
+        and call.args[1].value == "cast"
+    ):
+        return False
+    scope = provenance.scope(call.func)
+    while scope is not None:
+        if "getattr" in provenance.bindings.get(scope, {}):
+            return False
+        scope = provenance.scope(scope)
+    return True
+
+
+def _typing_receiver(node: ast.expr, provenance: ResourceProvenance) -> str | None:
+    if not isinstance(node, ast.Name) or node.id in provenance.mutated | provenance.external_bindings:
+        return None
+    binding = provenance.binding(node.id, node)
+    if not (
+        isinstance(binding, ast.alias)
+        and isinstance(provenance.context.parents.get(binding), ast.Import)
+        and binding.name in _TYPING
+    ):
+        return None
+    for read in provenance.reads.get(node.id, ()):
+        if provenance.binding(read.id, read) is not binding:
+            continue
+        parent = provenance.context.parents.get(read)
+        if isinstance(parent, ast.Attribute) and parent.value is read:
+            continue
+        if isinstance(parent, ast.Call) and _getattr_call(parent, provenance) and parent.args[0] is read:
+            continue
+        return None
+    return binding.name

{sarj_python_lint-1.61.0 → sarj_python_lint-1.62.0}/src/sarj_python_lint/rules/_registry.py

@@ -44,6 +44,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_dual_shape_model_field_reader import NoDualShapeModelFieldReader
 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
@@ -307,6 +308,7 @@ REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
         RequireKeywordOnlySwapProneParams.id: RequireKeywordOnlySwapProneParams,
         RequirePydanticForExternalJson.id: RequirePydanticForExternalJson,
         RequirePydanticForMappingShape.id: RequirePydanticForMappingShape,
+        NoDualShapeModelFieldReader.id: NoDualShapeModelFieldReader,
         PreferModuleLevelConstant.id: PreferModuleLevelConstant,
         PreferImmutableModuleConstant.id: PreferImmutableModuleConstant,
         PreferInjectedDependencyOverMonkeypatch.id: PreferInjectedDependencyOverMonkeypatch,

{sarj_python_lint-1.61.0 → sarj_python_lint-1.62.0}/src/sarj_python_lint/rules/duplicate_adjacent_exception_handler.py

@@ -3,10 +3,10 @@ from __future__ import annotations
 import ast
 import builtins
 from pathlib import PurePosixPath
+from types import MappingProxyType
 from typing import (
     TYPE_CHECKING,
     ClassVar,
-    cast,  # ruff: ignore[banned-api] -- vars exposes Any; the object view permits isinstance narrowing.
     final,
     override,
 )
@@ -31,14 +31,12 @@ from sarj_python_lint.rules._suppression_comments import scan_comments
 
 
 if TYPE_CHECKING:
-    from collections.abc import Mapping
-
     from sarj_python_lint._file_context import PythonFileContext
     from sarj_python_lint.rules._project_index import SourceUnit, SymbolRef
     from sarj_python_lint.rules._suppression_comments import Comment
 
 
-_BUILTIN_NAMESPACE = cast("Mapping[str, object]", vars(builtins))
+_BUILTIN_NAMESPACE = MappingProxyType[str, object](vars(builtins))
 _BUILTIN_EXCEPTIONS = frozenset(
     name for name, value in _BUILTIN_NAMESPACE.items() if isinstance(value, type) and issubclass(value, Exception)
 )

{sarj_python_lint-1.61.0 → sarj_python_lint-1.62.0}/src/sarj_python_lint/rules/no_any_mapping_types.py

@@ -117,6 +117,34 @@ class NoAnyMappingTypes(Rule):
                 expected_count=0,
                 public=True,
             ),
+            RuleExample(
+                example_id="generic-any-binding",
+                scenario="provider-identity",
+                title="A generic parameter named Any keeps its own identity",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app/service.py", "from typing import Any\nclass Rows[Any]:\n    rows: dict[str, Any]\n"
+                    ),
+                ),
+                focus_path=PurePosixPath("app/service.py"),
+                expected_count=0,
+                public=True,
+            ),
+            RuleExample(
+                example_id="generic-typing-any",
+                scenario="provider-identity",
+                title="An unrelated generic parameter preserves actual Any erasure",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app/service.py", "from typing import Any\nclass Rows[T]:\n    rows: dict[str, Any]\n"
+                    ),
+                ),
+                focus_path=PurePosixPath("app/service.py"),
+                expected_count=1,
+                public=True,
+            ),
         ),
     )
     description = documentation.summary
@@ -236,11 +264,12 @@ def _unshadowed_any_mappings(
     if parsed is None:
         return []
     names = {node.id for node in walk_ast(parsed) if isinstance(node, ast.Name)}
-    if not names.isdisjoint(_shadowed_names(owner, parents, scope_cache)):
+    type_parameters = frozenset(_generic_scope_names(owner, parents))
+    if not names.isdisjoint(_shadowed_names(owner, parents, scope_cache) - type_parameters):
         return []
     return [
         (mapping, expression if isinstance(expression, ast.Constant) else mapping)
-        for mapping in _any_mappings(expression, semantics)
+        for mapping in _any_mappings(expression, semantics, shadowed=type_parameters)
     ]
 
 
@@ -546,12 +575,39 @@ def _unshadowed_type_expression(
     return names.isdisjoint(_shadowed_names(node, parents, scope_cache))
 
 
+def _generic_scope_names(node: ast.AST, parents: dict[int, ast.AST]) -> set[str]:
+    names = _type_parameter_names(node)
+    below = node
+    parent = parents.get(id(below))
+    function_default = False
+    while parent is not None:
+        match parent:
+            case ast.arguments():
+                function_default = below in parent.defaults or below in parent.kw_defaults
+            case ast.FunctionDef() | ast.AsyncFunctionDef():
+                if not function_default and below not in parent.decorator_list:
+                    names.update(_type_parameter_names(parent))
+                function_default = False
+            case ast.Lambda():
+                function_default = False
+            case ast.ClassDef():
+                if below not in parent.decorator_list:
+                    names.update(_type_parameter_names(parent))
+            case ast.TypeAlias():
+                names.update(_type_parameter_names(parent))
+            case _:
+                pass
+        below = parent
+        parent = parents.get(id(below))
+    return names
+
+
 def _shadowed_names(
     node: ast.AST,
     parents: dict[int, ast.AST],
     scope_cache: dict[int, frozenset[str]],
 ) -> set[str]:
-    shadowed: set[str] = set()
+    shadowed = _generic_scope_names(node, parents)
     crossed_function_body = False
     below = node
     parent = parents.get(id(below))
@@ -567,6 +623,16 @@ def _shadowed_names(
     return shadowed
 
 
+def _type_parameter_names(node: ast.AST) -> set[str]:
+    if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef, ast.TypeAlias)):
+        return {
+            parameter.name
+            for parameter in node.type_params
+            if isinstance(parameter, (ast.TypeVar, ast.ParamSpec, ast.TypeVarTuple))
+        }
+    return set()
+
+
 def _scope_names(
     owner: ast.FunctionDef | ast.AsyncFunctionDef | ast.ClassDef,
     cache: dict[int, frozenset[str]],
@@ -628,7 +694,9 @@ def _type_comment(comment: str, owner: ast.AST) -> ast.expr | None:
     return expression
 
 
-def _any_mappings(annotation: ast.expr, semantics: AnnotationSemantics) -> list[ast.Subscript]:
+def _any_mappings(
+    annotation: ast.expr, semantics: AnnotationSemantics, *, shadowed: frozenset[str] = frozenset()
+) -> list[ast.Subscript]:
     resolved = semantics.parse(annotation)
     if resolved is None:
         return []
@@ -636,24 +704,30 @@ def _any_mappings(annotation: ast.expr, semantics: AnnotationSemantics) -> list[
     mappings: list[ast.Subscript] = []
     while pending:
         node = pending.pop()
-        if isinstance(node, ast.Subscript) and _is_any_mapping(node, semantics):
+        if isinstance(node, ast.Subscript) and _is_any_mapping(node, semantics, shadowed=shadowed):
             mappings.append(node)
-        pending.extend(_type_children(node, semantics))
+        pending.extend(_type_children(node, semantics, shadowed=shadowed))
     return mappings
 
 
-def _is_any_mapping(node: ast.Subscript, semantics: AnnotationSemantics) -> bool:
+def _is_any_mapping(node: ast.Subscript, semantics: AnnotationSemantics, *, shadowed: frozenset[str]) -> bool:
     if not isinstance(node.slice, ast.Tuple) or len(node.slice.elts) != _MAPPING_ARGUMENT_COUNT:
         return False
     imports = semantics.imports
     target = node.value
+    if _expression_root(target) in shadowed:
+        return False
     mapping = (isinstance(target, ast.Name) and target.id == "dict" and imports.builtin_is_unshadowed("dict")) or any(
         imports.resolves(target, sources=_MAPPING_SOURCES, symbol=name) for name in _MAPPING_NAMES
     )
     if not mapping:
         return False
     key, value = node.slice.elts
-    return _is_builtin_str(key, imports) and _contains_any(value, semantics, seen=frozenset())
+    return (
+        _expression_root(key) not in shadowed
+        and _is_builtin_str(key, imports)
+        and _contains_any(value, semantics, seen=frozenset(), shadowed=shadowed)
+    )
 
 
 def _is_builtin_str(node: ast.expr, imports: ImportIndex) -> bool:
@@ -665,20 +739,30 @@ def _contains_any(
     semantics: AnnotationSemantics,
     *,
     seen: frozenset[str],
+    shadowed: frozenset[str] = frozenset(),
 ) -> bool:
     parsed = semantics.parse(node)
-    if parsed is None:
+    if parsed is None or _expression_root(parsed) in shadowed:
         return False
     imports = semantics.imports
     if imports.resolves(parsed, sources=_TYPING_SOURCES, symbol="Any"):
         return True
     if isinstance(parsed, ast.Name) and parsed.id in semantics.aliases and parsed.id not in seen:
+        # Module aliases retain their declaration scope, independent of a
+        # generic name at this annotation's use site.
         return _contains_any(semantics.aliases[parsed.id], semantics, seen=seen | {parsed.id})
-    return any(_contains_any(child, semantics, seen=seen) for child in _type_children(parsed, semantics))
+    return any(
+        _contains_any(child, semantics, seen=seen, shadowed=shadowed)
+        for child in _type_children(parsed, semantics, shadowed=shadowed)
+    )
 
 
-def _type_children(node: ast.expr, semantics: AnnotationSemantics) -> tuple[ast.expr, ...]:
+def _type_children(
+    node: ast.expr, semantics: AnnotationSemantics, *, shadowed: frozenset[str] = frozenset()
+) -> tuple[ast.expr, ...]:
     if isinstance(node, ast.Subscript):
+        if _expression_root(node.value) in shadowed:
+            return ()
         imports = semantics.imports
         symbol = imports.resolved_symbol(node.value, sources=_TYPING_SOURCES | _MAPPING_SOURCES)
         if symbol == "Literal":