foldrive 0.1.0__py3-none-any.whl

foldrive/__init__.py

@@ -0,0 +1 @@
+__version__="0.1.0"

foldrive/auth.py

@@ -0,0 +1,59 @@
+from google.auth.exceptions import RefreshError
+from google.auth.transport.requests import Request
+from google.oauth2.credentials import Credentials
+from google_auth_oauthlib.flow import InstalledAppFlow
+
+from .paths import APP_DIR, TOKEN_PATH
+
+SCOPES = ["https://www.googleapis.com/auth/drive"]
+CLIENT_SECRET_PATH = APP_DIR / "client_secret.json"
+
+
+def _save(creds):
+    APP_DIR.mkdir(parents=True, exist_ok=True)
+    TOKEN_PATH.write_text(creds.to_json(), encoding="utf-8")
+
+
+
+def get_credentials():
+    if not TOKEN_PATH.exists():
+        return None
+    creds = Credentials.from_authorized_user_file(str(TOKEN_PATH),SCOPES)
+    if creds.valid:
+        return creds
+    if creds.expired and creds.refresh_token:
+        try:
+            creds.refresh(Request())
+        except RefreshError:
+            TOKEN_PATH.unlink()
+            return None
+        _save(creds)
+        return creds
+    return None
+
+def login():
+    creds=get_credentials()
+    if creds:
+        return creds
+    flow = InstalledAppFlow.from_client_secrets_file(str(CLIENT_SECRET_PATH), SCOPES)
+    creds = flow.run_local_server(port=0)
+    _save(creds)
+    return creds
+
+def logout():
+    if TOKEN_PATH.exists():
+        TOKEN_PATH.unlink()
+        return True
+    return False
+
+
+def get_service():
+    """Build a Drive client, or exit with a hint if not logged in."""
+    from googleapiclient.discovery import build
+
+    credentials = get_credentials()
+    if credentials is None:
+        raise SystemExit("Not logged in. Run: foldrive login")
+    return build("drive", "v3", credentials=credentials)
+
+        

foldrive/autostart.py

