wexample-wex-addon-dev-python 12.2.0__py3-none-any.whl → 13.0.0__py3-none-any.whl

wexample_wex_addon_dev_python/refactor/python_common.py

@@ -0,0 +1,426 @@
+from __future__ import annotations
+
+from collections.abc import Iterator
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import libcst as cst
+
+# Directories never scanned for source files (build/venv artefacts, VCS).
+SKIP_DIR_NAMES: frozenset[str] = frozenset({
+    "__pycache__",
+    ".venv",
+    "venv",
+    "env",
+    ".git",
+    "node_modules",
+    ".pytest_cache",
+    ".mypy_cache",
+    ".ruff_cache",
+    ".pdm-build",
+    "dist",
+    "build",
+})
+
+
+def dotted_to_parts(node) -> tuple[str, ...] | None:
+    """Flatten a chained `cst.Attribute` / `cst.Name` into ('a', 'b', 'c')."""
+    parts: list[str] = []
+    cur = node
+    while isinstance(cur, cst.Attribute):
+        if not isinstance(cur.attr, cst.Name):
+            return None
+        parts.append(cur.attr.value)
+        cur = cur.value
+    if not isinstance(cur, cst.Name):
+        return None
+    parts.append(cur.value)
+    parts.reverse()
+    return tuple(parts)
+
+
+def file_to_package_parts(py_file: Path) -> tuple[str, ...] | None:
+    """Return the dotted parts of the Python package containing `py_file`.
+
+    Walks up from the file's directory through every parent that has an
+    `__init__.py`; the walk stops at the first ancestor without one, which
+    marks the package root. Returns None when the file isn't inside any
+    Python package (no `__init__.py` chain). Used to resolve relative
+    imports to their absolute equivalent.
+    """
+    parts: list[str] = []
+    current = py_file.parent
+    while (current / "__init__.py").is_file():
+        parts.append(current.name)
+        up = current.parent
+        if up == current:
+            break
+        current = up
+    if not parts:
+        return None
+    parts.reverse()
+    return tuple(parts)
+
+
+def iter_python_files(scope_roots: list[Path]) -> Iterator[Path]:
+    """Iterate every .py file under any scope root, skipping build/VCS dirs."""
+    seen: set[str] = set()
+    for root in scope_roots:
+        stack: list[Path] = [root]
+        while stack:
+            current = stack.pop()
+            try:
+                for entry in current.iterdir():
+                    if entry.is_dir():
+                        if entry.name not in SKIP_DIR_NAMES:
+                            stack.append(entry)
+                    elif entry.suffix == ".py":
+                        key = str(entry.resolve())
+                        if key in seen:
+                            continue
+                        seen.add(key)
+                        yield entry
+            except (PermissionError, FileNotFoundError):
+                continue
+
+
+def parts_to_dotted(parts: tuple[str, ...]):
+    node: cst.BaseExpression = cst.Name(parts[0])
+    for part in parts[1:]:
+        node = cst.Attribute(value=node, attr=cst.Name(part))
+    return node
+
+
+def rewrite_imports(
+    py_file: Path,
+    old_parts: tuple[str, ...],
+    new_parts: tuple[str, ...],
+) -> str | None:
+    """Return rewritten source, or None when no import touched this file."""
+    source = py_file.read_text(encoding="utf-8")
+    try:
+        module = cst.parse_module(source)
+    except cst.ParserSyntaxError:
+        return None
+
+    transformer = _ImportRenameTransformer(
+        old_parts=old_parts,
+        new_parts=new_parts,
+        file_pkg=file_to_package_parts(py_file),
+    )
+    new_module = module.visit(transformer)
+    if not transformer.changed:
+        return None
+    return new_module.code
+
+
+def rewrite_symbol_references(
+    py_file: Path,
+    parent_parts: tuple[str, ...],
+    old_name: str,
+    new_name: str,
+    *,
+    is_definition_file: bool = False,
+) -> str | None:
+    """Return rewritten source, or None when no occurrence touched this file.
+
+    Handles imports (`from <parent> import <old_name>`, with or without `as`),
+    dotted imports (`import <parent>.<old_name>`), attribute access
+    (`<parent>.<old_name>`), and bare references whose qualified name resolves
+    to the external dotted name. In the definition file, locally-bound
+    `<old_name>` references are renamed too.
+    """
+    source = py_file.read_text(encoding="utf-8")
+    # Cheap pre-filter: QualifiedNameProvider scope analysis is expensive,
+    # most files don't even mention the symbol. The substring check matches
+    # def statements, imports, attribute access and bare references in one go.
+    if old_name not in source:
+        return None
+
+    try:
+        module = cst.parse_module(source)
+    except cst.ParserSyntaxError:
+        return None
+
+    wrapper = cst.metadata.MetadataWrapper(module)
+    transformer = _SymbolRenameTransformer(
+        parent_parts=parent_parts,
+        old_name=old_name,
+        new_name=new_name,
+        is_definition_file=is_definition_file,
+    )
+    new_module = wrapper.visit(transformer)
+    if not transformer.changed:
+        return None
+    return new_module.code
+
+
+@dataclass
+class RenameReport:
+    """Outcome of a rename run.
+
+    `source_path`/`target_path` describe the move (or proposed move in dry-run);
+    they may point to a directory (PACKAGE) or to a .py file (MODULE).
+    `files_changed` lists every .py whose imports were rewritten.
+    """
+
+    files_changed: list[Path] = field(default_factory=list)
+    files_scanned: int = 0
+    source_path: Path | None = None
+    target_path: Path | None = None
+
+
+class _ImportRenameTransformer(cst.CSTTransformer):
+    """Rewrites import statements that target the renamed package/module.
+
+    Covers four shapes:
+      A. `from <old>.<...> import X` / `import <old>.<...>` — absolute path
+         starts with the renamed entity.
+      B. `from <parent-of-old> import <old.last_part>` — the entity is
+         imported by name (alias position) under its direct parent.
+      C. Relative variants of A: `from .<x>.<...> import Y` whose resolved
+         absolute path starts with the renamed entity. Needs the current
+         file's dotted package (`file_pkg`) to resolve the dots.
+      D. Relative variants of B: `from .<...> import <old.last_part>` whose
+         resolved module path equals the old entity's direct parent.
+    """
+
+    def __init__(
+        self,
+        old_parts: tuple[str, ...],
+        new_parts: tuple[str, ...],
+        file_pkg: tuple[str, ...] | None = None,
+    ) -> None:
+        super().__init__()
+        self.old_parts = old_parts
+        self.new_parts = new_parts
+        self.file_pkg = file_pkg
+        self._n = len(old_parts)
+        self.changed = False
+
+    def leave_Import(
+        self,
+        original_node: cst.Import,
+        updated_node: cst.Import,
+    ) -> cst.Import:
+        new_names = []
+        touched = False
+        for alias in updated_node.names:
+            parts = dotted_to_parts(alias.name)
+            if parts is None or not self._starts_with(parts):
+                new_names.append(alias)
+                continue
+            new_parts = self.new_parts + parts[self._n:]
+            new_names.append(alias.with_changes(name=parts_to_dotted(new_parts)))
+            touched = True
+        if not touched:
+            return updated_node
+        self.changed = True
+        return updated_node.with_changes(names=new_names)
+
+    def leave_ImportFrom(
+        self,
+        original_node: cst.ImportFrom,
+        updated_node: cst.ImportFrom,
+    ) -> cst.ImportFrom:
+        rel_count = len(updated_node.relative)
+        resolved_pkg = self._resolve_relative_prefix(rel_count)
+        if rel_count > 0 and resolved_pkg is None:
+            # Relative import we can't resolve (no file_pkg or depth too deep) →
+            # leave it alone instead of guessing.
+            return updated_node
+
+        module_parts = (
+            dotted_to_parts(updated_node.module)
+            if updated_node.module is not None
+            else ()
+        )
+        if updated_node.module is not None and module_parts is None:
+            return updated_node
+
+        absolute_module = (resolved_pkg or ()) + (module_parts or ())
+
+        # Case A/C — the module side IS the renamed entity (or below it).
+        if self._starts_with(absolute_module):
+            new_absolute = self.new_parts + absolute_module[self._n:]
+            new_module_parts = new_absolute[len(resolved_pkg or ()):]
+            self.changed = True
+            new_module_node = (
+                parts_to_dotted(new_module_parts) if new_module_parts else None
+            )
+            return updated_node.with_changes(module=new_module_node)
+
+        # Case B/D — the module is exactly the direct parent of the renamed
+        # entity, and the entity appears as an imported name.
+        if (
+            self._n >= 1
+            and len(absolute_module) == self._n - 1
+            and absolute_module == self.old_parts[:-1]
+        ):
+            old_last = self.old_parts[-1]
+            new_last = self.new_parts[-1]
+            new_names = []
+            touched = False
+            for alias in updated_node.names:
+                if (
+                    isinstance(alias.name, cst.Name)
+                    and alias.name.value == old_last
+                ):
+                    new_names.append(alias.with_changes(name=cst.Name(new_last)))
+                    touched = True
+                else:
+                    new_names.append(alias)
+            if touched:
+                self.changed = True
+                return updated_node.with_changes(names=new_names)
+
+        return updated_node
+
+    def _resolve_relative_prefix(
+        self, rel_count: int
+    ) -> tuple[str, ...] | None:
+        """Convert a relative-import dot count into the absolute package
+        prefix it resolves to. Returns `()` for an absolute (non-relative)
+        import, the resolved prefix for a relative one, or None when
+        resolution is impossible (no file_pkg or depth overflow)."""
+        if rel_count == 0:
+            return ()
+        if self.file_pkg is None:
+            return None
+        # `from . import X` ← parent_count 0 (current package)
+        # `from .. import X` ← parent_count 1 (one level up)
+        parent_count = rel_count - 1
+        if parent_count > len(self.file_pkg):
+            return None
+        if parent_count == 0:
+            return self.file_pkg
+        return self.file_pkg[:-parent_count]
+
+    def _starts_with(self, parts: tuple[str, ...]) -> bool:
+        return len(parts) >= self._n and parts[: self._n] == self.old_parts
+
+
+class _SymbolRenameTransformer(cst.CSTTransformer):
+    """Rewrites references to one specific symbol (parent.old_name → parent.new_name).
+
+    Two cases handled uniformly via libcst's QualifiedNameProvider:
+    - Consumer file: matches the external IMPORT-sourced qualified name
+      `<parent>.<old_name>` on Name/Attribute usages, and rewrites
+      `from <parent> import <old_name>` / `import <parent>.<old_name>` lines.
+    - Definition file: when `is_definition_file=True`, additionally rewrites
+      Name nodes whose qualified name is the bare `<old_name>` with LOCAL
+      source — that covers the def statement itself plus same-module references.
+
+    Alias preservation: `from M import Old as X` keeps `X` untouched because
+    `original.value == 'X' != 'Old'`; only the import's `name` part is
+    rewritten via `leave_ImportFrom`.
+    """
+
+    METADATA_DEPENDENCIES = (cst.metadata.QualifiedNameProvider,)
+
+    def __init__(
+        self,
+        parent_parts: tuple[str, ...],
+        old_name: str,
+        new_name: str,
+        *,
+        is_definition_file: bool = False,
+    ) -> None:
+        super().__init__()
+        self.parent_parts = parent_parts
+        self.old_name = old_name
+        self.new_name = new_name
+        self.external_qname = ".".join(parent_parts) + "." + old_name
+        self.is_definition_file = is_definition_file
+        self.changed = False
+
+    def leave_Attribute(
+        self,
+        original_node: cst.Attribute,
+        updated_node: cst.Attribute,
+    ) -> cst.Attribute:
+        if (
+            not isinstance(original_node.attr, cst.Name)
+            or original_node.attr.value != self.old_name
+        ):
+            return updated_node
+        if not self._qname_matches_external(original_node):
+            return updated_node
+        self.changed = True
+        return updated_node.with_changes(attr=cst.Name(self.new_name))
+
+    def leave_Import(
+        self,
+        original_node: cst.Import,
+        updated_node: cst.Import,
+    ) -> cst.Import:
+        new_names: list[cst.ImportAlias] = []
+        touched = False
+        full_parts = self.parent_parts + (self.old_name,)
+        for alias in updated_node.names:
+            parts = dotted_to_parts(alias.name)
+            if parts == full_parts:
+                new_parts = self.parent_parts + (self.new_name,)
+                new_names.append(alias.with_changes(name=parts_to_dotted(new_parts)))
+                touched = True
+            else:
+                new_names.append(alias)
+        if not touched:
+            return updated_node
+        self.changed = True
+        return updated_node.with_changes(names=new_names)
+
+    def leave_ImportFrom(
+        self,
+        original_node: cst.ImportFrom,
+        updated_node: cst.ImportFrom,
+    ) -> cst.ImportFrom:
+        if updated_node.module is None:
+            return updated_node
+        module_parts = dotted_to_parts(updated_node.module)
+        if module_parts != self.parent_parts:
+            return updated_node
+        if not isinstance(updated_node.names, (list, tuple)):
+            return updated_node
+        new_names: list[cst.ImportAlias] = []
+        touched = False
+        for alias in updated_node.names:
+            if (
+                isinstance(alias.name, cst.Name)
+                and alias.name.value == self.old_name
+            ):
+                new_names.append(alias.with_changes(name=cst.Name(self.new_name)))
+                touched = True
+            else:
+                new_names.append(alias)
+        if not touched:
+            return updated_node
+        self.changed = True
+        return updated_node.with_changes(names=new_names)
+
+    def leave_Name(
+        self,
+        original_node: cst.Name,
+        updated_node: cst.Name,
+    ) -> cst.Name:
+        if original_node.value != self.old_name:
+            return updated_node
+        quals = self.get_metadata(
+            cst.metadata.QualifiedNameProvider, original_node, set()
+        )
+        for q in quals:
+            if q.name == self.external_qname:
+                self.changed = True
+                return updated_node.with_changes(value=self.new_name)
+            if (
+                self.is_definition_file
+                and q.name == self.old_name
+                and q.source == cst.metadata.QualifiedNameSource.LOCAL
+            ):
+                self.changed = True
+                return updated_node.with_changes(value=self.new_name)
+        return updated_node
+
+    def _qname_matches_external(self, node: cst.CSTNode) -> bool:
+        quals = self.get_metadata(cst.metadata.QualifiedNameProvider, node, set())
+        return any(q.name == self.external_qname for q in quals)

