Skip to content

Bulk rename

Rename many files with find/replace, a live preview, a confirmation dialog and undo.

Same example in PowerShell: Bulk rename

Bulk rename

Real capture on KDE Plasma 6.6 Wayland with the released packages.

What it teaches: open_file with index.html and style.css; pure planning logic; live preview; folder dialog fallback; undo.

Run it

uv init --app myapp && cd myapp    # once: a uv project for your app
uv add nativehtmlkit
# save the example file(s) in the project folder, then:
uv run bulk_rename/app.py

Related guide: project scaffolding

Source: bulk_rename/app.py

View on GitHub

"""Bulk rename: rename many files with find/replace, a live preview and undo.

This is the finished app of the tutorial docs/tutorials/bulk-rename.md.

What it teaches
  * an app split into index.html + style.css + app.py (``Application.open_file``)
  * a pure planning function that is easy to test without a window
  * live preview on ``input``/``change`` events of a whole form
  * the native folder picker with a capability check and an ``RpcError`` fallback
  * a confirmation ``<dialog>``, per-file error handling, and undo

Run:  uv run bulk_rename/app.py [FOLDER]
In regular-expression mode the replacement uses Python syntax: ``\\1`` or ``\\g<1>`` for groups.
"""
from __future__ import annotations

import html
import os
import re
import sys
from dataclasses import dataclass
from pathlib import Path

from nativehtmlkit import Application, Document, RpcError

HERE = Path(__file__).resolve().parent
WINDOWS = sys.platform == "win32"
INVALID_CHARACTERS = set('<>:"/\\|?*' + "".join(map(chr, range(32)))) if WINDOWS else {"/", "\0"}


# ---------------------------------------------------------------------------- planning (no UI)

@dataclass
class Row:
    old: str
    new: str
    status: str = "unchanged"     # unchanged | rename | conflict | invalid | error
    note: str = ""


def plan_renames(names: list[str], find: str, replace: str, *, regex: bool, match_case: bool) -> list[Row]:
    """One row per file name; never touches the disk."""
    rows = [Row(name, name) for name in names]
    if not find:
        return rows
    try:
        pattern = re.compile(find if regex else re.escape(find), 0 if match_case else re.IGNORECASE)
        # Plain-text mode: the replacement is literal text (a function bypasses \1 processing).
        replacement = replace if regex else (lambda _match: replace)
        new_names = [pattern.sub(replacement, name) for name in names]
    except (re.error, IndexError) as error:          # bad pattern, or \3 with only two groups
        for row in rows:
            row.status, row.note = "error", f"Invalid pattern: {error}"
        return rows

    def key(name: str) -> str:                       # Windows file names are case-insensitive
        return name.casefold() if WINDOWS else name

    existing = {key(name) for name in names}
    claimed: set[str] = set()
    for row, new in zip(rows, new_names):
        row.new = new
        if new == row.old:
            continue
        if not new or new in (".", "..") or INVALID_CHARACTERS & set(new):
            row.status, row.note = "invalid", "Not a valid file name"
        elif (key(new) in existing and key(new) != key(row.old)) or key(new) in claimed:
            row.status, row.note = "conflict", "Name already used"
        else:
            row.status = "rename"
            claimed.add(key(new))
    return rows


# ---------------------------------------------------------------------------------- the app

