ballpython 2.0.0__py3-none-any.whl → 2.0.2__py3-none-any.whl

pycleaner/frameworks/plugins.py

@@ -0,0 +1,290 @@
+"""
+pycleaner.frameworks.plugins
+============================
+
+Concrete Framework Plugins for Pydantic, Pytest, FastAPI, SQLAlchemy, and Dataclasses.
+"""
+
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+
+
+def _get_decorator_name(node: ast.expr) -> str:
+    """Extract string name from decorator node (e.g. 'pytest.fixture' or 'app.get')."""
+    if isinstance(node, ast.Name):
+        return node.id
+    if isinstance(node, ast.Attribute):
+        val = _get_decorator_name(node.value)
+        return f"{val}.{node.attr}" if val else node.attr
+    if isinstance(node, ast.Call):
+        return _get_decorator_name(node.func)
+    return ""
+
+
+def _has_base_named(class_node: ast.ClassDef, base_names: set[str]) -> bool:
+    """Check if class node inherits from any name in base_names."""
+    for base in class_node.bases:
+        if isinstance(base, ast.Name) and base.id in base_names:
+            return True
+        if isinstance(base, ast.Attribute) and base.attr in base_names:
+            return True
+    return False
+
+
+class PydanticPlugin:
+    """Understands Pydantic BaseModel, Field, model_config, and validators."""
+
+    name = "pydantic"
+    _MODEL_BASES = {"BaseModel", "BaseSettings", "RootModel", "GenericModel"}
+    _VALIDATOR_DECORATORS = {
+        "field_validator",
+        "model_validator",
+        "validator",
+        "root_validator",
+        "computed_field",
+    }
+
+    def is_applicable(self, tree: ast.AST, filepath: Path | str) -> bool:
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Import):
+                for alias in node.names:
+                    if alias.name.split(".")[0] == "pydantic":
+                        return True
+            elif isinstance(node, ast.ImportFrom):
+                if node.module and node.module.split(".")[0] == "pydantic":
+                    return True
+        return False
+
+    def get_protected_names(self, tree: ast.AST) -> set[str]:
+        return {"model_config", "Config", "ConfigDict"}
+
+    def get_protected_decorators(self) -> set[str]:
+        return self._VALIDATOR_DECORATORS
+
+    def is_protected_field(self, node: ast.AST, class_node: ast.ClassDef) -> bool:
+        return _has_base_named(class_node, self._MODEL_BASES)
+
+    def should_ignore_definition(
+        self,
+        name: str,
+        kind: str,
+        node: ast.AST,
+        context: str,
+        tree: ast.AST,
+    ) -> bool:
+        if name in self.get_protected_names(tree):
+            return True
+
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            for deco in node.decorator_list:
+                deco_name = _get_decorator_name(deco)
+                for val_dec in self._VALIDATOR_DECORATORS:
+                    if val_dec in deco_name:
+                        return True
+        return False
+
+
+class PytestPlugin:
+    """Understands Pytest fixtures, hooks, parameterizations, and marks."""
+
+    name = "pytest"
+
+    def is_applicable(self, tree: ast.AST, filepath: Path | str) -> bool:
+        f_name = Path(filepath).name
+        if (
+            f_name.startswith("test_")
+            or f_name.endswith("_test.py")
+            or f_name == "conftest.py"
+        ):
+            return True
+        for node in ast.walk(tree):
+            if isinstance(node, (ast.Import, ast.ImportFrom)):
+                if isinstance(node, ast.Import):
+                    for a in node.names:
+                        if a.name == "pytest":
+                            return True
+                elif node.module and node.module.split(".")[0] == "pytest":
+                    return True
+        return False
+
+    def get_protected_names(self, tree: ast.AST) -> set[str]:
+        return {
+            "pytestmark",
+            "pytest_plugins",
+            "pytest_configure",
+            "pytest_unconfigure",
+            "pytest_addoption",
+            "pytest_collection_modifyitems",
+            "pytest_sessionstart",
+            "pytest_sessionfinish",
+        }
+
+    def get_protected_decorators(self) -> set[str]:
+        return {"pytest.fixture", "fixture", "pytest.mark"}
+
+    def is_protected_field(self, node: ast.AST, class_node: ast.ClassDef) -> bool:
+        return False
+
+    def should_ignore_definition(
+        self,
+        name: str,
+        kind: str,
+        node: ast.AST,
+        context: str,
+        tree: ast.AST,
+    ) -> bool:
+        if name in self.get_protected_names(tree):
+            return True
+
+        # Test functions themselves are discovered by pytest runner
+        if kind == "function" and (name.startswith("test_") or name.endswith("_test")):
+            return True
+        if kind == "class" and name.startswith("Test"):
+            return True
+
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            for deco in node.decorator_list:
+                d_name = _get_decorator_name(deco)
+                if "fixture" in d_name or "mark." in d_name:
+                    return True
+        return False
+
+
+class FastAPIPlugin:
+    """Understands FastAPI route handlers, dependencies, and lifecycle hooks."""
+
+    name = "fastapi"
+    _ROUTE_METHODS = {
+        "get",
+        "post",
+        "put",
+        "delete",
+        "patch",
+        "options",
+        "head",
+        "api_route",
+    }
+
+    def is_applicable(self, tree: ast.AST, filepath: Path | str) -> bool:
+        for node in ast.walk(tree):
+            if isinstance(node, (ast.Import, ast.ImportFrom)):
+                if isinstance(node, ast.Import):
+                    for a in node.names:
+                        if a.name in ("fastapi", "starlette"):
+                            return True
+                elif node.module and node.module.split(".")[0] in (
+                    "fastapi",
+                    "starlette",
+                ):
+                    return True
+        return False
+
+    def get_protected_names(self, tree: ast.AST) -> set[str]:
+        return set()
+
+    def get_protected_decorators(self) -> set[str]:
+        return {"app.get", "app.post", "router.get", "router.post"}
+
+    def is_protected_field(self, node: ast.AST, class_node: ast.ClassDef) -> bool:
+        return False
+
+    def should_ignore_definition(
+        self,
+        name: str,
+        kind: str,
+        node: ast.AST,
+        context: str,
+        tree: ast.AST,
+    ) -> bool:
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            for deco in node.decorator_list:
+                d_name = _get_decorator_name(deco)
+                parts = d_name.split(".")
+                if len(parts) >= 2 and parts[-1] in self._ROUTE_METHODS:
+                    return True
+                if (
+                    "middleware" in d_name
+                    or "on_event" in d_name
+                    or "exception_handler" in d_name
+                ):
+                    return True
+        return False
+
+
+class SQLAlchemyPlugin:
+    """Understands SQLAlchemy DeclarativeBase, Mapped, Column, and relationships."""
+
+    name = "sqlalchemy"
+    _BASE_CLASSES = {"Base", "DeclarativeBase", "DeclarativeBaseNoMeta"}
+
+    def is_applicable(self, tree: ast.AST, filepath: Path | str) -> bool:
+        for node in ast.walk(tree):
+            if isinstance(node, (ast.Import, ast.ImportFrom)):
+                if isinstance(node, ast.Import):
+                    for a in node.names:
+                        if a.name.split(".")[0] == "sqlalchemy":
+                            return True
+                elif node.module and node.module.split(".")[0] == "sqlalchemy":
+                    return True
+        return False
+
+    def get_protected_names(self, tree: ast.AST) -> set[str]:
+        return {"__tablename__", "__table_args__", "__mapper_args__"}
+
+    def get_protected_decorators(self) -> set[str]:
+        return {"validates"}
+
+    def is_protected_field(self, node: ast.AST, class_node: ast.ClassDef) -> bool:
+        if _has_base_named(class_node, self._BASE_CLASSES):
+            return True
+        # Check if attribute annotation uses Mapped[...]
+        if isinstance(node, ast.AnnAssign):
+            ann = node.annotation
+            if isinstance(ann, ast.Subscript):
+                if isinstance(ann.value, ast.Name) and ann.value.id == "Mapped":
+                    return True
+        return False
+
+    def should_ignore_definition(
+        self,
+        name: str,
+        kind: str,
+        node: ast.AST,
+        context: str,
+        tree: ast.AST,
+    ) -> bool:
+        return name in self.get_protected_names(tree)
+
+
+class DataclassPlugin:
+    """Understands standard library dataclasses and attrs."""
+
+    name = "dataclass"
+
+    def is_applicable(self, tree: ast.AST, filepath: Path | str) -> bool:
+        return True
+
+    def get_protected_names(self, tree: ast.AST) -> set[str]:
+        return {"__post_init__"}
+
+    def get_protected_decorators(self) -> set[str]:
+        return {"dataclass"}
+
+    def is_protected_field(self, node: ast.AST, class_node: ast.ClassDef) -> bool:
+        for deco in class_node.decorator_list:
+            d_name = _get_decorator_name(deco)
+            if "dataclass" in d_name:
+                return True
+        return False
+
+    def should_ignore_definition(
+        self,
+        name: str,
+        kind: str,
+        node: ast.AST,
+        context: str,
+        tree: ast.AST,
+    ) -> bool:
+        return name in self.get_protected_names(tree)