wexample_wex_addon_dev_python/refactor/python_constant_rename_handler.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+import libcst as cst
+from wexample_helpers.decorator.base_class import base_class
+
+from wexample_wex_addon_dev_python.refactor.abstract_python_symbol_rename_handler import (
+    AbstractPythonSymbolRenameHandler,
+)
+
+
+@base_class
+class PythonConstantRenameHandler(AbstractPythonSymbolRenameHandler):
+    """Rename a top-level constant — a module-level assignment whose target is
+    a single bare name. Catches both annotated (`FOO: int = 1`) and plain
+    (`FOO = 1`) forms. Tuple/multi-target assignments are intentionally
+    skipped to keep the predicate unambiguous."""
+
+    def _is_definition_node(self, node: cst.CSTNode, name: str) -> bool:
+        if isinstance(node, cst.SimpleStatementLine):
+            for small in node.body:
+                if self._statement_assigns(small, name):
+                    return True
+        return False
+
+    def _kind_label(self) -> str:
+        return "constant"
+
+    def _statement_assigns(self, small: cst.BaseSmallStatement, name: str) -> bool:
+        if isinstance(small, cst.Assign):
+            if len(small.targets) != 1:
+                return False
+            target = small.targets[0].target
+            return isinstance(target, cst.Name) and target.value == name
+        if isinstance(small, cst.AnnAssign):
+            target = small.target
+            return isinstance(target, cst.Name) and target.value == name
+        return False

