Python Bulk File Renamer Project

"""Preview and safely rename files in one folder using numbered names."""

from __future__ import annotations

import argparse
import uuid
from dataclasses import dataclass
from pathlib import Path


@dataclass(frozen=True)
class Rename:
    source: Path
    destination: Path


def build_plan(
    folder: Path,
    prefix: str,
    start: int = 1,
    padding: int = 3,
    extension: str | None = None,
) -> list[Rename]:
    if not folder.is_dir():
        raise ValueError(f"Folder does not exist: {folder}")
    if not prefix or any(character in prefix for character in '<>:"/\\|?*'):
        raise ValueError("Prefix must be non-empty and cannot contain filename separators.")
    if start < 0 or padding < 1:
        raise ValueError("Start must be zero or greater, and padding must be at least 1.")

    normalized_extension = None
    if extension:
        normalized_extension = "." + extension.lower().lstrip(".")

    files = sorted(
        (
            path
            for path in folder.iterdir()
            if path.is_file()
            and (normalized_extension is None or path.suffix.lower() == normalized_extension)
        ),
        key=lambda path: path.name.casefold(),
    )
    plan = [
        Rename(source, folder / f"{prefix}_{number:0{padding}d}{source.suffix.lower()}")
        for number, source in enumerate(files, start=start)
    ]

    source_keys = {item.source.name.casefold() for item in plan}
    destination_keys: set[str] = set()
    for item in plan:
        key = item.destination.name.casefold()
        if key in destination_keys:
            raise ValueError(f"Two files would receive the same name: {item.destination.name}")
        destination_keys.add(key)
        if item.destination.exists() and key not in source_keys:
            raise ValueError(f"A different file already uses the target name: {item.destination.name}")
    return plan


def apply_plan(plan: list[Rename]) -> None:
    """Use temporary names so swaps and overlapping target names remain safe."""
    staged: list[tuple[Rename, Path]] = []
    completed: list[Rename] = []
    try:
        for item in plan:
            temporary = item.source.with_name(f".bulk-rename-{uuid.uuid4().hex}{item.source.suffix}")
            item.source.rename(temporary)
            staged.append((item, temporary))
        for item, temporary in staged:
            temporary.rename(item.destination)
            completed.append(item)
    except OSError:
        for item in reversed(completed):
            if item.destination.exists() and not item.source.exists():
                item.destination.rename(item.source)
        for item, temporary in reversed(staged[len(completed) :]):
            if temporary.exists() and not item.source.exists():
                temporary.rename(item.source)
        raise


def parse_args() -> argparse.Namespace:
    parser = argparse.ArgumentParser(description="Preview and bulk-rename files in one folder.")
    parser.add_argument("folder", type=Path)
    parser.add_argument("--prefix", required=True)
    parser.add_argument("--start", type=int, default=1)
    parser.add_argument("--padding", type=int, default=3)
    parser.add_argument("--extension", help="Only rename this extension, for example jpg")
    parser.add_argument("--apply", action="store_true", help="Apply the previewed plan")
    return parser.parse_args()


def main() -> None:
    args = parse_args()
    try:
        plan = build_plan(args.folder, args.prefix, args.start, args.padding, args.extension)
    except (ValueError, OSError) as error:
        raise SystemExit(f"Cannot create rename plan: {error}") from error

    if not plan:
        print("No matching files found.")
        return
    print("Rename preview:")
    for item in plan:
        print(f"- {item.source.name} -> {item.destination.name}")

    if not args.apply:
        print("\nPreview only. Run again with --apply after checking every name.")
        return
    if input("Type RENAME to continue: ").strip() != "RENAME":
        print("Cancelled. No files were renamed.")
        return

    try:
        apply_plan(plan)
    except OSError as error:
        raise SystemExit(f"Rename failed; rollback was attempted: {error}") from error
    print(f"Renamed {len(plan)} file(s).")


if __name__ == "__main__":
    main()