filecraft-cli 1.0.0__py3-none-any.whl

file_organiser_python/constants.py

@@ -0,0 +1,171 @@
+# -------------------------
+# Images
+# -------------------------
+
+IMAGE_EXTENSIONS = {
+    ".jpg",
+    ".jpeg",
+    ".png",
+    ".gif",
+    ".bmp",
+    ".tiff",
+    ".tif",
+    ".webp",
+    ".svg",
+    ".heic",
+    ".heif",
+    ".ico",
+    ".raw",
+    ".cr2",
+    ".nef",
+    ".orf",
+    ".sr2",
+    ".psd",
+    ".ai",
+    ".eps",
+}
+
+# -------------------------
+# Documents
+# -------------------------
+
+DOCUMENT_EXTENSIONS = {
+    ".pdf",
+    ".doc",
+    ".docx",
+    ".odt",
+    ".rtf",
+    ".txt",
+    ".md",
+    ".pages",
+    ".tex",
+}
+
+# -------------------------
+# Spreadsheets
+# -------------------------
+
+SPREADSHEET_EXTENSIONS = {".xls", ".xlsx", ".xlsm", ".ods", ".csv", ".tsv"}
+
+# -------------------------
+# Presentations
+# -------------------------
+
+PRESENTATION_EXTENSIONS = {".ppt", ".pptx", ".odp", ".key"}
+
+# -------------------------
+# Videos
+# -------------------------
+
+VIDEO_EXTENSIONS = {
+    ".mp4",
+    ".mkv",
+    ".mov",
+    ".avi",
+    ".wmv",
+    ".flv",
+    ".webm",
+    ".mpeg",
+    ".mpg",
+    ".3gp",
+    ".m4v",
+}
+
+# -------------------------
+# Audio
+# -------------------------
+
+AUDIO_EXTENSIONS = {
+    ".mp3",
+    ".wav",
+    ".aac",
+    ".flac",
+    ".ogg",
+    ".m4a",
+    ".wma",
+    ".aiff",
+    ".alac",
+}
+
+# -------------------------
+# Archives / Compressed
+# -------------------------
+
+ARCHIVE_EXTENSIONS = {
+    ".zip",
+    ".rar",
+    ".7z",
+    ".tar",
+    ".gz",
+    ".bz2",
+    ".xz",
+    ".tgz",
+    ".tar.gz",
+}
+
+# -------------------------
+# Executables
+# -------------------------
+
+EXECUTABLE_EXTENSIONS = {
+    ".exe",
+    ".msi",
+    ".apk",
+    ".app",
+    ".deb",
+    ".rpm",
+    ".dmg",
+    ".bin",
+    ".sh",
+    ".bat",
+}
+
+# -------------------------
+# Code / Programming
+# -------------------------
+
+CODE_EXTENSIONS = {
+    ".py",
+    ".js",
+    ".ts",
+    ".jsx",
+    ".tsx",
+    ".java",
+    ".c",
+    ".cpp",
+    ".h",
+    ".hpp",
+    ".cs",
+    ".go",
+    ".rs",
+    ".php",
+    ".rb",
+    ".swift",
+    ".kt",
+    ".html",
+    ".css",
+    ".scss",
+    ".json",
+    ".xml",
+    ".yaml",
+    ".yml",
+    ".sql",
+}
+
+# -------------------------
+# Fonts
+# -------------------------
+
+FONT_EXTENSIONS = {".ttf", ".otf", ".woff", ".woff2", ".eot"}
+
+# -------------------------
+# Disk Images
+# -------------------------
+
+DISK_IMAGE_EXTENSIONS = {".iso", ".img", ".vhd", ".vmdk"}
+
+# -------------------------
+# HISTORY FILE NAME PREFIX
+# -------------------------
+
+HISTORY_FILE_PREFIX = ".organizer_history_"

file_organiser_python/enums.py

@@ -0,0 +1,8 @@
+from enum import Enum
+
+
+class SeparateChoices(Enum):
+    EXTENSION = "extension"
+    DATE = "date"
+    EXTENSION_AND_DATE = "extension_and_date"
+    FILE = "file"

file_organiser_python/history.py

