pythinker-code 2.0.0__py3-none-any.whl

pythinker_code/utils/clipboard.py

@@ -0,0 +1,246 @@
+from __future__ import annotations
+
+import importlib
+import io
+import os
+import shutil
+import subprocess
+import sys
+from collections.abc import Iterable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, cast
+
+import pyperclip
+from PIL import Image, ImageGrab
+
+# Video file extensions recognized for clipboard paste.
+_VIDEO_SUFFIXES: frozenset[str] = frozenset(
+    {".mp4", ".mkv", ".avi", ".mov", ".wmv", ".webm", ".m4v", ".flv", ".3gp", ".3g2"}
+)
+
+
+@dataclass(frozen=True, slots=True)
+class ClipboardResult:
+    """Result of reading media from the clipboard.
+
+    Both fields may be non-empty when the clipboard contains a mix of
+    image files and non-image files (videos, PDFs, etc.).
+    """
+
+    images: tuple[Image.Image, ...]
+    file_paths: tuple[Path, ...]
+
+
+def is_clipboard_available() -> bool:
+    """Check if the Pyperclip text clipboard is available."""
+    try:
+        pyperclip.paste()
+        return True
+    except Exception:
+        return False
+
+
+def is_media_clipboard_available() -> bool:
+    """Check if the media clipboard (xclip/wl-paste) is available.
+
+    On headless Linux (e.g. SSH remote), pyperclip may fail because
+    DISPLAY is not set, but images can still be read through xclip or
+    wl-paste (e.g. via clipboard bridging tools like cc-clip that shim
+    xclip over an SSH tunnel).
+    """
+    if sys.platform == "linux":
+        return shutil.which("xclip") is not None or shutil.which("wl-paste") is not None
+    # macOS and Windows use native APIs that do not require external tools.
+    return True
+
+
+def grab_media_from_clipboard() -> ClipboardResult | None:
+    """Read media from the clipboard.
+
+    Inspects the clipboard once and returns all detected media.
+    Image files are returned as loaded PIL images; non-image files
+    (videos, PDFs, etc.) are returned as file paths.
+
+    On macOS the native pasteboard API is tried first to avoid
+    misidentifying a file's thumbnail as clipboard image data.
+    """
+    # 1. Try macOS native API for file paths (most reliable for Finder copies).
+    if sys.platform == "darwin":
+        file_paths = _read_clipboard_file_paths_macos_native()
+        images, non_image_paths = _classify_file_paths(file_paths)
+        if images or non_image_paths:
+            return ClipboardResult(
+                images=tuple(images),
+                file_paths=tuple(non_image_paths),
+            )
+
+    # 2. On Linux, use explicit xclip/wl-paste fallback instead of Pillow's
+    #    opaque internal selection, which may pick a broken tool first.
+    if sys.platform == "linux":
+        image = _grab_image_linux()
+        if image is not None:
+            return ClipboardResult(images=(image,), file_paths=())
+        return None
+
+    # 3. On Windows and other platforms, use Pillow's default implementation.
+    payload = ImageGrab.grabclipboard()
+    if payload is None:
+        return None
+    if isinstance(payload, Image.Image):
+        # Raw image data (screenshot or thumbnail).
+        # If we reach here, the macOS native path lookup did not find any
+        # file paths, so this is safe to treat as a real image.
+        return ClipboardResult(images=(payload,), file_paths=())
+    # payload is a list of file path strings.
+    images, non_image_paths = _classify_file_paths(payload)
+    if images or non_image_paths:
+        return ClipboardResult(
+            images=tuple(images),
+            file_paths=tuple(non_image_paths),
+        )
+    return None
+
+
+def _grab_image_linux() -> Image.Image | None:
+    """Read image from Linux clipboard with session-aware tool fallback.
+
+    Tries the backend matching the current session type first to avoid
+    reading stale data from the wrong clipboard (e.g. XWayland vs
+    Wayland). On headless systems with no session type, xclip is tried
+    first since clipboard bridges (e.g. cc-clip) typically shim xclip.
+    """
+    xclip_args = ["xclip", "-selection", "clipboard", "-t", "image/png", "-o"]
+    wlpaste_args = ["wl-paste", "-t", "image"]
+
+    if os.getenv("WAYLAND_DISPLAY"):
+        candidates = (wlpaste_args, xclip_args)
+    elif os.getenv("DISPLAY"):
+        candidates = (xclip_args, wlpaste_args)
+    else:  # headless — xclip first for common clipboard bridges
+        candidates = (xclip_args, wlpaste_args)
+
+    for idx, args in enumerate(candidates):
+        if shutil.which(args[0]) is None:
+            continue
+        try:
+            p = subprocess.run(args, capture_output=True, timeout=3)
+        except subprocess.TimeoutExpired:
+            continue
+        if p.returncode == 0 and p.stdout:
+            data = io.BytesIO(p.stdout)
+            try:
+                im = Image.open(data)
+                im.load()
+                return im
+            except Exception:
+                continue
+        # Silent errors mean clipboard is empty or has no image.
+        err = p.stderr
+        silent_errors = [
+            b"Nothing is copied",
+            b"No selection",
+            b"No suitable type of content copied",
+            b" not available",
+            b"cannot convert ",
+            b"no owner for the ",
+        ]
+        if any(se in err for se in silent_errors):
+            # Trust the session-native tool: if it says "no image", don't
+            # fall back to a different clipboard namespace (e.g. XWayland
+            # vs Wayland) which may contain stale unrelated data.
+            if idx == 0:
+                return None
+            continue
+        # Otherwise, a real error (e.g. tool broken) — try next candidate.
+
+    return None
+
+
+def _classify_file_paths(
+    paths: Iterable[os.PathLike[str] | str],
+) -> tuple[list[Image.Image], list[Path]]:
+    """Classify clipboard file paths into images and non-image files.
+
+    Returns ``(images, non_image_paths)`` where *images* contains loaded
+    PIL images and *non_image_paths* contains paths to videos, documents,
+    and other non-image files.
+    """
+    resolved: list[Path] = []
+    for item in paths:
+        try:
+            path = Path(item)
+        except (TypeError, ValueError):
+            continue
+        if not path.is_file():
+            continue
+        resolved.append(path)
+
+    images: list[Image.Image] = []
+    non_image_paths: list[Path] = []
+
+    for path in resolved:
+        # Video files are never opened as images.
+        if path.suffix.lower() in _VIDEO_SUFFIXES:
+            non_image_paths.append(path)
+            continue
+        try:
+            with Image.open(path) as img:
+                img.load()
+                images.append(img.copy())
+        except Exception:
+            non_image_paths.append(path)
+
+    return images, non_image_paths
+
+
+def _read_clipboard_file_paths_macos_native() -> list[Path]:
+    try:
+        appkit = cast(Any, importlib.import_module("AppKit"))
+        foundation = cast(Any, importlib.import_module("Foundation"))
+    except Exception:
+        return []
+
+    NSPasteboard = appkit.NSPasteboard
+    NSURL = foundation.NSURL
+    options_key = getattr(
+        appkit,
+        "NSPasteboardURLReadingFileURLsOnlyKey",
+        "NSPasteboardURLReadingFileURLsOnlyKey",
+    )
+
+    pb = NSPasteboard.generalPasteboard()
+    options = {options_key: True}
+    try:
+        urls: list[Any] | None = pb.readObjectsForClasses_options_([NSURL], options)
+    except Exception:
+        urls = None
+
+    paths: list[Path] = []
+    if urls:
+        for url in urls:
+            try:
+                path = url.path()
+            except Exception:
+                continue
+            if path:
+                paths.append(Path(str(path)))
+
+    if paths:
+        return paths
+
+    try:
+        file_list = cast(list[str] | str | None, pb.propertyListForType_("NSFilenamesPboardType"))
+    except Exception:
+        return []
+
+    if not file_list:
+        return []
+
+    file_items: list[str] = []
+    if isinstance(file_list, list):
+        file_items.extend(item for item in file_list if item)
+    else:
+        file_items.append(file_list)
+
+    return [Path(item) for item in file_items]

