sarj-python-lint 1.66.2__tar.gz → 1.67.0__tar.gz

{sarj_python_lint-1.66.2 → sarj_python_lint-1.67.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sarj-python-lint
-Version: 1.66.2
+Version: 1.67.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/
@@ -18,9 +18,9 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Quality Assurance
 Requires-Python: >=3.14
 Requires-Dist: packaging==26.3
-Requires-Dist: ruff>=0.17.0
-Requires-Dist: sarj-rule-contracts==0.2.5
-Requires-Dist: sqlglot==30.22.0
+Requires-Dist: ruff>=0.17.2
+Requires-Dist: sarj-rule-contracts==0.2.6
+Requires-Dist: sqlglot==30.24.0
 Requires-Dist: typer==0.27.3
 Description-Content-Type: text/markdown
 

{sarj_python_lint-1.66.2 → sarj_python_lint-1.67.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sarj-python-lint"
-version = "1.66.2"
+version = "1.67.0"
 description = "Custom Python lint rules — AST-based, pre-commit-friendly, hypermodern defaults"
 readme = "README.md"
 authors = [{ name = "sarj-ai" }]
@@ -15,7 +15,7 @@ classifiers = [
   "Programming Language :: Python :: 3.14",
   "Topic :: Software Development :: Quality Assurance",
 ]
-dependencies = ["sarj-rule-contracts==0.2.5", "packaging==26.3", "ruff>=0.17.0", "sqlglot==30.22.0", "typer==0.27.3"]
+dependencies = ["sarj-rule-contracts==0.2.6", "packaging==26.3", "ruff>=0.17.2", "sqlglot==30.24.0", "typer==0.27.3"]
 
 [project.scripts]
 sarj-python-lint = "sarj_python_lint.__main__:main"
@@ -32,7 +32,7 @@ Issues = "https://github.com/sarj-ai/code-standards/issues"
 dev = [
   "pydantic==2.14.1",
   "pytest>=9.1.1",
-  "ruff>=0.17.0",
+  "ruff>=0.17.2",
   "basedpyright>=1.40.2",
 ]
 

{sarj_python_lint-1.66.2 → sarj_python_lint-1.67.0}/src/sarj_python_lint/rules/_registry.py

@@ -219,6 +219,7 @@ if TYPE_CHECKING:
 from sarj_python_lint.rules.delete_route_returns_no_content import DeleteRouteReturnsNoContent
 from sarj_python_lint.rules.duplicate_adjacent_exception_handler import DuplicateAdjacentExceptionHandler
 from sarj_python_lint.rules.duplicate_closed_pure_helper import DuplicateClosedPureHelper
+from sarj_python_lint.rules.duplicate_pytest_fixture_params import DuplicatePytestFixtureParams
 from sarj_python_lint.rules.no_conflicting_pydantic_alias_validation import NoConflictingPydanticAliasValidation
 from sarj_python_lint.rules.no_contradictory_type_guard import NoContradictoryTypeGuard
 from sarj_python_lint.rules.no_create_verb_in_post_path import NoCreateVerbInPostPath
@@ -238,6 +239,7 @@ from sarj_python_lint.rules.no_work_verb_get_route import NoWorkVerbGetRoute
 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.pytest_fixture_returns_closed_resource import PytestFixtureReturnsClosedResource
 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.require_exp_on_jwt_decode import RequireExpOnJwtDecode
@@ -247,6 +249,8 @@ from sarj_python_lint.rules.test_without_explicit_oracle import NoExplicitTestOr
 
 REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
     {
+        PytestFixtureReturnsClosedResource.id: PytestFixtureReturnsClosedResource,
+        DuplicatePytestFixtureParams.id: DuplicatePytestFixtureParams,
         PreferBulkUpsert.id: PreferBulkUpsert,
         PreferPsycopgExecutemany.id: PreferPsycopgExecutemany,
         StoreFieldUpdateReusesUpsert.id: StoreFieldUpdateReusesUpsert,

{sarj_python_lint-1.66.2 → sarj_python_lint-1.67.0}/src/sarj_python_lint/rules/_resource_provenance.py

@@ -31,6 +31,10 @@ _SCOPES = (
 )
 _RESOURCE_OWNERS = MappingProxyType(
     {
+        "builtins": frozenset({"open"}),
+        "io": frozenset({"open", "StringIO", "BytesIO"}),
+        "tempfile": frozenset({"TemporaryFile", "NamedTemporaryFile"}),
+        "httpx": frozenset({"Client", "AsyncClient"}),
         "asyncio": frozenset({"sleep", "CancelledError", "exceptions.CancelledError"}),
         "contextlib": frozenset({"ExitStack", "AsyncExitStack", "_BaseExitStack"}),
         "subprocess": frozenset({"Popen", "TimeoutExpired"}),

sarj_python_lint-1.67.0/src/sarj_python_lint/rules/duplicate_pytest_fixture_params.py

@@ -0,0 +1,174 @@
+from __future__ import annotations
+
+import ast
+from pathlib import PurePosixPath
+from typing import TYPE_CHECKING, ClassVar, final, override
+
+from sarj_python_lint.rule_base import (
+    AutofixPolicy,
+    Diagnostic,
+    ExampleFile,
+    ExampleOutcome,
+    Rule,
+    RuleCategory,
+    RuleDocumentation,
+    RuleExample,
+    Severity,
+    is_suppressed,
+)
+from sarj_python_lint.rules._ast_index import walk as walk_ast
+from sarj_python_lint.rules._paths import is_test_path
+from sarj_python_lint.rules.pytest_fixture_returns_bare_tuple import fixture_declarations
+
+
+if TYPE_CHECKING:
+    from sarj_python_lint._file_context import PythonFileContext
+    from sarj_python_lint.rules.pytest_fixture_returns_bare_tuple import FixtureDeclaration
+
+
+_BAD = 'import pytest\n\n@pytest.fixture(params=("empty", "empty"))\ndef payload(request):\n    return request.param\n'
+
+
+@final
+class DuplicatePytestFixtureParams(Rule):
+    id: str = "duplicate-pytest-fixture-params"
+    code: str = "SARJ524"
+    documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
+        default_level=Severity.WARNING,
+        summary="Review repeated immutable values in a pytest fixture parameter list.",
+        rationale=(
+            "Each fixture parameter reruns its dependent tests. Repeating the same immutable literal can add "
+            "execution time without exercising a distinct input; Ruff PT014 covers test parametrization, not fixture params."
+        ),
+        remediation=(
+            "Review the dependent test contracts, then remove an accidental duplicate. Preserve intentional repetition "
+            "with explicit case IDs or an exact SARJ524 suppression explaining the repeated-run contract."
+        ),
+        category=RuleCategory.TESTING,
+        autofix=AutofixPolicy.NONE,
+        limitations=(
+            "Only directly imported pytest/pytest-asyncio fixtures in test paths with one decorator and literal list/tuple params are analyzed.",
+            "Compares immutable scalar/tuple literals with type and floating-point sign preserved; mutable values, calls, aliases and pytest.param metadata are not compared.",
+            "Explicit IDs, decorator unpacking and fixtures using request beyond direct request.param loads are excluded.",
+            "Dependent fixtures, hooks and tests may observe case indices, generated IDs or repeated execution; findings require contract review and are never auto-deleted.",
+        ),
+        examples=(
+            RuleExample(
+                example_id="repeated-fixture-input",
+                title="The same input schedules the dependent tests twice",
+                outcome=ExampleOutcome.MATCH,
+                files=(ExampleFile.python("tests/conftest.py", _BAD),),
+                focus_path=PurePosixPath("tests/conftest.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="distinct-fixture-inputs",
+                title="Each fixture parameter represents a distinct input",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(ExampleFile.python("tests/conftest.py", _BAD.replace('"empty", "empty"', '"empty", "filled"')),),
+                focus_path=PurePosixPath("tests/conftest.py"),
+                expected_count=0,
+                public=True,
+            ),
+        ),
+    )
+    description: str = documentation.summary
+
+    @override
+    def check_context(self, context: PythonFileContext) -> list[Diagnostic]:
+        if (
+            not is_test_path(context.path)
+            or context.generated
+            or "params" not in context.symbol_source
+            or context.tree is None
+        ):
+            return []
+        findings: list[Diagnostic] = []
+        for fixture in fixture_declarations(context.tree):
+            params = _parameter_values(fixture, context)
+            if params is None:
+                continue
+            first_values: dict[str, ast.expr] = {}
+            for value in params.elts:
+                key = _literal_key(value)
+                if key is None:
+                    continue
+                first = first_values.setdefault(key, value)
+                if first is value or is_suppressed(context.source_lines, value.lineno, self.code):
+                    continue
+                findings.append(
+                    Diagnostic(
+                        path=context.path,
+                        line=value.lineno,
+                        col=value.col_offset + 1,
+                        code=self.code,
+                        severity=Severity.WARNING,
+                        message=(
+                            f"fixture `{fixture.name}` repeats the immutable parameter from line {first.lineno}; "
+                            "review dependent contracts before removing it, or give intentional repetition explicit IDs"
+                        ),
+                    )
+                )
+        return findings
+
+
+def _parameter_values(fixture: FixtureDeclaration, context: PythonFileContext) -> ast.List | ast.Tuple | None:
+    decorator = fixture.decorator
+    if (
+        len(fixture.node.decorator_list) != 1
+        or not isinstance(decorator, ast.Call)
+        or decorator.args
+        or any(keyword.arg is None for keyword in decorator.keywords)
+        or _observes_request_identity(fixture.node, context)
+    ):
+        return None
+    keywords = {keyword.arg: keyword.value for keyword in decorator.keywords}
+    if len(keywords) != len(decorator.keywords):
+        return None
+    ids = keywords.get("ids")
+    if ids is not None and not (isinstance(ids, ast.Constant) and ids.value is None):
+        return None
+    params = keywords.get("params")
+    return params if isinstance(params, ast.List | ast.Tuple) else None
+
+
+def _literal_key(value: ast.expr) -> str | None:
+    if isinstance(value, ast.Constant) and isinstance(value.value, str | bytes | bool | int | float | type(None)):
+        return _scalar_key(value=value.value)
+    if (
+        isinstance(value, ast.UnaryOp)
+        and isinstance(value.op, ast.UAdd | ast.USub)
+        and isinstance(value.operand, ast.Constant)
+        and isinstance(value.operand.value, int | float)
+        and not isinstance(value.operand.value, bool)
+    ):
+        number = value.operand.value
+        number = -number if isinstance(value.op, ast.USub) else +number
+        return _scalar_key(value=number)
+    if isinstance(value, ast.Tuple):
+        keys = tuple(_literal_key(item) for item in value.elts)
+        if all(key is not None for key in keys):
+            return "tuple:" + "".join(f"{len(key)}:{key}" for key in keys if key is not None)
+    return None
+
+
+def _scalar_key(*, value: str | bytes | float | None) -> str:
+    if isinstance(value, int) and not isinstance(value, bool):
+        return f"int:{value:x}"
+    return f"{type(value).__name__}:{value!r}"
+
+
+def _observes_request_identity(node: ast.FunctionDef | ast.AsyncFunctionDef, context: PythonFileContext) -> bool:
+    for child in walk_ast(node):
+        if isinstance(child, ast.Name) and child.id == "request":
+            parent = context.parents.get(child)
+            if not (
+                isinstance(child.ctx, ast.Load)
+                and isinstance(parent, ast.Attribute)
+                and parent.value is child
+                and parent.attr == "param"
+                and isinstance(parent.ctx, ast.Load)
+            ):
+                return True
+    return False

{sarj_python_lint-1.66.2 → sarj_python_lint-1.67.0}/src/sarj_python_lint/rules/pytest_fixture_returns_bare_tuple.py

@@ -21,6 +21,8 @@ from sarj_python_lint.rules._paths import is_test_path
 
 
 if TYPE_CHECKING:
+    from collections.abc import Iterator
+
     from sarj_python_lint._file_context import PythonFileContext
 
 
@@ -42,6 +44,12 @@ class _FixtureFunction(NamedTuple):
     owner: ast.ClassDef | None
 
 
+class FixtureDeclaration(NamedTuple):
+    node: ast.FunctionDef | ast.AsyncFunctionDef
+    name: str
+    decorator: ast.expr
+
+
 _NO_FIXTURE_DECORATORS = _FixtureDecorators(frozenset(), {}, frozenset())
 
 
@@ -153,8 +161,7 @@ class PytestFixtureReturnsBareTuple(Rule):
         return diags
 
 
-def _bare_tuple_results(tree: ast.Module) -> list[_TupleResult]:
-    hits: list[_TupleResult] = []
+def fixture_declarations(tree: ast.Module) -> Iterator[FixtureDeclaration]:
     for node, owner in _discoverable_functions(tree):
         if not node.decorator_list:
             continue
@@ -162,6 +169,15 @@ def _bare_tuple_results(tree: ast.Module) -> list[_TupleResult]:
         fixture_name = _fixture_name(node, fixture_names)
         if fixture_name is None:
             continue
+        decorator = next(
+            dec for dec in node.decorator_list if _names_fixture(dec, fixture_names.names, fixture_names.roots)
+        )
+        yield FixtureDeclaration(node, fixture_name, decorator)
+
+
+def _bare_tuple_results(tree: ast.Module) -> list[_TupleResult]:
+    hits: list[_TupleResult] = []
+    for node, fixture_name, _decorator in fixture_declarations(tree):
         aliases = _type_aliases(tree, before_line=node.lineno)
         has_yield = _has_own_yield(node)
         if node.returns is not None and _homogeneous_tuple_annotation(

sarj_python_lint-1.67.0/src/sarj_python_lint/rules/pytest_fixture_returns_closed_resource.py

@@ -0,0 +1,190 @@
+from __future__ import annotations
+
+import ast
+from pathlib import PurePosixPath
+from typing import TYPE_CHECKING, ClassVar, final, override
+
+from sarj_python_lint.rule_base import (
+    AutofixPolicy,
+    Diagnostic,
+    ExampleFile,
+    ExampleOutcome,
+    Rule,
+    RuleCategory,
+    RuleDocumentation,
+    RuleExample,
+    Severity,
+    is_suppressed,
+)
+from sarj_python_lint.rules._paths import is_test_path
+from sarj_python_lint.rules.pytest_fixture_returns_bare_tuple import fixture_declarations
+
+
+if TYPE_CHECKING:
+    from sarj_python_lint._file_context import PythonFileContext
+    from sarj_python_lint.rules._resource_provenance import ResourceProvenance
+
+
+_SYNC_RESOURCES = frozenset(
+    {
+        "builtins.open",
+        "io.open",
+        "io.StringIO",
+        "io.BytesIO",
+        "tempfile.TemporaryFile",
+        "tempfile.NamedTemporaryFile",
+        "httpx.Client",
+    }
+)
+_BAD = 'from io import StringIO\nimport pytest\n\n@pytest.fixture\ndef stream():\n    with StringIO("payload") as handle:\n        return handle\n'
+
+
+@final
+class PytestFixtureReturnsClosedResource(Rule):
+    id: str = "pytest-fixture-returns-closed-resource"
+    code: str = "SARJ525"
+    documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
+        default_level=Severity.WARNING,
+        summary="Yield a managed fixture resource until its requesting test finishes.",
+        rationale=(
+            "Returning a context-managed stream or HTTPX client exits its context before pytest receives the value. "
+            "The requesting test receives an already closed resource instead of a usable dependency."
+        ),
+        remediation=(
+            "Yield the resource inside its context so teardown follows the requesting test, updating the generator "
+            "annotation as needed. If the contract deliberately supplies a closed resource, use an exact SARJ525 "
+            "suppression with that reason. Review exception and cleanup behavior; no automatic rewrite is provided."
+        ),
+        category=RuleCategory.TESTING,
+        autofix=AutofixPolicy.NONE,
+        limitations=(
+            "Only proven pytest/pytest-asyncio fixtures in test paths with one decorator and a direct return inside the owning with/async with are analyzed.",
+            "Recognizes built-in/io streams, tempfile TemporaryFile/NamedTemporaryFile, HTTPX Client and async-with AsyncClient; arbitrary context managers and TestClient are excluded.",
+            "Aliases, escaped/rebound resources, provider mutation, nested helpers, generator fixtures, returned snapshots and returns after the context are not inferred.",
+            "Unreachable branches and intentional closed-resource contracts are not inferred; findings are warnings requiring review.",
+        ),
+        examples=(
+            RuleExample(
+                example_id="fixture-returns-closed-stream",
+                title="Returning exits the stream context before the test runs",
+                outcome=ExampleOutcome.MATCH,
+                files=(ExampleFile.python("tests/conftest.py", _BAD),),
+                focus_path=PurePosixPath("tests/conftest.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="fixture-yields-live-stream",
+                title="Yield keeps the stream open for the requesting test",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(ExampleFile.python("tests/conftest.py", _BAD.replace("return handle", "yield handle")),),
+                focus_path=PurePosixPath("tests/conftest.py"),
+                expected_count=0,
+                public=True,
+            ),
+        ),
+    )
+    description: str = documentation.summary
+
+    @override
+    def check_context(self, context: PythonFileContext) -> list[Diagnostic]:
+        if (
+            not is_test_path(context.path)
+            or context.generated
+            or "with" not in context.symbol_source
+            or context.tree is None
+        ):
+            return []
+        returns = [node for node in context.nodes(ast.Return) if isinstance(node.value, ast.Name)]
+        if not returns:
+            return []
+        fixtures = {
+            fixture.node
+            for fixture in fixture_declarations(context.tree)
+            if len(fixture.node.decorator_list) == 1
+            and not (
+                isinstance(fixture.decorator, ast.Call)
+                and (fixture.decorator.args or any(keyword.arg is None for keyword in fixture.decorator.keywords))
+            )
+        }
+        if not fixtures:
+            return []
+        provenance = context.static_resource_provenance
+        generators = {provenance.scope(node) for node in context.nodes(ast.Yield, ast.YieldFrom)}
+        fixtures.difference_update(generators)
+        findings: list[Diagnostic] = []
+        for returned in returns:
+            if (
+                provenance.scope(returned) not in fixtures
+                or not isinstance(returned.value, ast.Name)
+                or not _returns_managed_resource(returned.value, returned, provenance)
+                or is_suppressed(context.source_lines, returned.lineno, self.code)
+            ):
+                continue
+            findings.append(
+                Diagnostic(
+                    path=context.path,
+                    line=returned.lineno,
+                    col=returned.col_offset + 1,
+                    code=self.code,
+                    severity=Severity.WARNING,
+                    message=(
+                        f"fixture returns `{returned.value.id}` after its context closes it; yield inside the context "
+                        "until the requesting test finishes, or document an intentional closed-resource contract"
+                    ),
+                )
+            )
+        return findings
+
+
+def _returns_managed_resource(value: ast.Name, returned: ast.Return, provenance: ResourceProvenance) -> bool:
+    binding = provenance.binding(value.id, returned)
+    item = provenance.parents.get(binding) if binding is not None else None
+    if (
+        not isinstance(binding, ast.Name)
+        or not isinstance(item, ast.withitem)
+        or item.optional_vars is not binding
+        or not isinstance(item.context_expr, ast.Call)
+    ):
+        return False
+    if (
+        not provenance.contains(provenance.parents.get(item), returned)
+        or value.id in provenance.mutated
+        or not _resource_reads_are_local(value, binding, provenance)
+    ):
+        return False
+    constructor = item.context_expr.func
+    qualified = provenance.runtime_import_name(constructor)
+    if qualified is None and _builtin_open(constructor, provenance):
+        qualified = "builtins.open"
+    owner = provenance.parents.get(item)
+    return (
+        qualified == "httpx.AsyncClient"
+        if isinstance(owner, ast.AsyncWith)
+        else isinstance(owner, ast.With) and qualified in _SYNC_RESOURCES
+    )
+
+
+def _builtin_open(constructor: ast.expr, provenance: ResourceProvenance) -> bool:
+    if not isinstance(constructor, ast.Name) or constructor.id != "open":
+        return False
+    return (
+        "open" not in provenance.mutated
+        and not any("open" in names for names in provenance.bindings.values())
+        and provenance.builtin_namespace_untouched
+        and not provenance.wildcard
+        and not provenance.dynamic_namespace
+    )
+
+
+def _resource_reads_are_local(value: ast.Name, binding: ast.AST, provenance: ResourceProvenance) -> bool:
+    for read in provenance.reads.get(value.id, ()):
+        if provenance.binding(value.id, read) is not binding:
+            continue
+        parent = provenance.parents.get(read)
+        if read is value or (
+            isinstance(parent, ast.Attribute) and parent.value is read and isinstance(parent.ctx, ast.Load)
+        ):
+            continue
+        return False
+    return True