@@ -0,0 +1,88 @@
+from pathlib import Path
+import json
+from typing import Dict, Optional
+
+from file_organiser_python.utils import build_non_conflicting_path
+
+
+def save_history(
+    history_path: Path,
+    revert_map: Dict[str, str],
+    operation: str = "rename",
+) -> None:
+    data = {
+        "operation": operation,
+        "mappings": revert_map,
+    }
+
+    history_path.parent.mkdir(parents=True, exist_ok=True)
+    with open(history_path, "w", encoding="utf-8") as f:
+        json.dump(data, f, indent=4)
+
+
+def load_latest_history(directory: Path) -> Path | None:
+    history_files = list(directory.glob(".organizer_history_*.json"))
+
+    if not history_files:
+        return None
+
+    return max(history_files, key=lambda f: f.stat().st_mtime)
+
+
+def read_history(history_path: Path) -> Dict[str, str]:
+    with open(history_path, "r", encoding="utf-8") as f:
+        data = json.load(f)
+
+    return data.get("mappings", {})
+
+
+def delete_history(history_path: Path) -> None:
+    if history_path.exists():
+        history_path.unlink()
+
+
+def revert_history(
+    history_path: Optional[Path] = None,
+    directory: Optional[Path] = None,
+    dry_run: bool = False,
+    delete_after_revert: bool = True,
+) -> int:
+    if history_path is None:
+        if directory is None:
+            directory = Path.cwd()
+
+        history_path = load_latest_history(directory)
+        if history_path is None:
+            print(f"No history file found in {directory}")
+            return 0
+
+    with open(history_path, "r", encoding="utf-8") as f:
+        data = json.load(f)
+
+    mappings: Dict[str, str] = data.get("mappings", {})
+    if not mappings:
+        print(f"No mappings found in history file: {history_path}")
+        return 0
+
+    reverted_count = 0
+    for current, original in mappings.items():
+        current_path = Path(current)
+        original_path = Path(original)
+
+        if not current_path.exists():
+            continue
+
+        if dry_run:
+            print(f"[DRY RUN] Would move {current_path} -> {original_path}")
+            reverted_count += 1
+            continue
+
+        original_path.parent.mkdir(parents=True, exist_ok=True)
+        destination_path = build_non_conflicting_path(original_path)
+        current_path.rename(destination_path)
+        reverted_count += 1
+
+    if reverted_count and delete_after_revert and not dry_run:
+        delete_history(history_path)
+
+    return reverted_count

file_organiser_python/main.py