pythinker_code/utils/datetime.py

@@ -0,0 +1,64 @@
+from datetime import datetime, timedelta
+
+
+def format_relative_time(timestamp: float) -> str:
+    """Format a timestamp as a relative time string."""
+    now = datetime.now()
+    dt = datetime.fromtimestamp(timestamp)
+    diff = now - dt
+    if diff < timedelta(minutes=5):
+        return "just now"
+    if diff < timedelta(hours=1):
+        minutes = int(diff.total_seconds() / 60)
+        return f"{minutes}m ago"
+    if diff < timedelta(days=1):
+        hours = int(diff.total_seconds() / 3600)
+        return f"{hours}h ago"
+    if diff < timedelta(days=7):
+        return f"{diff.days}d ago"
+    return dt.strftime("%m-%d")
+
+
+def format_duration(seconds: int) -> str:
+    """Format a duration in seconds using short units."""
+    delta = timedelta(seconds=seconds)
+    parts: list[str] = []
+    days = delta.days
+    if days:
+        parts.append(f"{days}d")
+    hours, remainder = divmod(delta.seconds, 3600)
+    minutes, secs = divmod(remainder, 60)
+    if hours:
+        parts.append(f"{hours}h")
+    if minutes:
+        parts.append(f"{minutes}m")
+    if secs and not parts:
+        parts.append(f"{secs}s")
+    return " ".join(parts) or "0s"
+
+
+def format_elapsed(seconds: float) -> str:
+    """Format elapsed seconds for spinner display.
+
+    Unlike :func:`format_duration` (which omits seconds when minutes are
+    present), this always includes seconds for sub-hour durations so that
+    spinner text stays precise::
+
+        0.5  -> "<1s"
+        5    -> "5s"
+        90   -> "1m 30s"
+        3661 -> "1h 1m 1s"
+    """
+    if seconds < 1:
+        return "<1s"
+    total = int(seconds)
+    if total < 60:
+        return f"{total}s"
+    hours, remainder = divmod(total, 3600)
+    minutes, secs = divmod(remainder, 60)
+    parts: list[str] = []
+    if hours:
+        parts.append(f"{hours}h")
+    parts.append(f"{minutes}m")
+    parts.append(f"{secs}s")
+    return " ".join(parts)

