pystou 0.1.0__py3-none-any.whl

cleanup/main.py

@@ -0,0 +1,310 @@
+#!/usr/bin/env python3
+"""Cleanup subcommand for removing junk files from directories."""
+
+import argparse
+import logging
+import os
+import shutil
+from pathlib import Path
+from typing import Optional
+
+from common.cli import add_common_arguments
+from common.interrupt import scanning
+from common.logger import log_configuration, setup_logging
+from common.validation import validate_directory_or_exit
+
+# Default junk file patterns
+JUNK_FILES: set[str] = {
+    ".DS_Store",
+    "._.DS_Store",
+    "Thumbs.db",
+    "desktop.ini",
+    ".Spotlight-V100",
+    ".Trashes",
+    "ehthumbs.db",
+    "ehthumbs_vista.db",
+}
+
+# Junk file prefixes (macOS resource forks)
+JUNK_PREFIXES: set[str] = {
+    "._",
+}
+
+# Junk directories
+JUNK_DIRS: set[str] = {
+    "__MACOSX",
+    ".AppleDouble",
+    ".LSOverride",
+    ".TemporaryItems",
+    ".fseventsd",
+}
+
+
+def add_cleanup_arguments(parser: argparse.ArgumentParser) -> None:
+    """Adds cleanup-specific arguments to the parser.
+
+    Args:
+        parser: ArgumentParser to add arguments to.
+    """
+    add_common_arguments(parser)
+    parser.add_argument(
+        "--include",
+        type=str,
+        action="append",
+        metavar="PATTERN",
+        help="Additional file/directory names to remove (can be used multiple times)",
+    )
+    parser.add_argument(
+        "--list-only",
+        action="store_true",
+        help="Only list junk files without removing them",
+    )
+
+
+def main(args: Optional[argparse.Namespace] = None) -> None:
+    """Main entry point for cleanup.
+
+    Args:
+        args: Parsed arguments. If None, parses from command line.
+    """
+    if args is None:
+        parser = argparse.ArgumentParser(description="Cleanup junk files script.")
+        add_cleanup_arguments(parser)
+        args = parser.parse_args()
+
+    setup_logging("cleanup", args.log_dir)
+    log_configuration(args)
+
+    validate_directory_or_exit(args.directory)
+
+    # Build the set of patterns to match
+    junk_files = JUNK_FILES.copy()
+    junk_dirs = JUNK_DIRS.copy()
+    if args.include:
+        for pattern in args.include:
+            junk_files.add(pattern)
+
+    # Find junk files
+    with scanning("scan"):
+        junk_items = find_junk(args.directory, args.recursive, junk_files, junk_dirs)
+
+    if not junk_items:
+        print("No junk files found.")
+        logging.info({"action": "no_junk_found"})
+        return
+
+    print(f"Found {len(junk_items)} junk item(s):")
+    for item in junk_items:
+        print(f"  {item}")
+
+    logging.info(
+        {
+            "action": "junk_found",
+            "count": len(junk_items),
+            "items": [str(i) for i in junk_items],
+        }
+    )
+
+    if args.list_only:
+        print("\n(Use without --list-only to remove)")
+        return
+
+    if args.dry_run:
+        print("\nDry run: would remove the above items")
+        logging.info({"action": "cleanup", "status": "dry_run"})
+        return
+
+    # Remove junk files
+    with scanning("removal"):
+        removed_count, skipped_count = remove_junk(junk_items)
+
+    print(f"\nRemoved {removed_count}/{len(junk_items)} item(s)")
+    if skipped_count > 0:
+        print(f"Skipped {skipped_count} item(s) due to errors")
+    logging.info(
+        {
+            "action": "cleanup_complete",
+            "removed": removed_count,
+            "skipped": skipped_count,
+            "total": len(junk_items),
+        }
+    )
+
+
+def find_junk(
+    directory: str,
+    recursive: bool,
+    junk_files: set[str],
+    junk_dirs: set[str],
+) -> list[Path]:
+    """Finds junk files and directories.
+
+    Args:
+        directory: Directory to search.
+        recursive: Whether to search recursively.
+        junk_files: Set of junk file names.
+        junk_dirs: Set of junk directory names.
+
+    Returns:
+        List of paths to junk items.
+    """
+    junk_items: list[Path] = []
+    directory_path = Path(directory)
+    scanned = 0
+
+    if recursive:
+        # followlinks=False prevents infinite loops from symlink cycles
+        for root, dirs, files in os.walk(directory_path, followlinks=False):
+            root_path = Path(root)
+            scanned += 1
+
+            # Progress indicator every 1000 directories
+            if scanned % 1000 == 0:
+                print(f"Scanned {scanned} directories...", end="\r")
+
+            # Check for junk directories
+            for dir_name in dirs[:]:  # Copy to allow modification
+                dir_path = root_path / dir_name
+                # Skip symlinks to avoid issues
+                if dir_path.is_symlink():
+                    continue
+                if dir_name in junk_dirs:
+                    junk_items.append(dir_path)
+                    dirs.remove(dir_name)  # Don't descend into junk dirs
+
+            # Check for junk files
+            for file_name in files:
+                file_path = root_path / file_name
+                # Skip symlinks
+                if file_path.is_symlink():
+                    continue
+                if is_junk_file(file_name, junk_files):
+                    junk_items.append(file_path)
+    else:
+        try:
+            for entry in os.scandir(directory_path):
+                # Skip symlinks
+                if entry.is_symlink():
+                    continue
+                if (entry.is_dir(follow_symlinks=False) and entry.name in junk_dirs) or (
+                    entry.is_file(follow_symlinks=False) and is_junk_file(entry.name, junk_files)
+                ):
+                    junk_items.append(Path(entry.path))
+        except PermissionError as e:
+            print(f"Permission denied: {directory_path}")
+            logging.warning({"action": "scan_error", "path": str(directory_path), "error": str(e)})
+
+    if scanned >= 1000:
+        print(f"Scanned {scanned} directories.    ")  # Clear progress line
+
+    return junk_items
+
+
+def is_junk_file(filename: str, junk_files: set[str]) -> bool:
+    """Checks if a filename is a junk file.
+
+    Args:
+        filename: Name of the file.
+        junk_files: Set of junk file names.
+
+    Returns:
+        True if the file is junk, False otherwise.
+    """
+    if filename in junk_files:
+        return True
+
+    # Check prefixes (e.g., ._ files)
+    return any(filename.startswith(prefix) for prefix in JUNK_PREFIXES)
+
+
+def remove_junk(junk_items: list[Path]) -> tuple:
+    """Removes junk files and directories.
+
+    Args:
+        junk_items: List of paths to remove.
+
+    Returns:
+        Tuple of (removed_count, skipped_count).
+    """
+    removed = 0
+    skipped = 0
+    total = len(junk_items)
+
+    for i, item in enumerate(junk_items, 1):
+        # Progress indicator
+        if total > 10 and i % 10 == 0:
+            print(f"Removing {i}/{total}...", end="\r")
+
+        try:
+            if not item.exists():
+                # File was already deleted (race condition)
+                logging.warning(
+                    {
+                        "action": "remove_junk",
+                        "status": "already_deleted",
+                        "path": str(item),
+                    }
+                )
+                skipped += 1
+                continue
+
+            if item.is_symlink():
+                # Don't follow symlinks, just remove the link
+                item.unlink()
+            elif item.is_dir():
+                shutil.rmtree(item)
+            else:
+                item.unlink()
+
+            removed += 1
+            logging.info(
+                {
+                    "action": "remove_junk",
+                    "status": "success",
+                    "path": str(item),
+                }
+            )
+
+        except FileNotFoundError:
+            # Race condition: file deleted between check and removal
+            logging.warning(
+                {
+                    "action": "remove_junk",
+                    "status": "not_found",
+                    "path": str(item),
+                }
+            )
+            skipped += 1
+
+        except PermissionError as e:
+            print(f"Permission denied: {item}")
+            logging.error(
+                {
+                    "action": "remove_junk",
+                    "status": "permission_denied",
+                    "path": str(item),
+                    "error": str(e),
+                }
+            )
+            skipped += 1
+
+        except OSError as e:
+            print(f"Error removing {item}: {e}")
+            logging.error(
+                {
+                    "action": "remove_junk",
+                    "status": "error",
+                    "path": str(item),
+                    "error": str(e),
+                }
+            )
+            skipped += 1
+
+    if total > 10:
+        print(f"Removed {removed}/{total} items.    ")  # Clear progress line
+
+    return removed, skipped
+
+
+if __name__ == "__main__":
+    main()