wexample_wex_addon_dev_python/refactor/python_function_rename_handler.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+import libcst as cst
+from wexample_helpers.decorator.base_class import base_class
+
+from wexample_wex_addon_dev_python.refactor.abstract_python_symbol_rename_handler import (
+    AbstractPythonSymbolRenameHandler,
+)
+
+
+@base_class
+class PythonFunctionRenameHandler(AbstractPythonSymbolRenameHandler):
+    """Rename a top-level function declared with `def foo(...)` at module level.
+    Async-def is covered too. Methods on classes are out of scope here — they
+    need type-aware dispatch resolution."""
+
+    def _is_definition_node(self, node: cst.CSTNode, name: str) -> bool:
+        return isinstance(node, cst.FunctionDef) and node.name.value == name
+
+    def _kind_label(self) -> str:
+        return "function"

wexample_wex_addon_dev_python/refactor/python_module_rename_handler.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from wexample_helpers.decorator.base_class import base_class
+
+from wexample_wex_addon_dev_python.refactor.abstract_python_path_rename_handler import (
+    AbstractPythonPathRenameHandler,
+)
+from wexample_wex_addon_dev_python.refactor.python_common import SKIP_DIR_NAMES
+
+
+@base_class
+class PythonModuleRenameHandler(AbstractPythonPathRenameHandler):
+    """Rename a single Python module (a `.py` file) and propagate the
+    import-rewrite. Unlike a package, the move can cross parent directories
+    — the target's parent must already exist (we don't create new packages
+    implicitly; the preflight surfaces a missing parent as a clean error)."""
+
+    def __attrs_post_init__(self) -> None:
+        super().__attrs_post_init__()
+        # A module dotted name needs at least one parent package — a bare
+        # top-level name has nowhere to live and `_derive_target_path`
+        # couldn't compute a target for it.
+        if "." not in self.source or "." not in self.target:
+            raise ValueError(
+                "module source/target must be fully dotted (e.g. 'pkg.sub.mod')"
+            )
+
+    def _derive_target_path(self, source_path: Path) -> Path:
+        n = len(self._source_parts)
+        # Strip the .py extension to align with `_source_parts`, swap the
+        # trailing N parts for `_target_parts`, then re-attach the extension.
+        file_parts_stripped = source_path.parts[:-1] + (source_path.stem,)
+        if file_parts_stripped[-n:] != self._source_parts:
+            raise RuntimeError(
+                f"Source file {source_path} doesn't end with parts {self._source_parts}"
+            )
+        prefix = file_parts_stripped[:-n]
+        target_with_ext = self._target_parts[:-1] + (self._target_parts[-1] + ".py",)
+        return Path(*prefix, *target_with_ext)
+
+    def _find_source_path(self) -> Path:
+        parent_parts = self._source_parts[:-1]
+        file_name = self._source_parts[-1] + ".py"
+        n_parent = len(parent_parts)
+
+        matches: list[Path] = []
+        for root in self.scope_roots:
+            for init_file in root.rglob("__init__.py"):
+                if any(part in SKIP_DIR_NAMES for part in init_file.parent.parts):
+                    continue
+                pkg_dir = init_file.parent
+                if len(pkg_dir.parts) < n_parent:
+                    continue
+                if pkg_dir.parts[-n_parent:] != parent_parts:
+                    continue
+                candidate = pkg_dir / file_name
+                if candidate.is_file():
+                    matches.append(candidate)
+
+        unique = list({str(m): m for m in matches}.values())
+
+        if not unique:
+            roots_str = ", ".join(str(r) for r in self.scope_roots)
+            raise FileNotFoundError(
+                f"No module file matching '{self.source}' under: {roots_str}"
+            )
+        if len(unique) > 1:
+            joined = "\n  ".join(str(m) for m in unique)
+            raise ValueError(
+                f"Multiple modules match '{self.source}', refine the dotted name:\n  {joined}"
+            )
+        return unique[0]