pytest-tidy 0.1.0__py3-none-any.whl

pytest_tidy/__init__.py

@@ -0,0 +1,44 @@
+"""pytest-tidy: a static, AST-based test-smell linter for pytest suites.
+
+The public surface is intentionally small and stable:
+
+    from pytest_tidy import lint_source, lint_paths, __version__
+"""
+
+from __future__ import annotations
+
+from .models import Diagnostic, Edit, Fix, Severity
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    "Diagnostic",
+    "Edit",
+    "Fix",
+    "Severity",
+    "lint_source",
+    "lint_paths",
+]
+
+
+def lint_source(source: str, filename: str = "<string>", config=None):
+    """Lint a single source string and return a list of :class:`Diagnostic`.
+
+    This is a convenience wrapper around the engine so that the package can be
+    used as a library without touching the CLI.
+    """
+    from .config import Config
+    from .engine import Engine
+
+    engine = Engine(config or Config())
+    return engine.check_source(filename, source)
+
+
+def lint_paths(paths, config=None):
+    """Lint files/directories and return a list of :class:`Diagnostic`."""
+    from .config import Config
+    from .engine import Engine
+
+    engine = Engine(config or Config())
+    return engine.check_paths(list(paths))

pytest_tidy/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pytest_tidy/astutils.py