pythinker_code/utils/diff.py

@@ -0,0 +1,135 @@
+from __future__ import annotations
+
+import asyncio
+import difflib
+from difflib import SequenceMatcher
+
+from pythinker_core.tooling import DisplayBlock
+
+from pythinker_code.tools.display import DiffDisplayBlock
+
+N_CONTEXT_LINES = 3
+
+_HUGE_FILE_THRESHOLD = 10000
+"""Line count above which diff computation is skipped entirely."""
+
+
+def format_unified_diff(
+    old_text: str,
+    new_text: str,
+    path: str = "",
+    *,
+    include_file_header: bool = True,
+) -> str:
+    """
+    Format a unified diff between old_text and new_text.
+
+    Args:
+        old_text: The original text.
+        new_text: The new text.
+        path: Optional file path for the diff header.
+        include_file_header: Whether to include the ---/+++ file header lines.
+
+    Returns:
+        A unified diff string.
+    """
+    old_lines = old_text.splitlines(keepends=True)
+    new_lines = new_text.splitlines(keepends=True)
+
+    # Ensure lines end with newline for proper diff formatting
+    if old_lines and not old_lines[-1].endswith("\n"):
+        old_lines[-1] += "\n"
+    if new_lines and not new_lines[-1].endswith("\n"):
+        new_lines[-1] += "\n"
+
+    fromfile = f"a/{path}" if path else "a/file"
+    tofile = f"b/{path}" if path else "b/file"
+
+    diff = list(
+        difflib.unified_diff(
+            old_lines,
+            new_lines,
+            fromfile=fromfile,
+            tofile=tofile,
+            lineterm="\n",
+        )
+    )
+
+    if (
+        not include_file_header
+        and len(diff) >= 2
+        and diff[0].startswith("--- ")
+        and diff[1].startswith("+++ ")
+    ):
+        diff = diff[2:]
+
+    return "".join(diff)
+
+
+def _build_diff_blocks_sync(
+    path: str,
+    old_text: str,
+    new_text: str,
+) -> list[DisplayBlock]:
+    """Synchronous diff block builder — CPU-bound, meant to run in a thread."""
+    if old_text == new_text:
+        return []
+
+    old_lines = old_text.splitlines()
+    new_lines = new_text.splitlines()
+
+    max_lines = max(len(old_lines), len(new_lines))
+
+    # Huge files: skip diff entirely, return a summary block
+    if max_lines > _HUGE_FILE_THRESHOLD:
+        old_desc = f"({len(old_lines)} lines)"
+        if len(old_lines) == len(new_lines):
+            new_desc = f"({len(new_lines)} lines, modified)"
+        else:
+            new_desc = f"({len(new_lines)} lines)"
+        return [
+            DiffDisplayBlock(
+                path=path,
+                old_text=old_desc,
+                new_text=new_desc,
+                old_start=1,
+                new_start=1,
+                is_summary=True,
+            )
+        ]
+
+    matcher = SequenceMatcher(None, old_lines, new_lines, autojunk=False)
+
+    blocks: list[DisplayBlock] = []
+    for group in matcher.get_grouped_opcodes(n=N_CONTEXT_LINES):
+        if not group:
+            continue
+        i1 = group[0][1]
+        i2 = group[-1][2]
+        j1 = group[0][3]
+        j2 = group[-1][4]
+        blocks.append(
+            DiffDisplayBlock(
+                path=path,
+                old_text="\n".join(old_lines[i1:i2]),
+                new_text="\n".join(new_lines[j1:j2]),
+                old_start=i1 + 1,
+                new_start=j1 + 1,
+            )
+        )
+    return blocks
+
+
+async def build_diff_blocks(
+    path: str,
+    old_text: str,
+    new_text: str,
+) -> list[DisplayBlock]:
+    """Build diff display blocks grouped with small context windows.
+
+    Runs the CPU-bound diff computation in a thread to avoid blocking
+    the event loop.
+    """
+    if old_text == new_text:
+        return []
+    return await asyncio.to_thread(_build_diff_blocks_sync, path, old_text, new_text)

