sarj-python-lint 1.28.4__tar.gz → 1.28.6__tar.gz

{sarj_python_lint-1.28.4 → sarj_python_lint-1.28.6}/PKG-INFO

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

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

{sarj_python_lint-1.28.4 → sarj_python_lint-1.28.6}/src/sarj_python_lint/_file_context.py

@@ -67,6 +67,17 @@ class PythonFileContext:
 
         return consumed_docstring_names(self._valid_tree(), node_index=self.node_index)
 
+    @cached_property
+    def docstring_node_ids(self) -> frozenset[int]:
+        result: set[int] = set()
+        for owner in self.nodes(ast.Module, ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef):
+            if not owner.body or not isinstance(owner.body[0], ast.Expr):
+                continue
+            value = owner.body[0].value
+            if isinstance(value, ast.Constant) and isinstance(value.value, str):
+                result.add(id(value))
+        return frozenset(result)
+
     @property
     def parents(self) -> Mapping[ast.AST, ast.AST]:
         return self.node_index.parents

{sarj_python_lint-1.28.4 → sarj_python_lint-1.28.6}/src/sarj_python_lint/rules/complex_postgres_query_requires_architecture_review.py

@@ -71,18 +71,6 @@ class _ConstructorImport(NamedTuple):
     name: str
 
 
-def _docstring_node_ids(tree: ast.AST, *, node_index: NodeIndex | None = None) -> set[int]:
-    result: set[int] = set()
-    for owner in nodes(tree, ast.Module, ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef, index=node_index):
-        body = owner.body
-        if not body or not isinstance(body[0], ast.Expr):
-            continue
-        value = body[0].value
-        if isinstance(value, ast.Constant) and isinstance(value.value, str):
-            result.add(id(value))
-    return result
-
-
 def _is_query_context(node: ast.expr, parents: Mapping[ast.AST, ast.AST], roots: frozenset[int]) -> bool:
     current: ast.AST = node
     while True:
@@ -368,7 +356,7 @@ class ComplexPostgresQueryRequiresArchitectureReview(Rule):
         if not _is_postgres_module(tree, node_index=context.node_index):
             return []
 
-        docstrings = _docstring_node_ids(tree, node_index=context.node_index)
+        docstrings = context.docstring_node_ids
         parents = context.parents
         query_roots = _query_roots(tree, parents, node_index=context.node_index)
         diagnostics: list[Diagnostic] = []

{sarj_python_lint-1.28.4 → sarj_python_lint-1.28.6}/src/sarj_python_lint/rules/defect_xfail_requires_explicit_strict.py