common/cli.py

@@ -0,0 +1,37 @@
+import argparse
+
+
+def add_common_arguments(parser: argparse.ArgumentParser) -> None:
+    """Adds common arguments to an ArgumentParser.
+
+    Args:
+        parser: ArgumentParser to add arguments to.
+    """
+    parser.add_argument(
+        "directory",
+        nargs="?",
+        default=".",
+        help="Directory to start from (default: current directory)",
+    )
+    parser.add_argument(
+        "-r",
+        "--recursive",
+        action="store_true",
+        help="Recursively process subdirectories",
+    )
+    parser.add_argument(
+        "-n",
+        "--dry-run",
+        action="store_true",
+        help="Perform a dry run (do not make any changes)",
+    )
+    parser.add_argument(
+        "--log-dir",
+        default=".",
+        help="Directory to store log files (default: current directory)",
+    )
+    parser.add_argument(
+        "--db-dir",
+        default=".",
+        help="Directory to store index database (default: current directory)",
+    )

common/cursor.py

@@ -0,0 +1,98 @@
+"""Cursor utilities for terminal progress display."""
+
+import atexit
+import contextlib
+import signal
+import sys
+from typing import Optional
+
+# ANSI escape codes for cursor control
+HIDE_CURSOR = "\033[?25l"
+SHOW_CURSOR = "\033[?25h"
+
+# Track cursor state
+_cursor_hidden = False
+_original_sigint: Optional[signal.Handlers] = None
+_original_sigterm: Optional[signal.Handlers] = None
+
+
+def hide_cursor() -> None:
+    """Hides the terminal cursor and registers cleanup handlers."""
+    global _cursor_hidden, _original_sigint, _original_sigterm
+
+    if _cursor_hidden:
+        return
+
+    # Only hide if stdout is a terminal
+    if not sys.stdout.isatty():
+        return
+
+    sys.stdout.write(HIDE_CURSOR)
+    sys.stdout.flush()
+    _cursor_hidden = True
+
+    # Register atexit handler for normal exit
+    atexit.register(show_cursor)
+
+    # Store original signal handlers and install our own
+    _original_sigint = signal.getsignal(signal.SIGINT)
+    _original_sigterm = signal.getsignal(signal.SIGTERM)
+
+    signal.signal(signal.SIGINT, _signal_handler)
+    signal.signal(signal.SIGTERM, _signal_handler)
+
+
+def show_cursor() -> None:
+    """Shows the terminal cursor and removes cleanup handlers."""
+    global _cursor_hidden, _original_sigint, _original_sigterm
+
+    if not _cursor_hidden:
+        return
+
+    # Only show if stdout is a terminal
+    if sys.stdout.isatty():
+        sys.stdout.write(SHOW_CURSOR)
+        sys.stdout.flush()
+
+    _cursor_hidden = False
+
+    # Unregister atexit handler
+    with contextlib.suppress(Exception):
+        atexit.unregister(show_cursor)
+
+    # Restore original signal handlers
+    if _original_sigint is not None:
+        with contextlib.suppress(Exception):
+            signal.signal(signal.SIGINT, _original_sigint)
+        _original_sigint = None
+
+    if _original_sigterm is not None:
+        with contextlib.suppress(Exception):
+            signal.signal(signal.SIGTERM, _original_sigterm)
+        _original_sigterm = None
+
+
+def _signal_handler(signum: int, frame) -> None:
+    """Signal handler that restores cursor before re-raising."""
+    global _original_sigint, _original_sigterm
+
+    # Capture original handlers BEFORE show_cursor clears them
+    if signum == signal.SIGINT and _original_sigint is not None:
+        original = _original_sigint
+    elif signum == signal.SIGTERM and _original_sigterm is not None:
+        original = _original_sigterm
+    else:
+        original = signal.SIG_DFL
+
+    # Restore cursor (this clears _original_sigint/_original_sigterm)
+    show_cursor()
+
+    # Re-raise with original handler
+    if original == signal.SIG_DFL:
+        # Default behavior - raise KeyboardInterrupt for SIGINT
+        if signum == signal.SIGINT:
+            raise KeyboardInterrupt
+        else:
+            sys.exit(128 + signum)
+    elif original != signal.SIG_IGN and callable(original):
+        original(signum, frame)