@@ -0,0 +1,259 @@
+"""Low-level AST helpers shared by every rule.
+
+The most important helper is :func:`qualified_name`, which resolves an
+expression like ``pt.raises`` (given ``import pytest as pt``) or ``raises``
+(given ``from pytest import raises``) to its canonical dotted path
+``"pytest.raises"``. Rules match against those canonical names so they work
+regardless of how a symbol was imported.
+"""
+
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass, field
+from typing import Dict, Iterator, List, Optional, Tuple
+
+# Scopes ordered from narrowest to widest. A fixture may only depend on fixtures
+# whose scope is >= its own; the reverse is a pytest ScopeMismatch error.
+SCOPE_ORDER: Dict[str, int] = {
+    "function": 0,
+    "class": 1,
+    "module": 2,
+    "package": 3,
+    "session": 4,
+}
+
+FIXTURE_DECORATORS = frozenset({"pytest.fixture", "pytest.yield_fixture"})
+
+NESTED_SCOPES = (ast.FunctionDef, ast.AsyncFunctionDef, ast.Lambda, ast.ClassDef)
+FUNCTION_DEFS = (ast.FunctionDef, ast.AsyncFunctionDef)
+
+
+@dataclass
+class Imports:
+    """Resolved import table for a module.
+
+    ``modules`` maps a bound alias to the real module name, e.g.
+    ``{"pytest": "pytest", "pt": "pytest", "np": "numpy"}``.
+
+    ``names`` maps a bound name to ``(module, original_name)`` for
+    ``from x import y as z`` style imports, e.g.
+    ``{"raises": ("pytest", "raises"), "sleep": ("time", "sleep")}``.
+    """
+
+    modules: Dict[str, str] = field(default_factory=dict)
+    names: Dict[str, Tuple[str, str]] = field(default_factory=dict)
+
+
+def build_import_table(tree: ast.Module) -> Imports:
+    imports = Imports()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                bound = alias.asname or alias.name.split(".")[0]
+                # For "import a.b.c" without asname, the bound name is "a" and
+                # refers to module "a". For "import a.b as c" it is c -> a.b.
+                target = alias.name if alias.asname else alias.name.split(".")[0]
+                imports.modules[bound] = target
+        elif isinstance(node, ast.ImportFrom):
+            if node.module is None or node.level:
+                # Relative imports: we can't resolve the absolute module, but the
+                # bound name is still useful for local resolution. Record it as a
+                # local name pointing at a best-effort module string.
+                module = node.module or ""
+            else:
+                module = node.module
+            for alias in node.names:
+                if alias.name == "*":
+                    continue
+                bound = alias.asname or alias.name
+                imports.names[bound] = (module, alias.name)
+    return imports
+
+
+def qualified_name(node: ast.AST, imports: Imports) -> Optional[str]:
+    """Return the canonical dotted name for an attribute/name expression.
+
+    Returns ``None`` if ``node`` is not a plain attribute/name chain (e.g. it is
+    a call, subscript, or literal). Import aliases are resolved so callers can
+    match on stable names like ``"pytest.mark.parametrize"``.
+    """
+    parts: List[str] = []
+    cur = node
+    while isinstance(cur, ast.Attribute):
+        parts.append(cur.attr)
+        cur = cur.value
+    if not isinstance(cur, ast.Name):
+        return None
+    base = cur.id
+    parts.append(base)
+    parts.reverse()  # [base, attr, attr, ...]
+
+    if base in imports.modules:
+        parts[0] = imports.modules[base]
+        return ".".join(parts)
+    if base in imports.names:
+        module, original = imports.names[base]
+        resolved = ([module] if module else []) + [original] + parts[1:]
+        return ".".join(p for p in resolved if p)
+    return ".".join(parts)
+
+
+def call_qualified_name(node: ast.Call, imports: Imports) -> Optional[str]:
+    """Canonical dotted name of a call's *callee* (``node.func``)."""
+    return qualified_name(node.func, imports)
+
+
+def decorator_names(func: ast.AST, imports: Imports) -> List[Tuple[str, ast.AST]]:
+    """Return ``(canonical_name, decorator_node)`` for each decorator.
+
+    For ``@x.y(...)`` the decorator node is the ``Call`` and the name resolves
+    ``x.y``; for ``@x.y`` the node is the attribute/name itself.
+    """
+    out: List[Tuple[str, ast.AST]] = []
+    for dec in getattr(func, "decorator_list", []) or []:
+        target = dec.func if isinstance(dec, ast.Call) else dec
+        name = qualified_name(target, imports)
+        if name is not None:
+            out.append((name, dec))
+    return out
+
+
+def fixture_decorator(
+    func: ast.AST, imports: Imports
+) -> Optional[Tuple[str, ast.AST]]:
+    """Return ``(canonical_name, decorator_node)`` if ``func`` is a fixture."""
+    for name, dec in decorator_names(func, imports):
+        if name in FIXTURE_DECORATORS:
+            return name, dec
+    return None
+
+
+def fixture_scope(decorator: ast.AST) -> Tuple[str, Optional[ast.AST]]:
+    """Extract a fixture's declared scope from its decorator.
+
+    Returns ``(scope, scope_value_node)``. ``scope_value_node`` is the AST node
+    carrying the scope literal (a keyword value or positional arg), or ``None``
+    when the scope is implicit (defaults to ``"function"``).
+    """
+    if not isinstance(decorator, ast.Call):
+        return "function", None
+    for kw in decorator.keywords:
+        if kw.arg == "scope" and isinstance(kw.value, ast.Constant):
+            if isinstance(kw.value.value, str):
+                return kw.value.value, kw.value
+    # Deprecated positional scope: pytest.fixture("module").
+    if decorator.args:
+        first = decorator.args[0]
+        if isinstance(first, ast.Constant) and isinstance(first.value, str):
+            if first.value in SCOPE_ORDER:
+                return first.value, first
+    return "function", None
+
+
+def is_test_function(func: ast.AST, prefix: str = "test") -> bool:
+    name = getattr(func, "name", "")
+    return isinstance(func, FUNCTION_DEFS) and name.startswith(prefix)
+
+
+def function_arg_names(func: ast.AST) -> List[str]:
+    """Positional/keyword parameter names, excluding ``self``/``cls``."""
+    args = func.args
+    names: List[str] = []
+    for a in list(args.posonlyargs) + list(args.args):
+        names.append(a.arg)
+    if args.vararg:
+        names.append(args.vararg.arg)
+    for a in args.kwonlyargs:
+        names.append(a.arg)
+    if args.kwarg:
+        names.append(args.kwarg.arg)
+    return [n for n in names if n not in ("self", "cls")]
+
+
+def is_docstring(stmt: ast.stmt) -> bool:
+    return (
+        isinstance(stmt, ast.Expr)
+        and isinstance(stmt.value, ast.Constant)
+        and isinstance(stmt.value.value, str)
+    )
+
+
+def is_trivial_stmt(stmt: ast.stmt) -> bool:
+    """A statement that carries no real behaviour: ``pass``, ``...``, docstring."""
+    if isinstance(stmt, ast.Pass):
+        return True
+    if is_docstring(stmt):
+        return True
+    if isinstance(stmt, ast.Expr) and isinstance(stmt.value, ast.Constant):
+        return stmt.value.value is Ellipsis
+    return False
+
+
+def significant_body(body: List[ast.stmt]) -> List[ast.stmt]:
+    return [s for s in body if not is_trivial_stmt(s)]
+
+
+def iter_body_excluding_nested(func: ast.AST) -> Iterator[ast.AST]:
+    """Yield every node under ``func.body`` without descending into nested
+    function/lambda/class scopes. The nested scope node itself is yielded, but
+    not its contents."""
+    for stmt in getattr(func, "body", []):
+        yield from _walk_no_nested(stmt)
+
+
+def _walk_no_nested(node: ast.AST) -> Iterator[ast.AST]:
+    yield node
+    if isinstance(node, NESTED_SCOPES):
+        # Yield the nested scope itself but do not descend into its body, so a
+        # `return`/`yield` inside a nested helper isn't attributed to the outer
+        # function.
+        return
+    for child in ast.iter_child_nodes(node):
+        yield from _walk_no_nested(child)
+
+
+def constant_is_truthy(node: ast.AST) -> Optional[bool]:
+    """If ``node`` is a literal whose truthiness is statically known, return it.
+
+    Handles constants and non-empty/empty literal containers. Returns ``None``
+    when truthiness cannot be determined statically.
+    """
+    if isinstance(node, ast.Constant):
+        try:
+            return bool(node.value)
+        except Exception:  # pragma: no cover - defensive
+            return None
+    if isinstance(node, (ast.List, ast.Tuple, ast.Set)):
+        return len(node.elts) > 0
+    if isinstance(node, ast.Dict):
+        return len(node.keys) > 0
+    return None
+
+
+def unparse(node: ast.AST) -> str:
+    try:
+        return ast.unparse(node)
+    except Exception:  # pragma: no cover - defensive
+        return "<expr>"
+
+
+def source_segment(source: str, node: ast.AST) -> Optional[str]:
+    try:
+        return ast.get_source_segment(source, node)
+    except Exception:  # pragma: no cover - defensive
+        return None
+
+
+def is_simple_expr(node: ast.AST) -> bool:
+    """True for expressions safe to wrap/inline without precedence surprises."""
+    return isinstance(
+        node,
+        (
+            ast.Name,
+            ast.Attribute,
+            ast.Call,
+            ast.Subscript,
+            ast.Constant,
+        ),
+    )