@@ -0,0 +1,178 @@
+"""Registers `foldrive tick` to run in the background.
+
+Windows uses Task Scheduler; everything else uses cron. The public install/
+uninstall/status functions dispatch on platform, so each backend below can assume
+it is only ever called on its own OS.
+"""
+
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+TASK_NAME = "foldrive-tick"
+INTERVAL_MINUTES = 5
+
+# schtasks' defaults are wrong for a laptop sync tool: it refuses to start on
+# battery and kills a running task the moment you unplug. Those flags can't be set
+# from the schtasks command line, and registering from XML needs elevation, so the
+# task is created the plain way and then patched through the PowerShell API.
+POWER_SETTINGS_SCRIPT = f"""
+$task = Get-ScheduledTask -TaskName '{TASK_NAME}'
+$task.Settings.DisallowStartIfOnBatteries = $false
+$task.Settings.StopIfGoingOnBatteries = $false
+$task.Settings.MultipleInstances = 'IgnoreNew'
+$task.Settings.StartWhenAvailable = $true
+$task | Set-ScheduledTask | Out-Null
+"""
+
+def _foldrive_command():
+    """The command Task Scheduler should run, however foldrive was installed.
+
+    Always an absolute path: the task runs with a different environment and
+    working directory, so a bare `foldrive` may not resolve.
+
+    Prefers pythonw.exe: it belongs to the GUI subsystem, so Windows never
+    allocates a console for it. Running foldrive.exe (a console script) would
+    flash a command prompt on screen at every scheduled tick.
+    """
+    if getattr(sys, "frozen", False):
+        # Standalone foldrive.exe (PyInstaller build; needs --noconsole to be quiet).
+        return f'"{sys.executable}" tick'
+
+    windowless_python = Path(sys.executable).with_name("pythonw.exe")
+    if windowless_python.exists():
+        return f'"{windowless_python}" -m foldrive.cli tick'
+
+    installed_path = shutil.which("foldrive")
+    if installed_path:
+        return f'"{installed_path}" tick'
+
+    # Installed but not on PATH - call this same interpreter's module directly.
+    return f'"{sys.executable}" -m foldrive.cli tick'
+
+
+def _allow_running_on_battery():
+    """Returns True if the power settings were relaxed.
+
+    Best-effort: if it fails, the task still syncs whenever the machine is plugged
+    in, which is worth keeping rather than failing the whole install over.
+    """
+    result = subprocess.run(
+        ["powershell", "-NoProfile", "-NonInteractive", "-Command", POWER_SETTINGS_SCRIPT],
+        capture_output=True,
+        text=True,
+    )
+    return result.returncode == 0
+
+
+def install():
+    if sys.platform == "win32":
+        return _install_windows()
+    return _install_cron()
+
+def uninstall():
+    if sys.platform == "win32":
+        return _uninstall_windows()
+    return _uninstall_cron()
+
+
+def status():
+    if sys.platform == "win32":
+        return _status_windows()
+    return _status_cron()
+
+
+
+def _install_windows():
+    subprocess.run([
+        "schtasks", "/create", "/tn", TASK_NAME,
+        "/tr", _foldrive_command(),
+        "/sc", "minute", "/mo", str(INTERVAL_MINUTES),
+        "/f",
+    ], check=True)
+    return _allow_running_on_battery()
+
+
+def _uninstall_windows():
+    subprocess.run(["schtasks", "/delete", "/tn", TASK_NAME, "/f"], check=True)
+
+
+def _status_windows():
+    result = subprocess.run(
+        ["schtasks", "/query", "/tn", TASK_NAME], capture_output=True, text=True
+    )
+    return result.stdout.strip() if result.returncode == 0 else "not registered"
+
+CRON_MARKER = "# foldrive-tick"
+
+
+def _read_crontab():
+    """Empty string when there is no crontab yet.
+
+    `crontab -l` exits 1 with "no crontab for <user>" in that case - a normal
+    first-run state, not a failure, so this must not use check=True.
+
+    Any OTHER failure must raise rather than return "": the caller rewrites the
+    whole crontab from what this returns, so mistaking an unreadable crontab for
+    an empty one would delete every job the user has.
+    """
+    result = subprocess.run(["crontab", "-l"], capture_output=True, text=True)
+    if result.returncode == 0:
+        return result.stdout
+    if "no crontab" in result.stderr.lower():
+        return ""
+    raise SystemExit(f"Could not read the crontab: {result.stderr.strip()}")
+
+
+def _write_crontab(lines):
+    """cron has no 'append' - the whole crontab is replaced every time. That is
+    exactly why every foldrive line carries CRON_MARKER: so we can strip ours and
+    put everyone else's back untouched."""
+    text = "\n".join(lines).strip() + "\n"
+    result = subprocess.run(["crontab", "-"], input=text, text=True, capture_output=True)
+    if result.returncode != 0:
+        raise SystemExit(f"Could not update crontab: {result.stderr.strip()}")
+
+
+def _without_foldrive_lines(text):
+    return [line for line in text.splitlines() if CRON_MARKER not in line]
+
+
+def _cron_command():
+    """Absolute path: cron runs with a minimal PATH (usually /usr/bin:/bin), so a
+    bare `foldrive` may not resolve even though it works in your shell."""
+    installed_path = shutil.which("foldrive")
+    if installed_path:
+        return f"{installed_path} tick"
+    return f"{sys.executable} -m foldrive.cli tick"
+
+
+def _install_cron():
+    if shutil.which("crontab") is None:
+        raise SystemExit(
+            "No `crontab` command found. Install cron, or run `foldrive sync` manually."
+        )
+    lines = _without_foldrive_lines(_read_crontab())
+    # >/dev/null: cron mails the user any output a job produces, and foldrive
+    # already writes everything worth keeping to its log file.
+    lines.append(
+        f"*/{INTERVAL_MINUTES} * * * * {_cron_command()} >/dev/null 2>&1 {CRON_MARKER}"
+    )
+    _write_crontab(lines)
+    return True          # cron has no battery restriction to relax
+
+
+def _uninstall_cron():
+    existing = _read_crontab()
+    remaining = _without_foldrive_lines(existing)
+    if len(remaining) == len(existing.splitlines()):
+        raise SystemExit("Background sync was not enabled.")
+    _write_crontab(remaining)
+
+
+def _status_cron():
+    for line in _read_crontab().splitlines():
+        if CRON_MARKER in line:
+            return line.strip()
+    return "not registered"

foldrive/cli.py