@@ -0,0 +1,259 @@
+from pathlib import Path
+from datetime import date
+from typing import Optional
+
+import typer
+
+from file_organiser_python.enums import SeparateChoices
+from file_organiser_python.history import revert_history
+from file_organiser_python.organizer import (
+    FileOrganizer,
+    MissingTargetDirectoryError,
+    TargetPathNotDirectoryError,
+)
+from file_organiser_python.utils import validate_directory
+
+app = typer.Typer()
+
+
+def _resolve_target_directory(
+    target_dir: Optional[Path],
+    dry_run: bool,
+) -> Optional[Path]:
+    if not target_dir:
+        return None
+
+    if target_dir.exists():
+        if not target_dir.is_dir():
+            raise typer.BadParameter(
+                f"Path is not a directory: {target_dir}",
+                param_hint="--target-dir",
+            )
+        return target_dir
+
+    if dry_run:
+        typer.echo(f"[DRY RUN] Target directory does not exist: {target_dir}")
+        return target_dir
+
+    if typer.confirm(
+        f"Target directory '{target_dir}' does not exist. Create it?",
+        default=False,
+    ):
+        try:
+            target_dir.mkdir(parents=True, exist_ok=True)
+        except OSError as exc:
+            raise typer.BadParameter(
+                f"Unable to create target directory: {target_dir}",
+                param_hint="--target-dir",
+            ) from exc
+        typer.echo(f"Created target directory: {target_dir.resolve()}")
+        return target_dir
+
+    raise typer.BadParameter(
+        f"Target directory does not exist: {target_dir}",
+        param_hint="--target-dir",
+    )
+
+
+def _validate_optional_directory(path: Optional[Path], option_name: str) -> None:
+    if not path:
+        return
+
+    try:
+        validate_directory(path)
+    except ValueError as exc:
+        raise typer.BadParameter(str(exc), param_hint=option_name) from exc
+
+
+def _validate_optional_iso_date(sort_date: Optional[str]) -> None:
+    if not sort_date:
+        return
+
+    try:
+        date.fromisoformat(sort_date)
+    except ValueError as exc:
+        raise typer.BadParameter(
+            "Date must be in YYYY-MM-DD format.",
+            param_hint="--date",
+        ) from exc
+
+
+def _validate_required_directories(paths: list[Path], option_name: str) -> None:
+    if not paths:
+        raise typer.BadParameter(
+            "At least one working directory is required.",
+            param_hint=option_name,
+        )
+
+    for path in paths:
+        try:
+            validate_directory(path)
+        except ValueError as exc:
+            raise typer.BadParameter(str(exc), param_hint=option_name) from exc
+
+
+@app.command()
+def rename(
+    target_dir: Optional[Path] = typer.Option(
+        None, help="Where renamed files are moved."
+    ),
+    working_dir: Optional[Path] = typer.Option(
+        None, help="Source directory to process."
+    ),
+    dry_run: bool = typer.Option(False, help="Preview actions without making changes."),
+    history: bool = typer.Option(False, "--history", help="Save operation history."),
+    renameWith: Optional[str] = typer.Option(
+        None,
+        "--rename-with",
+        help="Base name to use for renamed files (e.g. 'file' to get 'file_1.pdf', 'file_2.pdf', etc.).",
+    ),
+) -> None:
+    _validate_optional_directory(working_dir, "--working-dir")
+    target_dir = _resolve_target_directory(target_dir, dry_run=dry_run)
+
+    try:
+        organizer = FileOrganizer(
+            target_dir=target_dir,
+            working_dir=working_dir,
+            dry_run=dry_run,
+            save_history=history,
+            renameWith=renameWith,
+        )
+    except (MissingTargetDirectoryError, TargetPathNotDirectoryError) as exc:
+        raise typer.BadParameter(str(exc), param_hint="--target-dir") from exc
+    organizer.rename()
+
+
+@app.command()
+def separate(
+    mode: SeparateChoices = typer.Option(
+        SeparateChoices.EXTENSION,
+        "--mode",
+        help="How to separate files: extension, date, extension_and_date, file.",
+    ),
+    extension: Optional[str] = typer.Option(
+        None,
+        "--extension",
+        help="Extension to filter, e.g. .pdf or pdf.",
+    ),
+    file_type: Optional[str] = typer.Option(
+        None,
+        "--file-type",
+        help="File type filter for --mode file (e.g. documents, images, pdf).",
+    ),
+    sort_date: Optional[str] = typer.Option(
+        None,
+        "--date",
+        help="Date in YYYY-MM-DD format. Defaults to today when mode uses date.",
+    ),
+    target_dir: Optional[Path] = typer.Option(
+        None, help="Where separated files are moved."
+    ),
+    working_dir: Optional[Path] = typer.Option(
+        None, help="Source directory to process."
+    ),
+    dry_run: bool = typer.Option(False, help="Preview actions without making changes."),
+    history: bool = typer.Option(False, "--history", help="Save operation history."),
+) -> None:
+    _validate_optional_directory(working_dir, "--working-dir")
+    _validate_optional_iso_date(sort_date)
+    target_dir = _resolve_target_directory(target_dir, dry_run=dry_run)
+
+    normalized_extension = f".{extension.lstrip('.').lower()}" if extension else None
+
+    try:
+        organizer = FileOrganizer(
+            target_dir=target_dir,
+            working_dir=working_dir,
+            dry_run=dry_run,
+            save_history=history,
+            sort_date=sort_date,
+            sort_extension=normalized_extension,
+            file_type=file_type,
+            separate_choice=mode,
+        )
+    except (MissingTargetDirectoryError, TargetPathNotDirectoryError) as exc:
+        raise typer.BadParameter(str(exc), param_hint="--target-dir") from exc
+    organizer.separate()
+
+
+@app.command()
+def revert(
+    directory: Optional[Path] = typer.Option(
+        None,
+        help="Directory containing history files. Defaults to current directory.",
+    ),
+    history_file: Optional[Path] = typer.Option(
+        None,
+        "--history-file",
+        help="Specific history file path to revert.",
+    ),
+    dry_run: bool = typer.Option(
+        False, help="Preview revert actions without making changes."
+    ),
+    keep_history: bool = typer.Option(
+        False,
+        "--keep-history",
+        help="Do not delete history file after successful revert.",
+    ),
+) -> None:
+    _validate_optional_directory(directory, "--directory")
+
+    reverted = revert_history(
+        history_path=history_file,
+        directory=directory,
+        dry_run=dry_run,
+        delete_after_revert=not keep_history,
+    )
+    print(f"Reverted {reverted} file(s).")
+
+
+@app.command()
+def merge(
+    mode: SeparateChoices = typer.Option(
+        SeparateChoices.EXTENSION,
+        "--mode",
+        help="How to merge files: extension, date, extension_and_date, file.",
+    ),
+    extension: Optional[str] = typer.Option(
+        None,
+        "--extension",
+        help="Extension to filter, e.g. .pdf or pdf.",
+    ),
+    sort_date: Optional[str] = typer.Option(
+        None,
+        "--date",
+        help="Date in YYYY-MM-DD format. Defaults to today when mode uses date.",
+    ),
+    target_dir: Optional[Path] = typer.Option(
+        None, help="Where merged files are moved."
+    ),
+    working_dirs: list[Path] = typer.Option(
+        ..., "--working-dir", help="One or more source directories to merge from."
+    ),
+    dry_run: bool = typer.Option(False, help="Preview actions without making changes."),
+    history: bool = typer.Option(False, "--history", help="Save operation history."),
+) -> None:
+    _validate_required_directories(working_dirs, "--working-dir")
+    _validate_optional_iso_date(sort_date)
+    target_dir = _resolve_target_directory(target_dir, dry_run=dry_run)
+
+    normalized_extension = f".{extension.lstrip('.').lower()}" if extension else None
+
+    try:
+        organizer = FileOrganizer(
+            target_dir=target_dir,
+            working_dirs=working_dirs,
+            dry_run=dry_run,
+            save_history=history,
+            sort_date=sort_date,
+            sort_extension=normalized_extension,
+            separate_choice=mode,
+        )
+    except (MissingTargetDirectoryError, TargetPathNotDirectoryError) as exc:
+        raise typer.BadParameter(str(exc), param_hint="--target-dir") from exc
+    organizer.merge()
+
+
+if __name__ == "__main__":
+    app()