pytest_tidy/autofix.py

@@ -0,0 +1,100 @@
+"""Apply autofixes to source text as byte-precise range replacements.
+
+Python's AST reports ``col_offset`` as a UTF-8 *byte* offset, so we do all edit
+arithmetic in bytes and decode once at the end. Edits are applied from the end
+of the file toward the start, which keeps earlier offsets valid; any pair of
+overlapping edits is resolved by keeping the first and deferring the rest to a
+later pass.
+"""
+
+from __future__ import annotations
+
+from typing import List, Optional, Sequence, Tuple
+
+from .models import Diagnostic, Edit
+
+
+class _Span:
+    __slots__ = ("start", "end", "text")
+
+    def __init__(self, start: int, end: int, text: bytes) -> None:
+        self.start = start
+        self.end = end
+        self.text = text
+
+
+def _line_byte_offsets(source: str) -> List[int]:
+    offsets = [0]
+    total = 0
+    for line in source.splitlines(keepends=True):
+        total += len(line.encode("utf-8"))
+        offsets.append(total)
+    return offsets
+
+
+def _edit_to_span(offsets: List[int], edit: Edit) -> _Span:
+    start = offsets[edit.start_line - 1] + edit.start_col
+    end = offsets[edit.end_line - 1] + edit.end_col
+    return _Span(start, end, edit.replacement.encode("utf-8"))
+
+
+def _overlaps(start: int, end: int, occupied: Sequence[Tuple[int, int]]) -> bool:
+    for os, oe in occupied:
+        if not (end <= os or start >= oe):
+            return True
+    return False
+
+
+def apply_fixes(
+    source: str, diagnostics: Sequence[Diagnostic]
+) -> Tuple[str, List[Diagnostic]]:
+    """Apply every non-conflicting fix once.
+
+    Returns ``(new_source, fixed_diagnostics)``. Diagnostics whose edits
+    conflicted with an already-applied fix are simply left unfixed; callers that
+    want to converge can call :func:`fix_source` which loops.
+    """
+    offsets = _line_byte_offsets(source)
+    items: List[Tuple[Diagnostic, List[_Span]]] = []
+    for diag in diagnostics:
+        if not diag.fix:
+            continue
+        spans = [_edit_to_span(offsets, e) for e in diag.fix.edits]
+        if not spans:
+            continue
+        items.append((diag, spans))
+
+    # Highest start offset first so applied edits never invalidate lower ones.
+    items.sort(key=lambda it: min(s.start for s in it[1]), reverse=True)
+
+    data = source.encode("utf-8")
+    occupied: List[Tuple[int, int]] = []
+    fixed: List[Diagnostic] = []
+    for diag, spans in items:
+        if any(_overlaps(s.start, s.end, occupied) for s in spans):
+            continue
+        for span in sorted(spans, key=lambda s: s.start, reverse=True):
+            data = data[: span.start] + span.text + data[span.end :]
+            occupied.append((span.start, span.end))
+        fixed.append(diag)
+    return data.decode("utf-8"), fixed
+
+
+def fix_source(
+    source: str, engine, filename: str, max_passes: int = 10
+) -> Tuple[str, List[Diagnostic]]:
+    """Repeatedly lint + apply fixes until stable.
+
+    Returns ``(fixed_source, applied_diagnostics)``. Re-linting between passes
+    lets a fix that becomes applicable only after an earlier edit still land.
+    """
+    applied: List[Diagnostic] = []
+    current = source
+    for _ in range(max_passes):
+        diagnostics = engine.check_source(filename, current)
+        new_source, fixed = apply_fixes(current, diagnostics)
+        if not fixed or new_source == current:
+            break
+        applied.extend(fixed)
+        current = new_source
+    return current, applied