@@ -0,0 +1,199 @@
+"""foldrive CLI: argument parsing and dispatch. Command logic lives in commands/."""
+
+import argparse
+
+from . import __version__
+from .commands import (
+    autostart, init, log, login, logout, ls, pull, push, restore, setup, status,
+    sync, tick, whoami,
+)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="foldrive",
+        description="Pair a local folder with a Google Drive folder.",
+    )
+
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"foldrive {__version__}",
+    )
+
+    sub = parser.add_subparsers(
+        dest="command",
+        required=True,
+    )
+
+    p = sub.add_parser(
+        "setup",
+        help="One-time Google setup: install your OAuth client file",
+    )
+    p.add_argument(
+        "path",
+        nargs="?",
+        default=None,
+        help="Path to the client JSON downloaded from Google Cloud "
+             "(omit to print the setup steps)",
+    )
+    p.add_argument(
+        "--force",
+        action="store_true",
+        help="Replace an already-installed client file",
+    )
+    p.set_defaults(func=setup.run)
+
+    p = sub.add_parser(
+        "login",
+        help="Sign in with your Google account",
+    )
+    p.set_defaults(func=login.run)
+
+    p = sub.add_parser(
+        "whoami",
+        help="Show the currently signed-in Google account",
+    )
+    p.set_defaults(func=whoami.run)
+
+    p = sub.add_parser(
+        "logout",
+        help="Sign out and forget the saved Google token",
+    )
+    p.set_defaults(func=logout.run)
+
+    p = sub.add_parser(
+        "ls",
+        help="List the contents of a Drive folder by name",
+    )
+    p.add_argument(
+        "name",
+        nargs="?",
+        default=None,
+        help="Drive folder name to look up (you'll be asked if omitted)",
+    )
+    p.set_defaults(func=ls.run)
+
+    p = sub.add_parser(
+        "init",
+        help="Initialize the current folder for foldrive syncing",
+    )
+    p.set_defaults(func=init.run)
+
+    p = sub.add_parser(
+        "status",
+        help="Show local and remote sync status",
+    )
+    p.add_argument(
+        "--all",
+        action="store_true",
+        help="List every pending file instead of the first 40",
+    )
+    p.set_defaults(func=status.run)
+
+    p = sub.add_parser(
+        "push",
+        help="Upload local changes to Google Drive",
+    )
+    p.add_argument(
+        "--yes",
+        action="store_true",
+        help="Skip the first-sync confirmation prompt",
+    )
+    p.add_argument(
+        "--allow-mass-delete",
+        action="store_true",
+        help="Permit a run that would delete most of the folder",
+    )
+    p.set_defaults(func=push.run)
+
+    p = sub.add_parser(
+        "pull",
+        help="Download remote changes from Google Drive",
+    )
+    p.add_argument(
+        "--yes",
+        action="store_true",
+        help="Never prompt; use safe defaults",
+    )
+    p.add_argument(
+        "--allow-mass-delete",
+        action="store_true",
+        help="Permit a run that would delete most of the folder",
+    )
+    p.set_defaults(func=pull.run)
+
+    p = sub.add_parser(
+        "sync",
+        help="Synchronize local and Google Drive changes",
+    )
+    p.add_argument(
+        "--yes",
+        action="store_true",
+        help="Never prompt; use safe defaults",
+    )
+    p.add_argument(
+        "--allow-mass-delete",
+        action="store_true",
+        help="Permit a run that would delete most of the folder",
+    )
+    p.set_defaults(func=sync.run)
+
+    p = sub.add_parser(
+        "log",
+        help="Show what foldrive has done to this folder",
+    )
+    p.add_argument(
+        "-n", "--number",
+        type=int,
+        default=20,
+        help="How many entries to show (default 20)",
+    )
+    p.add_argument(
+        "--all",
+        action="store_true",
+        help="Show the entire history",
+    )
+    p.set_defaults(func=log.run)
+
+    p = sub.add_parser(
+        "restore",
+        help="Bring one file back from Drive",
+    )
+    p.add_argument(
+        "path",
+        help="Path of the file inside this folder, e.g. notes/unit-3.pdf",
+    )
+    p.add_argument(
+        "--force",
+        action="store_true",
+        help="Overwrite the local file if it already exists",
+    )
+    p.set_defaults(func=restore.run)
+
+    p = sub.add_parser(
+        "tick",
+        help="Run any scheduled syncs that are due (used by the background task)",
+    )
+    p.set_defaults(func=tick.run)
+
+    p = sub.add_parser(
+        "autostart",
+        help="Enable foldrive to start automatically when you log in",
+    )
+    p.add_argument("--remove", action="store_true",help="Disable background sync")
+    p.add_argument("--status",action="store_true",help="Show whether it's registered")
+    p.set_defaults(func=autostart.run)
+
+    args = parser.parse_args()
+    try:
+        args.func(args)
+    except KeyboardInterrupt:
+        # Ctrl-C is a normal way to stop a long sync, not a crash. Each command
+        # saves its snapshot in a `finally`, so whatever finished is already
+        # recorded and the next run picks up from there.
+        raise SystemExit("\nInterrupted. Finished files are saved - re-run to continue.")
+
+
+if __name__ == "__main__":
+    main()