pythinker_code/utils/editor.py

@@ -0,0 +1,91 @@
+"""External editor utilities for editing text in $VISUAL/$EDITOR."""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import shlex
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+
+from pythinker_code.utils.logging import logger
+from pythinker_code.utils.subprocess_env import get_clean_env
+
+# VSCode needs --wait to block until the file is closed.
+_EDITOR_CANDIDATES = [
+    (["code", "--wait"], "code"),
+    (["vim"], "vim"),
+    (["vi"], "vi"),
+    (["nano"], "nano"),
+]
+
+
+def get_editor_command(configured: str = "") -> list[str] | None:
+    """Determine the editor command to use.
+
+    Priority: *configured* (from config) -> $VISUAL -> $EDITOR -> auto-detect.
+    Auto-detect order: code --wait -> vim -> vi -> nano.
+    """
+    if configured:
+        try:
+            return shlex.split(configured)
+        except ValueError:
+            logger.warning("Invalid configured editor value: {}", configured)
+
+    for var in ("VISUAL", "EDITOR"):
+        value = os.environ.get(var)
+        if value:
+            try:
+                return shlex.split(value)
+            except ValueError:
+                logger.warning("Invalid {} value: {}", var, value)
+                continue
+
+    for cmd, binary in _EDITOR_CANDIDATES:
+        if shutil.which(binary):
+            return cmd
+
+    return None
+
+
+def edit_text_in_editor(text: str, configured: str = "") -> str | None:
+    """Open *text* in an external editor and return the edited result.
+
+    Returns ``None`` if the editor failed or the user quit without saving.
+    """
+    editor_cmd = get_editor_command(configured)
+    if editor_cmd is None:
+        logger.warning("No editor found. Set $VISUAL or $EDITOR.")
+        return None
+
+    fd, tmpfile = tempfile.mkstemp(suffix=".md", prefix="pythinker-edit-")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            f.write(text)
+
+        mtime_before = os.path.getmtime(tmpfile)
+
+        try:
+            returncode = subprocess.call(editor_cmd + [tmpfile], env=get_clean_env())
+        except OSError as exc:
+            logger.warning("Failed to launch editor {}: {}", editor_cmd, exc)
+            return None
+
+        if returncode != 0:
+            logger.warning("Editor exited with non-zero return code: {}", returncode)
+            return None
+
+        mtime_after = os.path.getmtime(tmpfile)
+        if mtime_after == mtime_before:
+            return None
+
+        edited = Path(tmpfile).read_text(encoding="utf-8")
+        if edited.endswith("\n"):
+            edited = edited[:-1]
+
+        return edited
+    finally:
+        with contextlib.suppress(OSError):
+            os.unlink(tmpfile)