pycleaner/modernizer.py

@@ -0,0 +1,349 @@
+"""
+Code modernizer engine for upgrading Python source to modern Python idioms (PEP 585, PEP 604).
+
+Performs AST-driven modernization:
+- PEP 585 built-in collection generics (List[T] -> list[T], Dict[K, V] -> dict[K, V], etc.)
+- PEP 604 union syntax (Union[A, B] -> A | B, Optional[A] -> A | None)
+- Automatic injection of 'from __future__ import annotations' when type syntax is modernized
+- Singleton equality comparison healing (== None -> is None, == True/False -> is True/False)
+- Redundant (object) class inheritance pruning (class Foo(object): -> class Foo:)
+- Redundant unicode literal prefix pruning ("..." -> "...")
+"""
+
+from __future__ import annotations
+
+import ast
+import io
+import re
+import tokenize
+from dataclasses import dataclass, field
+
+
+@dataclass(slots=True)
+class ModernizeResult:
+    """Result of modernizing Python source code."""
+
+    code: str
+    changed: bool
+    transformations: list[str] = field(default_factory=list)
+
+
+class _AnnotationTransformer(ast.NodeTransformer):
+    """Transforms legacy typing annotations to PEP 585 and PEP 604 syntax."""
+
+    _PEP_585_MAP = {
+        "List": "list",
+        "Dict": "dict",
+        "Set": "set",
+        "Tuple": "tuple",
+        "FrozenSet": "frozenset",
+        "Type": "type",
+    }
+
+    def __init__(self) -> None:
+        self.changed = False
+        self.transformations: list[str] = []
+
+    def visit_Subscript(self, node: ast.Subscript) -> ast.AST:
+        self.generic_visit(node)
+        name: str | None = None
+        if isinstance(node.value, ast.Name):
+            name = node.value.id
+        elif (
+            isinstance(node.value, ast.Attribute)
+            and isinstance(node.value.value, ast.Name)
+            and node.value.value.id == "typing"
+        ):
+            name = node.value.attr
+
+        if not name:
+            return node
+
+        if name in self._PEP_585_MAP:
+            self.changed = True
+            new_id = self._PEP_585_MAP[name]
+            self.transformations.append(f"PEP 585: typing.{name} -> {new_id}")
+            node.value = ast.Name(id=new_id, ctx=ast.Load())
+            return node
+
+        if name == "Optional":
+            self.changed = True
+            self.transformations.append("PEP 604: typing.Optional[T] -> T | None")
+            return ast.BinOp(
+                left=node.slice, op=ast.BitOr(), right=ast.Constant(value=None)
+            )
+
+        if name == "Union":
+            self.changed = True
+            self.transformations.append("PEP 604: typing.Union[...] -> ... | ...")
+            if isinstance(node.slice, ast.Tuple) and node.slice.elts:
+                cur: ast.expr = node.slice.elts[0]
+                for nxt in node.slice.elts[1:]:
+                    cur = ast.BinOp(left=cur, op=ast.BitOr(), right=nxt)
+                return cur
+            return node.slice
+
+        return node
+
+
+class Modernizer:
+    """Modernizes Python codebases to canonical modern syntax (PEP 585 / 604 / 695)."""
+
+    def __init__(
+        self,
+        enable_pep585: bool = True,
+        enable_pep604: bool = True,
+        enable_singleton_is: bool = True,
+        enable_object_inheritance_pruning: bool = True,
+        enable_unicode_prefix_pruning: bool = True,
+    ) -> None:
+        self.enable_pep585 = enable_pep585
+        self.enable_pep604 = enable_pep604
+        self.enable_singleton_is = enable_singleton_is
+        self.enable_object_inheritance_pruning = enable_object_inheritance_pruning
+        self.enable_unicode_prefix_pruning = enable_unicode_prefix_pruning
+
+    def modernize(self, source: str, filename: str = "<stdin>") -> ModernizeResult:
+        """Modernize Python source string with surgical preservation."""
+        try:
+            ast.parse(source, filename=filename)
+        except SyntaxError:
+            return ModernizeResult(code=source, changed=False)
+
+        current_code = source
+        all_transforms: list[str] = []
+
+        # 1. Class (object) pruning
+        if self.enable_object_inheritance_pruning:
+            current_code, t_obj = self._prune_object_inheritance(current_code)
+            all_transforms.extend(t_obj)
+
+        # 2. Singleton comparisons (== None -> is None, == True/False)
+        if self.enable_singleton_is:
+            current_code, t_cmp = self._modernize_singleton_comparisons(current_code)
+            all_transforms.extend(t_cmp)
+
+        # 3. Unicode literal prefixes ("..." -> "...")
+        if self.enable_unicode_prefix_pruning:
+            current_code, t_u = self._prune_unicode_prefixes(current_code)
+            all_transforms.extend(t_u)
+
+        # 4. PEP 585 / PEP 604 Annotations
+        if self.enable_pep585 or self.enable_pep604:
+            current_code, t_ann = self._modernize_annotations(current_code)
+            all_transforms.extend(t_ann)
+
+        changed = current_code != source
+        return ModernizeResult(
+            code=current_code,
+            changed=changed,
+            transformations=all_transforms,
+        )
+
+    def _prune_object_inheritance(self, source: str) -> tuple[str, list[str]]:
+        try:
+            tree = ast.parse(source)
+        except SyntaxError:
+            return source, []
+
+        transforms: list[str] = []
+        lines = source.splitlines(keepends=True)
+        edits: list[tuple[int, int, str]] = []
+        for node in ast.walk(tree):
+            if isinstance(node, ast.ClassDef) and len(node.bases) == 1:
+                base = node.bases[0]
+                if isinstance(base, ast.Name) and base.id == "object":
+                    line_idx = node.lineno - 1
+                    line_str = lines[line_idx]
+                    pattern = re.compile(
+                        rf"(class\s+{re.escape(node.name)})\s*\(\s*object\s*\)\s*:"
+                    )
+                    if pattern.search(line_str):
+                        new_line = pattern.sub(rf"class {node.name}:", line_str)
+                        edits.append((line_idx, line_idx + 1, new_line))
+                        transforms.append(
+                            f"Pruned legacy (object) inheritance from class {node.name}"
+                        )
+
+        if not edits:
+            return source, []
+
+        for start, end, new_text in sorted(edits, key=lambda x: x[0], reverse=True):
+            lines[start:end] = [new_text]
+
+        return "".join(lines), transforms
+
+    def _modernize_singleton_comparisons(self, source: str) -> tuple[str, list[str]]:
+        try:
+            tree = ast.parse(source)
+        except SyntaxError:
+            return source, []
+
+        lines = source.splitlines(keepends=True)
+        transforms: list[str] = []
+        edits: list[tuple[int, int, int, int, str]] = []
+
+        for node in ast.walk(tree):
+            if (
+                isinstance(node, ast.Compare)
+                and len(node.ops) == 1
+                and len(node.comparators) == 1
+            ):
+                op = node.ops[0]
+                comparator = node.comparators[0]
+                if isinstance(comparator, ast.Constant) and (
+                    comparator.value is None or isinstance(comparator.value, bool)
+                ):
+                    val = comparator.value
+                    if isinstance(op, ast.Eq):
+                        replacement_op = "is"
+                        transforms.append(f"Modernized '== {val}' to 'is {val}'")
+                    elif isinstance(op, ast.NotEq):
+                        replacement_op = "is not"
+                        transforms.append(f"Modernized '!= {val}' to 'is not {val}'")
+                    else:
+                        continue
+
+                    left_unparsed = ast.unparse(node.left)
+                    new_expr = f"{left_unparsed} {replacement_op} {val}"
+                    edits.append(
+                        (
+                            node.lineno,
+                            node.col_offset,
+                            node.end_lineno,
+                            node.end_col_offset,
+                            new_expr,
+                        )
+                    )
+
+        if not edits:
+            return source, []
+
+        edits.sort(key=lambda e: (e[0], e[1]), reverse=True)
+        for lineno, col_offset, end_lineno, end_col_offset, new_text in edits:
+            if lineno == end_lineno:
+                idx = lineno - 1
+                line = lines[idx]
+                lines[idx] = line[:col_offset] + new_text + line[end_col_offset:]
+
+        return "".join(lines), transforms
+
+    def _prune_unicode_prefixes(self, source: str) -> tuple[str, list[str]]:
+        try:
+            tokens = list(
+                tokenize.tokenize(io.BytesIO(source.encode("utf-8")).readline)
+            )
+        except tokenize.TokenError:
+            return source, []
+
+        edits: list[tuple[int, int, int, int]] = []
+        for tok in tokens:
+            if tok.type == tokenize.STRING:
+                if tok.string.startswith(
+                    ('u"', "u'", 'u"""', "u'''", 'U"', "U'", 'U"""', "U'''")
+                ):
+                    s_line, s_col = tok.start
+                    edits.append((s_line, s_col, s_line, s_col + 1))
+
+        if not edits:
+            return source, []
+
+        lines = source.splitlines(keepends=True)
+        edits.sort(key=lambda e: (e[0], e[1]), reverse=True)
+        for s_line, s_col, _e_line, e_col in edits:
+            idx = s_line - 1
+            if 0 <= idx < len(lines):
+                line = lines[idx]
+                lines[idx] = line[:s_col] + line[e_col:]
+
+        new_source = "".join(lines)
+        return new_source, ["Pruned obsolete unicode literal prefixes"]
+
+    def _modernize_annotations(self, source: str) -> tuple[str, list[str]]:
+        try:
+            tree = ast.parse(source)
+        except SyntaxError:
+            return source, []
+
+        lines = source.splitlines(keepends=True)
+        edits: list[tuple[int, int, int, int, str]] = []
+        transformer = _AnnotationTransformer()
+
+        def process_annotation(node: ast.AST | None) -> None:
+            if node is None:
+                return
+            if not hasattr(node, "lineno") or not hasattr(node, "end_lineno"):
+                return
+            sub = _AnnotationTransformer()
+            new_node = sub.visit(node)
+            if sub.changed:
+                transformer.changed = True
+                transformer.transformations.extend(sub.transformations)
+                new_repr = ast.unparse(new_node)
+                edits.append(
+                    (
+                        node.lineno,
+                        node.col_offset,
+                        node.end_lineno,
+                        node.end_col_offset,
+                        new_repr,
+                    )
+                )
+
+        for node in ast.walk(tree):
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                process_annotation(node.returns)
+                for arg in (
+                    node.args.posonlyargs + node.args.args + node.args.kwonlyargs
+                ):
+                    process_annotation(arg.annotation)
+                if node.args.vararg:
+                    process_annotation(node.args.vararg.annotation)
+                if node.args.kwarg:
+                    process_annotation(node.args.kwarg.annotation)
+            elif isinstance(node, ast.AnnAssign):
+                process_annotation(node.annotation)
+
+        if not edits:
+            return source, []
+
+        edits.sort(key=lambda e: (e[0], e[1]), reverse=True)
+        for lineno, col_offset, end_lineno, end_col_offset, new_text in edits:
+            if lineno == end_lineno:
+                idx = lineno - 1
+                line = lines[idx]
+                lines[idx] = line[:col_offset] + new_text + line[end_col_offset:]
+
+        res = "".join(lines)
+
+        if transformer.changed and "from __future__ import annotations" not in res:
+            res = self._inject_future_annotations(res)
+            transformer.transformations.append(
+                "Injected 'from __future__ import annotations'"
+            )
+
+        return res, transformer.transformations
+
+    @staticmethod
+    def _inject_future_annotations(source: str) -> str:
+        lines = source.splitlines(keepends=True)
+        insert_idx = 0
+        try:
+            tree = ast.parse(source)
+            if (
+                tree.body
+                and isinstance(tree.body[0], ast.Expr)
+                and isinstance(tree.body[0].value, ast.Constant)
+                and isinstance(tree.body[0].value.value, str)
+            ):
+                insert_idx = getattr(tree.body[0], "end_lineno", 1)
+        except SyntaxError:
+            pass  # Fall back to default index if docstring extraction fails
+
+        future_stmt = "from __future__ import annotations\n\n"
+        if insert_idx < len(lines):
+            lines.insert(insert_idx, future_stmt)
+        else:
+            lines.append(future_stmt)
+
+        return "".join(lines)