foldrive/commands/__init__.py

@@ -0,0 +1 @@
+"""One module per CLI command; each exposes run(args)."""

foldrive/commands/autostart.py

@@ -0,0 +1,16 @@
+from .. import autostart,logs
+
+def run(args):
+    if(args.remove):
+        autostart.uninstall()
+        print("Background Sync Disabled")
+        return
+    if args.status:
+        print(autostart.status())
+        return
+    runs_on_battery = autostart.install()
+    print(f"Background sync enabled - foldrive tick runs every {autostart.INTERVAL_MINUTES} minutes")
+    if not runs_on_battery:
+        print("Note: could not allow syncing on battery power - Windows will only")
+        print("      run the background sync while this machine is plugged in.")
+    print(f"Log: {logs.LOG_PATH}")

foldrive/commands/init.py

@@ -0,0 +1,57 @@
+import copy
+from pathlib import Path
+
+from googleapiclient.errors import HttpError
+
+from .. import auth, config, drive
+
+
+def run(args):
+    folder = Path.cwd()
+
+    if (folder / config.CONFIG_NAME).exists():
+        raise SystemExit("Already initialized. Edit .googledrive.json to change settings.")
+
+    enclosing_root = config.find_config_root(folder.parent)
+    if enclosing_root is not None:
+        raise SystemExit(f"This folder is inside '{enclosing_root}', which is already synced.")
+
+    service = auth.get_service()
+    try:
+        matching_folders = drive.find_folder_by_name(service, folder.name)
+
+        if len(matching_folders) > 1:
+            print(f"Multiple Drive folders are named '{folder.name}':")
+            for folder_match in matching_folders:
+                print(f"  {folder_match['name']}  (id: {folder_match['id']})")
+            raise SystemExit(
+                "foldrive can't tell them apart yet. Rename the extras in Drive, then re-run init."
+            )
+
+        elif len(matching_folders) == 1:
+            drive_folder_id = matching_folders[0]["id"]
+            answer = input(f"Found Drive folder '{folder.name}'. Link this local folder to it? [y/N] ")
+            if answer.strip().lower() != "y":
+                raise SystemExit("Cancelled. Nothing was created or linked.")
+
+        else:
+            answer = input(f"No Drive folder named '{folder.name}' found. Create it in My Drive? [y/N] ")
+            if answer.strip().lower() != "y":
+                raise SystemExit("Cancelled. Nothing was created or linked.")
+            drive_folder_id = drive.create_folder(service, folder.name)
+            print(f"Created Drive folder '{folder.name}'.")
+
+        new_config = copy.deepcopy(config.DEFAULT_CONFIG)
+        new_config["drive_folder_id"] = drive_folder_id
+        new_config["drive_folder_name"] = folder.name
+        config.save_config(folder, new_config)
+        config.register_folder(folder)
+
+        print(f"Linked '{folder}'  <->  Drive folder '{folder.name}'.")
+        print("Settings saved in .googledrive.json — edit schedules/ignores there.")
+        print("Next: run `foldrive status` to see what a first sync would do.")
+
+    except HttpError as api_error:
+        raise SystemExit(f"Google Drive API error: {api_error.reason}")
+    except OSError:
+        raise SystemExit("Network error — are you connected to the internet?")

foldrive/commands/log.py