pythinker_code/utils/environment.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+import os
+import platform
+from dataclasses import dataclass
+from typing import Literal
+
+from pythinker_host.path import HostPath
+
+
+@dataclass(slots=True, frozen=True, kw_only=True)
+class Environment:
+    os_kind: Literal["Windows", "Linux", "macOS"] | str
+    os_arch: str
+    os_version: str
+    shell_name: Literal["bash", "sh", "Windows PowerShell"]
+    shell_path: HostPath
+
+    @staticmethod
+    async def detect() -> Environment:
+        match platform.system():
+            case "Darwin":
+                os_kind = "macOS"
+            case "Windows":
+                os_kind = "Windows"
+            case "Linux":
+                os_kind = "Linux"
+            case system:
+                os_kind = system
+
+        os_arch = platform.machine()
+        os_version = platform.version()
+
+        if os_kind == "Windows":
+            shell_name = "Windows PowerShell"
+            system_root = os.environ.get("SYSTEMROOT", r"C:\Windows")
+            possible_paths = [
+                HostPath(
+                    os.path.join(
+                        system_root, "System32", "WindowsPowerShell", "v1.0", "powershell.exe"
+                    )
+                ),
+            ]
+            fallback_path = HostPath("powershell.exe")
+            for path in possible_paths:
+                if await path.is_file():
+                    shell_path = path
+                    break
+            else:
+                shell_path = fallback_path
+        else:
+            possible_paths = [
+                HostPath("/bin/bash"),
+                HostPath("/usr/bin/bash"),
+                HostPath("/usr/local/bin/bash"),
+            ]
+            fallback_path = HostPath("/bin/sh")
+            for path in possible_paths:
+                if await path.is_file():
+                    shell_name = "bash"
+                    shell_path = path
+                    break
+            else:
+                shell_name = "sh"
+                shell_path = fallback_path
+
+        return Environment(
+            os_kind=os_kind,
+            os_arch=os_arch,
+            os_version=os_version,
+            shell_name=shell_name,
+            shell_path=shell_path,
+        )

pythinker_code/utils/envvar.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+import os
+
+_TRUE_VALUES = {"1", "true", "t", "yes", "y"}
+
+
+def get_env_bool(name: str, default: bool = False) -> bool:
+    value = os.getenv(name)
+    if value is None:
+        return default
+    return value.strip().lower() in _TRUE_VALUES
+
+
+def get_env_int(name: str, default: int) -> int:
+    value = os.getenv(name)
+    if value is None:
+        return default
+    try:
+        return int(value)
+    except ValueError:
+        return default