class BulkRename:
    def __init__(self, app: Application, window):
        self.app, self.window, self.document = app, window, window.document
        self.folder: Path | None = None
        self.names: list[str] = []
        self.plan: list[Row] = []
        self.undo_steps: list[tuple[str, str]] = []
        doc = self.document
        # The top-level flag says whether the host offers native dialogs in this session.
        # (features["file_dialogs"]["available"] is None, "not observed", on a native desktop.)
        if not app.capabilities().get("file_dialogs"):
            doc.set_attribute("browse", "disabled", "")
        # Live preview: every keystroke or checkbox change in the rule form.
        doc.on("input", lambda _event: self.update_preview(), element="rule")
        doc.on("change", lambda _event: self.update_preview(), element="rule")
        # Enter in a rule field submits the form: treat it as "update preview", nothing else.
        doc.on("submit", lambda _event: self.update_preview(), element="rule")
        doc.on("click", lambda _event: self.open_folder(doc.get_value("folder")), element="load")
        doc.on("click", lambda _event: self.browse(), element="browse")
        doc.on("click", lambda _event: self.ask_confirmation(), element="apply")
        # Decide in the button handlers, not in the dialog's close event: a <dialog> keeps its
        # previous return value when the user dismisses it with Escape.
        doc.on("click", lambda _event: self.confirm(False), element="confirm-no")
        doc.on("click", lambda _event: self.confirm(True), element="confirm-yes")
        doc.on("click", lambda _event: self.undo(), element="undo")

    def set_summary(self, text: str) -> None:
        self.document.set_text("summary", text)

    def set_enabled(self, element: str, enabled: bool) -> None:
        if enabled:
            self.document.remove_attribute(element, "disabled")
        else:
            self.document.set_attribute(element, "disabled", "")

    def update_preview(self) -> None:
        doc = self.document
        self.plan = plan_renames(self.names, doc.get_value("find"), doc.get_value("replace"),
                                 regex=doc.get_checked("regex"), match_case=doc.get_checked("case"))
        # File names are untrusted text: escape every cell. The status class comes from a fixed set.
        cells = "".join(f'<tr class="{row.status}"><td>{html.escape(row.old)}</td><td>{html.escape(row.new)}</td>'
                        f'<td>{html.escape(row.note or row.status)}</td></tr>' for row in self.plan)
        count = sum(row.status == "rename" for row in self.plan)
        blocked = sum(row.status in ("conflict", "invalid", "error") for row in self.plan)
        summary = f"{len(self.names)} file(s), {count} to rename" + (f", {blocked} skipped" if blocked else "")
        doc.batch([
            {"op": "replace_children_html", "element": "preview", "html": cells},
            {"op": "set_text", "element": "summary", "text": summary},
            {"op": "set_text", "element": "apply", "text": f"Rename {count}"},
        ])
        self.set_enabled("apply", count > 0)

    def update_file_list(self) -> None:
        self.names = sorted(entry.name for entry in self.folder.iterdir() if entry.is_file())
        self.update_preview()

    def open_folder(self, path: str) -> None:
        if not path or not Path(path).is_dir():
            self.set_summary("That folder does not exist.")
            return
        self.folder = Path(path).resolve()
        self.document.set_value("folder", str(self.folder))
        self.set_undo([])
        self.update_file_list()

    def browse(self) -> None:
        def done(future) -> None:
            try:
                result = future.result()
            except RpcError as error:        # -32001: no dialog service in this session
                self.set_summary("Native file dialogs are not available in this session."
                                 if error.code == -32001 else f"The folder dialog failed (error {error.code}).")
                return
            if not result["cancelled"]:
                self.open_folder(result["paths"][0])
        # wait=False keeps the event thread free while the dialog is open.
        self.window.choose_folder(title="Folder with files to rename", wait=False).add_done_callback(done)

    def set_undo(self, steps: list[tuple[str, str]]) -> None:
        self.undo_steps = steps
        self.set_enabled("undo", bool(steps))

    def ask_confirmation(self) -> None:
        count = sum(row.status == "rename" for row in self.plan)
        self.document.set_text("confirm-text", f"Rename {count} file(s) in {self.folder}?")
        self.document.show_dialog("confirm")

    def confirm(self, yes: bool) -> None:
        self.document.close_dialog("confirm", "")
        if yes:
            self.rename()

    def rename(self) -> None:
        done, failed = [], 0
        for row in (r for r in self.plan if r.status == "rename"):
            source, target = self.folder / row.old, self.folder / row.new
            try:
                # os.rename silently replaces an existing file on Linux: refuse that ourselves.
                if target.exists() and not (WINDOWS and row.old.casefold() == row.new.casefold()):
                    raise FileExistsError(target)
                os.rename(source, target)
                done.append((row.old, row.new))
            except OSError:                   # in use, permission denied, or changed since the preview
                failed += 1
        self.set_undo(done)
        self.update_file_list()
        message = f"Renamed {len(done)} file(s)."
        if failed:
            message += f" {failed} failed (in use, permission denied or changed)."
        self.set_summary(message)

    def undo(self) -> None:
        if not self.undo_steps:
            return
        restored = 0
        # Reverse order, so chains such as a->b, b->c are undone correctly.
        for old, new in reversed(self.undo_steps):
            try:
                os.rename(self.folder / new, self.folder / old)
                restored += 1
            except OSError:
                pass
        self.set_undo([])
        self.update_file_list()
        self.set_summary(f"Restored {restored} file name(s).")


def build(app: Application, folder: str | None = None) -> BulkRename:
    # Relative URLs in index.html (style.css) resolve against the file's folder.
    window = app.open_file(HERE / "index.html", title="Bulk rename", width=900, height=620,
                           min_width=640, min_height=400)
    tool = BulkRename(app, window)
    if folder:
        tool.open_folder(folder)
    return tool


def main() -> None:
    with Application.start(name="Bulk rename") as app:
        build(app, sys.argv[1] if len(sys.argv) > 1 else None)
        app.run()


if __name__ == "__main__":
    main()