@@ -0,0 +1,67 @@
+"""Show what foldrive did to this folder, most recent first."""
+
+from datetime import datetime
+from pathlib import Path
+
+from .. import config, history
+
+# Past tense: this is a record of what happened, not a plan.
+KIND_LABELS = {
+    "upload_new": "uploaded",
+    "upload_changed": "updated in Drive",
+    "download_new": "downloaded",
+    "download_changed": "updated locally",
+    "trash_remote": "trashed in Drive",
+    "recycle_local": "moved to Recycle Bin",
+    "link": "linked",
+    "download_new_doc": "downloaded Doc",
+    "download_changed_doc": "downloaded Doc again",
+    "download_changed_doc_keep_local": "downloaded Doc, kept local copy",
+    "upload_changed_doc": "uploaded into Doc",
+    "upload_changed_doc_keep_drive": "uploaded into Doc, kept Drive copy",
+    "restore": "restored from Drive",
+}
+
+# A gap this long means a different run - blank line between runs so the history
+# reads as sessions rather than one undifferentiated stream.
+RUN_GAP_SECONDS = 120
+
+
+def _local_time(iso_text):
+    try:
+        return datetime.fromisoformat(iso_text).astimezone()
+    except (ValueError, TypeError):
+        return None
+
+
+def run(args):
+    folder = config.find_config_root(Path.cwd())
+    if folder is None:
+        raise SystemExit("Not a foldrive folder. Run: foldrive init")
+
+    limit = None if args.all else args.number
+    entries = history.read(folder, limit)
+
+    if not entries:
+        print("No history yet for this folder.")
+        print("It is written as foldrive syncs; run `foldrive sync` first.")
+        return
+
+    print(f"Folder : {folder}")
+    print(f"History: {history.history_path(folder)}\n")
+
+    previous_time = None
+    for entry in entries:
+        moment = _local_time(entry.get("at"))
+        if (previous_time and moment
+                and (previous_time - moment).total_seconds() > RUN_GAP_SECONDS):
+            print()
+        previous_time = moment
+
+        stamp = moment.strftime("%Y-%m-%d %H:%M:%S") if moment else "unknown time"
+        label = KIND_LABELS.get(entry.get("kind"), entry.get("kind", "?"))
+        print(f"  {stamp}  {label:<28} {entry.get('path', '')}")
+
+    if not args.all:
+        print(f"\nShowing the last {len(entries)}. Use --all for everything, "
+              f"-n N for a different count.")

foldrive/commands/login.py

@@ -0,0 +1,10 @@
+from .. import auth
+
+
+def run(args):
+    already = auth.get_credentials() is not None
+    auth.login()
+    if already:
+        print("Already logged in.")
+    else:
+        print(f"Logged in. Token saved to {auth.TOKEN_PATH}")

foldrive/commands/logout.py

@@ -0,0 +1,8 @@
+from .. import auth
+
+
+def run(args):
+    if auth.logout():
+        print("Logged out.")
+    else:
+        print("Not logged in.")

foldrive/commands/ls.py

@@ -0,0 +1,42 @@
+from googleapiclient.errors import HttpError
+
+from .. import auth, drive
+
+
+def run(args):
+    if args.name is None:
+        args.name = input("Enter the Drive folder name: ").strip()
+        if not args.name:
+            raise SystemExit("No folder name given.")
+
+    service = auth.get_service()
+    try:
+        matching_folders = drive.find_folder_by_name(service, args.name)
+        if not matching_folders:
+            print(f"No Drive folder named '{args.name}' found.")
+            return
+        if len(matching_folders) > 1:
+            print(f"Multiple folders named '{args.name}' found.")
+            for folder_match in matching_folders:
+                print(f" {folder_match['name']} (id: {folder_match['id']})")
+            return
+
+        children = drive.list_children(service, matching_folders[0]["id"])
+        if not children:
+            print("(empty folder)")
+            return
+        folders_first_alphabetical = sorted(
+            children,
+            key=lambda child: (child["mimeType"] != drive.FOLDER_MIME_TYPE, child["name"].lower()),
+        )
+        print(f"Found one folder with the name '{args.name}', following are the contents in Google Drive of that folder: ")
+        for child in folders_first_alphabetical:
+            if child["mimeType"] == drive.FOLDER_MIME_TYPE:
+                print(f"  {child['name']}/")
+            else:
+                size_kb = int(child.get("size", 0)) // 1024
+                print(f"  {child['name']}  ({size_kb} KB)")
+    except HttpError as api_error:
+        raise SystemExit(f"Google Drive API error: {api_error.reason}")
+    except OSError:
+        raise SystemExit("Network error — are you connected to the internet?")