common/errors.py

@@ -0,0 +1,9 @@
+"""Typed exceptions used to distinguish expected failures from bugs."""
+
+
+class PystouError(Exception):
+    """Base class for expected, explained PyStou errors."""
+
+
+class InvalidDirectoryError(PystouError):
+    """Raised when a target directory is missing or is not a directory."""

common/fs_walker.py

@@ -0,0 +1,178 @@
+import logging
+import os
+import sqlite3
+from pathlib import Path
+from typing import Optional
+
+
+class ScanContext:
+    """Context object to track scanning state efficiently."""
+
+    __slots__ = ("_last_update", "dir_count", "file_count", "update_interval")
+
+    def __init__(self, update_interval: int = 100):
+        self.dir_count = 0
+        self.file_count = 0
+        self.update_interval = update_interval
+        self._last_update = 0
+
+    def increment_dirs(self) -> None:
+        self.dir_count += 1
+        self._maybe_update_output()
+
+    def increment_files(self) -> None:
+        self.file_count += 1
+        self._maybe_update_output()
+
+    def _maybe_update_output(self) -> None:
+        total = self.dir_count + self.file_count
+        if total - self._last_update >= self.update_interval:
+            self._last_update = total
+            update_live_output(self.dir_count, self.file_count)
+
+    def final_update(self) -> None:
+        update_live_output(self.dir_count, self.file_count)
+        print()  # Newline after scanning complete
+
+
+def collect_directories(
+    conn: sqlite3.Connection,
+    directory: str,
+    recursive: bool,
+    level: Optional[int] = None,
+) -> None:
+    """Scans the filesystem and populates the database.
+
+    Args:
+        conn (sqlite3.Connection): SQLite database connection.
+        directory (str): Directory to start scanning from.
+        recursive (bool): Whether to scan directories recursively.
+        level (Optional[int]): Maximum depth level for recursion (default: unlimited).
+    """
+    ctx = ScanContext(update_interval=100)
+    clear_database(conn)
+    scan_tree(Path(directory), conn, recursive, level, ctx)
+    ctx.final_update()
+
+
+def scan_tree(
+    root_dir: Path,
+    conn: sqlite3.Connection,
+    recursive: bool,
+    level: Optional[int],
+    ctx: ScanContext,
+) -> None:
+    """Scans a tree iteratively (explicit stack avoids RecursionError on deep trees).
+
+    Args:
+        root_dir (Path): Directory to start from.
+        conn (sqlite3.Connection): SQLite database connection.
+        recursive (bool): Whether to scan recursively.
+        level (Optional[int]): Maximum depth level for recursion.
+        ctx (ScanContext): Scanning context for counters and output.
+    """
+    stack: list[tuple[Path, int]] = [(root_dir, 1)]
+    while stack:
+        current_dir, current_level = stack.pop()
+        try:
+            with os.scandir(current_dir) as entries:
+                dir_entries: list[tuple[str, str, float]] = []
+                file_entries: list[tuple[str, str, int, float]] = []
+                subdirs: list[Path] = []
+                for entry in entries:
+                    full_path = Path(entry.path)
+                    try:
+                        if entry.is_dir(follow_symlinks=False):
+                            stat_info = entry.stat(follow_symlinks=False)
+                            dir_entries.append(
+                                (str(full_path), str(current_dir), stat_info.st_mtime)
+                            )
+                            ctx.increment_dirs()
+                            if recursive and (level is None or current_level < level):
+                                subdirs.append(full_path)
+                        elif entry.is_file(follow_symlinks=False):
+                            stat_info = entry.stat(follow_symlinks=False)
+                            file_entries.append(
+                                (
+                                    str(current_dir),
+                                    entry.name,
+                                    stat_info.st_size,
+                                    stat_info.st_mtime,
+                                )
+                            )
+                            ctx.increment_files()
+                    except OSError as e:
+                        # One bad entry must not abort its siblings.
+                        logging.warning(
+                            {
+                                "action": "scan_entry_error",
+                                "path": str(full_path),
+                                "error": str(e),
+                            }
+                        )
+                insert_entries(conn, dir_entries, file_entries)
+                # reversed() so siblings are popped in scandir order (matches the
+                # original recursive traversal).
+                for subdir in reversed(subdirs):
+                    stack.append((subdir, current_level + 1))
+        except PermissionError as e:
+            print(f"\nPermission denied: {current_dir}")
+            logging.error({"action": "scan_error", "directory": str(current_dir), "error": str(e)})
+        except OSError as e:
+            logging.warning(
+                {"action": "scan_error", "directory": str(current_dir), "error": str(e)}
+            )
+
+
+def clear_database(conn: sqlite3.Connection) -> None:
+    """Clears existing data from the database.
+
+    Args:
+        conn (sqlite3.Connection): SQLite database connection.
+    """
+    cursor = conn.cursor()
+    cursor.execute("DELETE FROM directories")
+    cursor.execute("DELETE FROM files")
+    conn.commit()
+
+
+def update_live_output(dir_count: int, file_count: int) -> None:
+    """Updates the live scanning output.
+
+    Args:
+        dir_count (int): Number of directories scanned.
+        file_count (int): Number of files scanned.
+    """
+    formatted_dir_count = f"{dir_count:,}"
+    formatted_file_count = f"{file_count:,}"
+    print(
+        f"Scanning directories: {formatted_dir_count}, files: {formatted_file_count}",
+        end="\r",
+        flush=True,
+    )
+
+
+def insert_entries(
+    conn: sqlite3.Connection,
+    dir_entries: list[tuple[str, str, float]],
+    file_entries: list[tuple[str, str, int, float]],
+) -> None:
+    """Inserts directory and file entries into the database.
+
+    Args:
+        conn (sqlite3.Connection): SQLite database connection.
+        dir_entries (List[Tuple[str, str, float]]): List of directory entries.
+        file_entries (List[Tuple[str, str, int, float]]): List of file entries.
+    """
+    cursor = conn.cursor()
+    if dir_entries:
+        cursor.executemany(
+            "INSERT OR IGNORE INTO directories (path, parent_path, mtime) VALUES (?, ?, ?)",
+            dir_entries,
+        )
+    if file_entries:
+        cursor.executemany(
+            "INSERT OR IGNORE INTO files (directory_path, name, size, mtime) VALUES (?, ?, ?, ?)",
+            file_entries,
+        )
+    conn.commit()