@@ -64,13 +64,16 @@ class DefectXfailRequiresExplicitStrict(Rule):
         ),
         remediation=(
             "Set literal `strict=True` so an unexpected pass fails. If only some parameter cases carry the defect, "
-            "move the marker to those `pytest.param(...)` cases before making it strict."
+            "move the marker to those `pytest.param(...)` cases before making it strict. When the defect's exception "
+            "type or group shape is independently known, native `raises=...`, where supported, can narrow unrelated failures; "
+            "same-type failures still need an origin oracle. Keep intentional broad expected-failure policies."
         ),
         category=RuleCategory.TESTING,
         aliases=("defect-xfail-requires-strict", "xfail-requires-strict"),
         limitations=(
             "Only markers resolved through an unambiguous pytest or pytest.mark import are analyzed.",
             "Only xfail reasons that explicitly identify a defect are analyzed.",
+            "Exception narrowing and defect identity remain manual review; strictness or a typed marker alone does not establish failure origin.",
             "Nondeterministic, recognized Hypothesis, network, environment-gated, run=False, and statically disabled pins are excluded.",
             "Repository-level strict_xfail / xfail_strict configuration is intentionally not consulted: defect pins remain locally explicit.",
             "Default pytest test_/Test collection names are recognized; repositories with custom collection patterns may need a local suppression.",

{sarj_python_lint-1.28.4 → sarj_python_lint-1.28.6}/src/sarj_python_lint/rules/no_analytical_aggregation_in_postgres_store.py

@@ -16,7 +16,7 @@ from sarj_python_lint.rule_base import (
     RuleExample,
     Severity,
 )
-from sarj_python_lint.rules._ast_index import nodes, walk
+from sarj_python_lint.rules._ast_index import walk
 from sarj_python_lint.rules._sql import is_store_module, sql_string_value, strip_sql_noise
 
 
@@ -24,7 +24,6 @@ if TYPE_CHECKING:
     from sqlglot import exp
 
     from sarj_python_lint._file_context import PythonFileContext
-    from sarj_python_lint.rules._ast_index import NodeIndex
 
 
 _QUERY_SHAPE = re.compile(r"\bSELECT\b[\s\S]*?\bFROM\b", re.IGNORECASE)
@@ -65,18 +64,6 @@ _STRONG_ANALYTICAL: tuple[tuple[str, re.Pattern[str]], ...] = (
 )
 
 
-def _docstring_node_ids(tree: ast.AST, *, node_index: NodeIndex | None = None) -> set[int]:
-    result: set[int] = set()
-    for owner in nodes(tree, ast.Module, ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef, index=node_index):
-        body = owner.body
-        if not body or not isinstance(body[0], ast.Expr):
-            continue
-        value = body[0].value
-        if isinstance(value, ast.Constant) and isinstance(value.value, str):
-            result.add(id(value))
-    return result
-
-
 def analytical_signal(sql: str) -> str | None:
     if _LOCKING_READ.search(sql) is not None:
         return None
@@ -217,7 +204,7 @@ class NoAnalyticalAggregationInPostgresStore(Rule):
         if tree is None:
             return []
 
-        docstrings = _docstring_node_ids(tree, node_index=context.node_index)
+        docstrings = context.docstring_node_ids
         diagnostics: list[Diagnostic] = []
         consumed: set[int] = set()
         for node in context.nodes(ast.Constant, ast.BinOp):

{sarj_python_lint-1.28.4 → sarj_python_lint-1.28.6}/src/sarj_python_lint/rules/no_offset_pagination.py

@@ -16,13 +16,12 @@ from sarj_python_lint.rule_base import (
     RuleExample,
     Severity,
 )
-from sarj_python_lint.rules._ast_index import nodes, walk
+from sarj_python_lint.rules._ast_index import walk
 from sarj_python_lint.rules._sql import is_store_module, sql_string_value, strip_sql_noise
 
 
 if TYPE_CHECKING:
     from sarj_python_lint._file_context import PythonFileContext
-    from sarj_python_lint.rules._ast_index import NodeIndex
 
 
 _DYNAMIC_VALUE = r"(?:%s|%\(\w+\)s|\?\d*|:\w+|@\w+|\$\d+|:__sarj_dynamic__)"
@@ -107,7 +106,7 @@ class NoOffsetPagination(Rule):
 
         diags: list[Diagnostic] = []
         consumed: set[int] = set()
-        docstrings = _docstring_node_ids(tree, node_index=context.node_index)
+        docstrings = context.docstring_node_ids
         for node in context.nodes(ast.Constant, ast.BinOp, ast.JoinedStr):
             if id(node) in consumed or id(node) in docstrings:
                 continue
@@ -151,17 +150,6 @@ def _sql_value(node: ast.expr) -> str | None:
     return sql_string_value(node)
 
 
-def _docstring_node_ids(tree: ast.Module, *, node_index: NodeIndex | None = None) -> set[int]:
-    result: set[int] = set()
-    for owner in nodes(tree, ast.Module, ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef, index=node_index):
-        if not owner.body or not isinstance(owner.body[0], ast.Expr):
-            continue
-        value = owner.body[0].value
-        if isinstance(value, ast.Constant) and isinstance(value.value, str):
-            result.add(id(value))
-    return result
-
-
 def _mask_dialect_noise(sql: str) -> str:
     sql = _QUOTED_IDENTIFIER.sub(lambda match: " " * len(match.group(0)), sql)
     return _MYSQL_COMMENT.sub(lambda match: " " * len(match.group(0)), sql)

{sarj_python_lint-1.28.4 → sarj_python_lint-1.28.6}/src/sarj_python_lint/rules/prefer_fstring_over_concat.py

@@ -124,13 +124,16 @@ class PreferFstringOverConcat(Rule):
         summary="Prefer f-strings for short human-readable interpolation when they make the result clearer.",
         rationale="For prose-like strings, f-strings keep interpolated values and surrounding text visible together.",
         remediation=(
-            "Replace the interpolation with one f-string. Preserve an explicit `str(value)` conversion as `{value!s}` "
-            "and `repr(value)` as `{value!r}` when those conversion semantics matter."
+            "Use one f-string when it preserves the required conversion and operator semantics. Preserve an explicit "
+            "`str(value)` conversion as `{value!s}` "
+            "and `repr(value)` as `{value!r}` when those conversion semantics matter. Retain required custom "
+            "concatenation or formatting behavior; a `str` annotation alone does not prove equivalence."
         ),
         category=RuleCategory.STYLE,
         autofix=AutofixPolicy.NONE,
         limitations=(
             "Runtime operands must have concrete string evidence.",
+            "String evidence does not prove that custom concatenation operators and `__format__` agree; this remains manual review.",
             (
                 "Logging, common direct SQL and regular-expression forms, lazy strings, ORM expressions, generated files, long "
                 "literals, and punctuation-oriented fragment composition are excluded."

{sarj_python_lint-1.28.4 → sarj_python_lint-1.28.6}/src/sarj_python_lint/rules/prefer_injected_dependency_over_monkeypatch.py

@@ -55,7 +55,9 @@ class PreferInjectedDependencyOverMonkeypatch(Rule):
             "fake when rebuilding the fixture would add wiring without improving the boundary. Keep attribute-existence "
             "checks enabled and the tested implementation intact. Suppress SARJ445 only at that call, naming the "
             "owned instance and injection seam. For inherently global boundaries or lookup interception, explain why "
-            "injection would invalidate the test. Do not switch to bare assignment merely to avoid this rule."
+            "injection would invalidate the test. Establish the binding the exercised consumer actually reads, "
+            "including already-bound import aliases, and show that the oracle rejects a wrong consumer. "
+            "Do not switch to bare assignment merely to avoid this rule."
         ),
         category=RuleCategory.TESTING,
         autofix=AutofixPolicy.NONE,
@@ -65,7 +67,7 @@ class PreferInjectedDependencyOverMonkeypatch(Rule):
             "Environment, mapping, import-path, and working-directory mutations are intentionally allowed.",
             "Untyped handles are recognized only on pytest tests or fixtures; directly parametrized values are excluded.",
             "A nested function that captures a monkeypatch handle from an outer scope is not inferred.",
-            "Instance ownership and collaborator contracts are not inferred; justified scoped patches need a local suppression.",
+            "Instance ownership, collaborator contracts, and active consumer lookups are not inferred; justified scoped patches need a local suppression.",
         ),
         examples=(
             RuleExample(

{sarj_python_lint-1.28.4 → sarj_python_lint-1.28.6}/src/sarj_python_lint/rules/require_precise_factory_signature.py

@@ -35,7 +35,7 @@ class RequirePreciseFactorySignature(ProjectRule):
     documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
         default_level=Severity.WARNING,
         summary="Keep fixed keyword factory calls behind a precise callable signature.",
-        rationale="Callable[..., T] erases argument checking, so misspelled keywords and incompatible injected factories pass strict typing and can fail at runtime.",
+        rationale="Callable[..., T] and functools.partial[T] erase argument checking at injected boundaries, so misspelled keywords and incompatible factories pass strict typing and can fail at runtime.",
         remediation=(
             "If factory substitution is unnecessary, call the existing constructor directly. Otherwise reuse an "
             "existing precise callable contract; use type[T] when the dependency requires a class, accounting "
@@ -46,7 +46,7 @@ class RequirePreciseFactorySignature(ProjectRule):
         category=RuleCategory.ARCHITECTURE,
         autofix=AutofixPolicy.NONE,
         limitations=(
-            "Only undecorated module-level functions with proven standard Callable[..., OwnedClass] parameters directly called with at least one named keyword are considered. Imported classes require scanned first-party declarations.",
+            "Only undecorated module-level functions with proven standard Callable[..., OwnedClass] or functools.partial[OwnedClass] parameters directly called with at least one named keyword are considered. Imported classes require scanned first-party declarations; direct partial construction and calls remain native type-checker ownership.",
             "Tests, test support, generated code, unresolved/string/generic annotations, positional-only calls, unpacking, forwarding, nested captures, rebinding and ambiguous imports are excluded. Import capture checks are conservative across the file, so an unrelated local pattern, exception or walrus binding can prevent a warning.",
             "A fixed call demonstrates signature erasure, not a current runtime defect. Genuine dynamic APIs can use a reasoned suppression. No autofix: the correct contract depends on whether classes or function factories are intended.",
         ),
@@ -65,6 +65,36 @@ class RequirePreciseFactorySignature(ProjectRule):
                 expected_count=1,
                 public=True,
             ),
+            RuleExample(
+                example_id="erased-partial-factory",
+                title="An injected partial retains its result type but loses argument checking",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app/service.py",
+                        "from functools import partial\nclass Result: pass\ndef build(factory: partial[Result]):\n    return factory(size=4)\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("app/service.py"),
+                expected_count=1,
+                scenario="partial-erasure",
+                public=True,
+            ),
+            RuleExample(
+                example_id="direct-partial-factory",
+                title="Direct partial construction keeps native argument checking",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app/service.py",
+                        "from functools import partial\nclass Result:\n    def __init__(self, *, size: int):\n        self.size = size\ndef build():\n    factory = partial(Result)\n    return factory(size=4)\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("app/service.py"),
+                expected_count=0,
+                scenario="partial-erasure",
+                public=True,
+            ),
             RuleExample(
                 example_id="exact-factory",
                 title="Factory declares its keyword contract",
@@ -113,7 +143,7 @@ class RequirePreciseFactorySignature(ProjectRule):
                         col=argument.col_offset + 1,
                         code=self.code,
                         message=(
-                            f"`{argument.arg}` is called with fixed keywords but Callable[..., T] erases its "
+                            f"`{argument.arg}` is called with fixed keywords but its factory annotation erases its "
                             "argument contract; remove unnecessary factory indirection or reuse a precise callable "
                             "contract that preserves the accepted keywords."
                         ),
@@ -124,19 +154,20 @@ class RequirePreciseFactorySignature(ProjectRule):
 
 
 def _factory_result(annotation: ast.expr | None, context: PythonFileContext) -> ast.Name | ast.Attribute | None:
-    if (
-        not isinstance(annotation, ast.Subscript)
-        or context.module_imports.resolved_qualified_name(annotation.value) not in _CALLABLES
-    ):
+    if not isinstance(annotation, ast.Subscript):
         return None
-    if not isinstance(annotation.slice, ast.Tuple) or len(annotation.slice.elts) != _CALLABLE_ARITY:
+    carrier = context.module_imports.resolved_qualified_name(annotation.value)
+    if carrier in _CALLABLES:
+        if not isinstance(annotation.slice, ast.Tuple) or len(annotation.slice.elts) != _CALLABLE_ARITY:
+            return None
+        parameters, result = annotation.slice.elts
+        if not isinstance(parameters, ast.Constant) or parameters.value is not Ellipsis:
+            return None
+    elif carrier == "functools.partial":
+        result = annotation.slice
+    else:
         return None
-    parameters, result = annotation.slice.elts
-    if (
-        not isinstance(parameters, ast.Constant)
-        or parameters.value is not Ellipsis
-        or not isinstance(result, (ast.Name, ast.Attribute))
-    ):
+    if not isinstance(result, (ast.Name, ast.Attribute)):
         return None
     root = _root(annotation.value)
     if (root is not None and _captured_import_root(root, context)) or any(