treeing 1.0.1__py3-none-any.whl

treeing/gui/dnd.py

@@ -0,0 +1,124 @@
+"""
+treeing/gui/dnd.py
+
+Defines the Windows file drag-and-drop binding.
+Currently effective on Windows only; on other platforms bind_file_drop is a no-op.
+"""
+
+import sys
+
+
+def bind_file_drop(widget, callback) -> None:
+    """
+    Bind a file drop event to a Tk widget.
+
+    On drop, calls callback(path: str, extra_files: int). No-op on non-Windows
+    platforms.
+    """
+    if not sys.platform.startswith('win'):
+        return
+    try:
+        _bind_windows_file_drop(widget, callback)
+    except (OSError, AttributeError, ValueError):
+        pass
+
+
+def _bind_windows_file_drop(widget, callback) -> None:
+    """
+    Implement file drop on Windows by subclassing the window procedure.
+
+    Uses the WM_DROPFILES message and the DragQueryFileW API.
+    """
+    import ctypes
+    from ctypes import wintypes
+
+    WM_DROPFILES = 0x0233
+    GWL_WNDPROC = -4
+
+    widget.update_idletasks()
+    hwnd = widget.winfo_id()
+
+    shell32 = ctypes.windll.shell32
+    user32 = ctypes.windll.user32
+
+    WNDPROC = ctypes.WINFUNCTYPE(
+        wintypes.LRESULT,
+        wintypes.HWND,
+        wintypes.UINT,
+        wintypes.WPARAM,
+        wintypes.LPARAM,
+    )
+
+    if hasattr(user32, 'GetWindowLongPtrW'):
+        get_wndproc = user32.GetWindowLongPtrW
+        set_wndproc = user32.SetWindowLongPtrW
+    else:
+        get_wndproc = user32.GetWindowLongW
+        set_wndproc = user32.SetWindowLongW
+
+    old_wndproc = get_wndproc(hwnd, GWL_WNDPROC)
+
+    def py_drop_handler(hwnd, msg, wparam, lparam):
+        """Handle WM_DROPFILES: extract the dropped file paths and callback with the first one."""
+        if msg == WM_DROPFILES:
+            count = shell32.DragQueryFileW(wparam, 0xFFFFFFFF, None, 0)
+            paths: list[str] = []
+            for i in range(count):
+                buf = ctypes.create_unicode_buffer(260)
+                needed = shell32.DragQueryFileW(wparam, i, buf, len(buf))
+                if needed >= len(buf) - 1:
+                    buf = ctypes.create_unicode_buffer(needed + 1)
+                    shell32.DragQueryFileW(wparam, i, buf, len(buf))
+                paths.append(buf.value)
+            shell32.DragFinish(wparam)
+            if paths:
+                callback(paths[0], max(0, len(paths) - 1))
+            return 0
+        return user32.CallWindowProcW(old_wndproc, hwnd, msg, wparam, lparam)
+
+    new_wndproc = WNDPROC(py_drop_handler)
+    set_wndproc(hwnd, GWL_WNDPROC, new_wndproc)
+    shell32.DragAcceptFiles(hwnd, True)
+
+    widget._treeing_drop_old_wndproc = old_wndproc
+    widget._treeing_drop_wndproc = new_wndproc
+    widget._treeing_drop_hwnd = hwnd
+    widget._treeing_drop_user32 = user32
+    widget._treeing_drop_shell32 = shell32
+    widget._treeing_drop_gwl = GWL_WNDPROC
+
+    def _on_destroy(event) -> None:
+        """On window destruction, restore the original WNDPROC and revoke drag-drop to avoid dangling callbacks."""
+        w = event.widget
+        drop_hwnd = getattr(w, '_treeing_drop_hwnd', None)
+        if drop_hwnd is None:
+            return
+        try:
+            drop_user32 = w._treeing_drop_user32
+            drop_shell32 = w._treeing_drop_shell32
+            if hasattr(drop_user32, 'SetWindowLongPtrW'):
+                set_proc = drop_user32.SetWindowLongPtrW
+                get_proc = drop_user32.GetWindowLongPtrW
+            else:
+                set_proc = drop_user32.SetWindowLongW
+                get_proc = drop_user32.GetWindowLongW
+            current = get_proc(drop_hwnd, w._treeing_drop_gwl)
+            if current == w._treeing_drop_wndproc:
+                set_proc(drop_hwnd, w._treeing_drop_gwl, w._treeing_drop_old_wndproc)
+            drop_shell32.DragAcceptFiles(drop_hwnd, False)
+        except (OSError, AttributeError, ValueError):
+            pass
+        for attr in (
+            '_treeing_drop_old_wndproc',
+            '_treeing_drop_wndproc',
+            '_treeing_drop_hwnd',
+            '_treeing_drop_user32',
+            '_treeing_drop_shell32',
+            '_treeing_drop_gwl',
+        ):
+            try:
+                delattr(w, attr)
+            except AttributeError:
+                pass
+
+    widget.bind('<Destroy>', _on_destroy, add='+')

treeing/gui/icon.py

@@ -0,0 +1,69 @@
+"""
+treeing/gui/icon.py
+
+Defines the window-icon logic.
+Supports Windows (.ico), macOS (.icns) and a PNG fallback.
+"""
+
+import sys
+import tkinter as tk
+
+from ..config import _resource_dir
+
+
+def set_window_icon(root: tk.Misc) -> None:
+    """
+    Set the window and (macOS) Dock icon.
+
+    Tk cannot use an emoji string directly; a resource file must be loaded.
+    """
+    assets = _resource_dir() / "assets"
+
+    if sys.platform == "darwin":
+        icns = assets / "icon.icns"
+        if icns.is_file():
+            try:
+                root.iconbitmap(str(icns))
+                return
+            except tk.TclError:
+                pass
+
+    if sys.platform.startswith("win"):
+        ico = assets / "icon.ico"
+        if ico.is_file():
+            try:
+                root.iconbitmap(str(ico))
+                return
+            except tk.TclError:
+                pass
+
+    png = assets / "icon.png"
+    if not png.is_file():
+        return
+    try:
+        img = tk.PhotoImage(master=root, file=str(png))
+    except (tk.TclError, RuntimeError):
+        return
+    root.iconphoto(True, img)
+    root._treeing_icon = img  # keep a reference so it is not garbage-collected
+
+
+def apply_window_icon(widget: tk.Misc, *, icon_source: tk.Misc | None = None) -> None:
+    """
+    Give a Toplevel sub-window a title-bar icon matching the main window.
+
+    Reuses the PhotoImage already loaded on icon_source or a parent window to
+    avoid reloading; falls back to loading from the resource directory.
+    """
+    if icon_source is not None and getattr(icon_source, '_treeing_icon', None) is not None:
+        widget.iconphoto(True, icon_source._treeing_icon)
+        return
+
+    candidate = icon_source or widget
+    while candidate is not None:
+        if getattr(candidate, '_treeing_icon', None) is not None:
+            widget.iconphoto(True, candidate._treeing_icon)
+            return
+        candidate = getattr(candidate, 'master', None)
+
+    set_window_icon(widget)

treeing/gui/preview.py

@@ -0,0 +1,9 @@
+"""treeing/gui/preview.py
+
+Re-exports the node display-name formatter used by the GUI preview pane.
+Directly reuses core.preview.format_preview_label.
+"""
+
+from ..core.preview import format_preview_label
+
+__all__ = ['format_preview_label']

treeing/gui/settings.py

@@ -0,0 +1,80 @@
+"""
+treeing/gui/settings.py
+
+Defines GUI user-preference persistence.
+Saves/loads the last generate directory, font size, import encoding and other
+settings to ~/.treeing/settings.json.
+"""
+
+import json
+from pathlib import Path
+
+_SETTINGS_PATH = Path.home() / '.treeing' / 'settings.json'
+_DEFAULT_FONT_SIZE = 10
+_DEFAULT_IMPORT_ENCODING = 'utf-8'
+_DEFAULT_IMPORT_ENCODINGS = (
+    'utf-8', 'utf-16', 'cp1252', 'iso-8859-1', 'mac-roman',
+)
+
+
+def load_settings() -> dict:
+    """Load user settings; return an empty dict on failure."""
+    try:
+        if _SETTINGS_PATH.is_file():
+            return json.loads(_SETTINGS_PATH.read_text(encoding='utf-8'))
+    except (OSError, json.JSONDecodeError, TypeError):
+        pass
+    return {}
+
+
+def save_settings(data: dict) -> None:
+    """Save user settings, creating the parent directory as needed."""
+    try:
+        _SETTINGS_PATH.parent.mkdir(parents=True, exist_ok=True)
+        _SETTINGS_PATH.write_text(
+            json.dumps(data, ensure_ascii=False, indent=2),
+            encoding='utf-8',
+        )
+    except OSError:
+        pass
+
+
+def get_font_size(settings: dict | None = None) -> int:
+    """Return a valid font size in the range 8-24; fall back to the default for invalid values."""
+    raw = (settings or load_settings()).get('font_size', _DEFAULT_FONT_SIZE)
+    try:
+        size = int(raw)
+    except (TypeError, ValueError):
+        return _DEFAULT_FONT_SIZE
+    return max(8, min(size, 24))
+
+
+def get_last_generate_dir(settings: dict | None = None) -> str | None:
+    """Return the directory used for the last generation, or None when it no longer exists."""
+    path = (settings or load_settings()).get('last_generate_dir')
+    if path and Path(path).is_dir():
+        return path
+    return None
+
+
+def get_import_encodings(settings: dict | None = None) -> list[str]:
+    """Dropdown preset list; settings.json's import_encodings may add or remove entries; empty falls back to the built-in default."""
+    raw = (settings or load_settings()).get('import_encodings')
+    if isinstance(raw, list) and raw:
+        seen: list[str] = []
+        for item in raw:
+            if isinstance(item, str):
+                enc = item.strip()
+                if enc and enc not in seen:
+                    seen.append(enc)
+        if seen:
+            return seen
+    return list(_DEFAULT_IMPORT_ENCODINGS)
+
+
+def get_import_encoding(settings: dict | None = None) -> str:
+    """Return the last chosen import encoding; default utf-8."""
+    raw = (settings or load_settings()).get('import_encoding', _DEFAULT_IMPORT_ENCODING)
+    if isinstance(raw, str) and raw.strip():
+        return raw.strip()
+    return _DEFAULT_IMPORT_ENCODING

treeing/gui/tooltip.py

@@ -0,0 +1,234 @@
+"""
+treeing/gui/tooltip.py
+
+Defines the hover-tooltip component.
+Supports showing explanatory text on Labels, buttons and grouped checkboxes.
+"""
+
+import tkinter as tk
+from typing import Literal
+
+from ..config import get_string
+
+_DEFAULT_WRAP = 420
+_WINDOW_MARGIN = 8
+_DEFAULT_H_OFFSET = 16
+_RIGHT_HALF_INSET = 8
+_TOOLTIP_OFFSET = 4
+_TooltipPosition = Literal['below', 'above']
+
+
+class ToolTip:
+    """
+    A tooltip component that shows explanatory text on hover.
+    Supports custom position (below/above), wrap width and a root window.
+
+    MING changed the Toplevel to "lazy-create + reuse": each ToolTip instance
+    holds at most one Toplevel, deiconified on hover and withdrawn on leave,
+    instead of creating and destroying one each time. This works around
+    macOS-arm, where repeatedly creating/destroying override-redirect windows
+    leaves white rectangles (ghost frames) because WindowServer cannot clear
+    them in time.
+    """
+
+    def __init__(
+        self,
+        widget,
+        text: str,
+        *,
+        root: tk.Misc | None = None,
+        wraplength: int = _DEFAULT_WRAP,
+        position: _TooltipPosition = 'below',
+    ) -> None:
+        """
+        Initialise the tooltip and bind the widget's Enter/Leave events.
+
+        `root` is used to compute the tooltip position; when omitted, the
+        top-level window holding the widget is used. No window is created
+        here; the real creation happens on first _show.
+        """
+        self.widget = widget
+        self.text = text
+        self.root = root
+        self.wraplength = wraplength
+        self.position = position
+        self.tip_window: tk.Toplevel | None = None
+        self._label: tk.Label | None = None
+        widget.bind('<Enter>', self._show, add='+')
+        widget.bind('<Leave>', self._hide, add='+')
+
+    def _ensure_window(self, root: tk.Misc) -> tk.Toplevel:
+        """
+        Lazily create and reuse a single Toplevel window.
+
+        On first call, creates the Toplevel, sets it topmost, and packs a
+        Label inside; later calls return the existing window. The window
+        persists; _hide only withdraws it (no destroy), avoiding the ghost
+        frames caused by repeated create/destroy on macOS-arm.
+        """
+        if self.tip_window is not None:
+            return self.tip_window
+
+        tw = tk.Toplevel(root)
+        tw.withdraw()
+        tw.wm_overrideredirect(True)
+        # Topmost keeps the tooltip above the main window; some platforms /
+        # window managers do not support this attribute, so failures are
+        # silently ignored and do not affect display.
+        try:
+            tw.wm_attributes('-topmost', True)
+        except tk.TclError:
+            pass
+        self._label = tk.Label(
+            tw,
+            text=self.text,
+            justify=tk.LEFT,
+            background='#ffffe0',
+            relief=tk.SOLID,
+            borderwidth=1,
+            padx=8,
+            pady=6,
+            wraplength=self.wraplength,
+        )
+        self._label.pack()
+        self.tip_window = tw
+        return tw
+
+    def _place_tooltip(self, root: tk.Misc, tw: tk.Toplevel) -> None:
+        """
+        Compute the tooltip's screen coordinates and move the window.
+
+        Horizontal: if the widget is to the right of the centre line, right-align
+        with a left inset; otherwise left-align; then clamp within the root
+        window's left/right edges.
+        Vertical: above or below per `position`; if the target side does not fit
+        (above the top or below the bottom of the screen), flip to the other
+        side so the tooltip never leaves the visible area.
+
+        Height prefers winfo_reqheight because, while the window is withdrawn,
+        winfo_height may return 1 on macOS-arm Tk (not actually mapped), which
+        would make an "above" tooltip stick to the widget top and overflow
+        downward over the button.
+        """
+        root.update_idletasks()
+        tw.update_idletasks()
+
+        root_x = root.winfo_rootx()
+        root_w = root.winfo_width()
+        root_right = root_x + root_w
+
+        wx = self.widget.winfo_rootx()
+        wy = self.widget.winfo_rooty()
+        ww = max(self.widget.winfo_width(), 1)
+        wh = max(self.widget.winfo_height(), 1)
+
+        tip_w = max(_to_int(tw.winfo_reqwidth(), 0), _to_int(tw.winfo_width(), 0), 1)
+        tip_h = max(_to_int(tw.winfo_reqheight(), 0), _to_int(tw.winfo_height(), 0), 1)
+
+        window_cx = root_x + root_w // 2
+        widget_cx = wx + ww // 2
+
+        if widget_cx >= window_cx:
+            x = wx + ww - tip_w - _RIGHT_HALF_INSET
+        else:
+            x = wx + _DEFAULT_H_OFFSET
+
+        x = max(root_x + _WINDOW_MARGIN, min(x, root_right - tip_w - _WINDOW_MARGIN))
+
+        y_above = wy - tip_h - _TOOLTIP_OFFSET
+        y_below = wy + wh + _TOOLTIP_OFFSET
+
+        if self.position == 'above':
+            y = y_above
+            if y < _WINDOW_MARGIN:
+                y = y_below
+        else:
+            y = y_below
+            screen_h = _safe_screen_height(root)
+            if screen_h and y + tip_h > screen_h - _WINDOW_MARGIN:
+                y = y_above
+
+        tw.wm_geometry(f'+{x}+{y}')
+
+    def _show(self, _event=None) -> None:
+        """
+        Show the tooltip when the mouse enters the widget.
+
+        Reuses the existing window; refreshes the Label if the text changed
+        (may happen when one instance is bound to multiple widgets). Positions
+        before deiconify, so it does not appear at the default position and
+        then jump (which causes flicker / ghost frames).
+        """
+        if not self.text:
+            return
+        root = self.root or self.widget.winfo_toplevel()
+        tw = self._ensure_window(root)
+        if self._label is not None:
+            self._label.configure(text=self.text)
+        self._place_tooltip(root, tw)
+        try:
+            tw.deiconify()
+        except tk.TclError:
+            # Silently skip this show when the parent window has been destroyed.
+            self.tip_window = None
+            self._label = None
+
+    def _hide(self, _event=None) -> None:
+        """
+        Hide the tooltip when the mouse leaves the widget.
+
+        Withdraw only, never destroy: the window stays for the next hover,
+        which from the source eliminates the ghost frames caused by repeatedly
+        destroying override-redirect windows on macOS-arm.
+        """
+        if self.tip_window is not None:
+            try:
+                self.tip_window.withdraw()
+            except tk.TclError:
+                self.tip_window = None
+                self._label = None
+
+
+def _to_int(value, fallback: int) -> int:
+    """
+    Safely convert a Tk geometry value to int, returning fallback on failure.
+
+    Under mocks or abnormal Tk states, winfo_* may return a non-int (MagicMock,
+    empty string, etc.); int() would raise TypeError. This wrapper guards the
+    coordinate calculations so they never abort.
+    """
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return fallback
+
+
+def _safe_screen_height(root: tk.Misc) -> int | None:
+    """
+    Return the screen height of the root window's screen, or None on failure / non-int.
+
+    Tk may raise TclError for winfo_screenheight in some abnormal states, and
+    under mocks the return value is not an int; callers skip the below-flip
+    check in that case.
+    """
+    try:
+        value = root.winfo_screenheight()
+    except tk.TclError:
+        return None
+    if isinstance(value, int):
+        return value
+    return None
+
+
+def bind_tooltip(
+    widget,
+    string_key: str,
+    *,
+    root: tk.Misc | None = None,
+    position: _TooltipPosition = 'below',
+    **fmt,
+) -> ToolTip:
+    """Bind a tooltip with text from strings.json to a widget."""
+    return ToolTip(
+        widget, get_string(string_key, **fmt), root=root, position=position,
+    )

treeing/gui_entry.py

@@ -0,0 +1,39 @@
+"""treeing/gui_entry.py
+
+PyInstaller GUI entry point.
+Creates the Tk root and starts TreeingApp, catching ConfigError so the packaged app still exits cleanly.
+"""
+import sys
+
+from treeing.config import ConfigError, get_ui_string
+
+
+def run_gui() -> int:
+    """
+    Create the Tk main window and run TreeingApp.
+
+    If the current environment is missing Tcl/Tk, print an error message and
+    return 1, rather than raising an opaque TclError.
+    """
+    import tkinter as tk
+
+    from treeing.gui.app import TreeingApp
+
+    try:
+        root = tk.Tk()
+    except tk.TclError as exc:
+        print(get_ui_string('gui_err_tcl_missing'), file=sys.stderr)
+        print(f"Underlying error: {exc}", file=sys.stderr)
+        return 1
+
+    TreeingApp(root)
+    root.mainloop()
+    return 0
+
+
+if __name__ == '__main__':
+    try:
+        sys.exit(run_gui())
+    except ConfigError as e:
+        print(str(e), file=sys.stderr)
+        sys.exit(1)

treeing/main.py

@@ -0,0 +1,21 @@
+#!/usr/bin/env python3
+"""treeing/main.py
+
+Unified entry script for development.
+Starts the GUI with no arguments, or runs the CLI with arguments; a ConfigError is caught and reported with a non-zero exit code.
+"""
+import sys
+
+from treeing.cli.main import cli_main
+from treeing.config import ConfigError
+from treeing.gui_entry import run_gui
+
+if __name__ == '__main__':
+    try:
+        if len(sys.argv) > 1:
+            sys.exit(cli_main())
+        else:
+            run_gui()
+    except ConfigError as e:
+        print(str(e), file=sys.stderr)
+        sys.exit(1)

treeing/path_checks.py

@@ -0,0 +1,87 @@
+"""treeing/path_checks.py
+
+Defines output-path validation logic.
+Provides `verify_output_is_directory` and `verify_output_writable`,
+shared by the CLI and GUI, to ensure the target directory is legal and writable.
+"""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from pathlib import Path
+
+from .config import get_string
+
+
+def verify_output_is_directory(output: str | Path) -> str | None:
+    """
+    Check whether the output path is legal.
+
+    Returns an error message if the path exists and is a file; otherwise None.
+    """
+    target = Path(output).expanduser()
+    if target.exists() and target.is_file():
+        return get_string('cli_output_is_file', path=target)
+    return None
+
+
+def _nearest_existing(path: Path) -> Path | None:
+    """Walk upward from path to the nearest existing parent directory; return None if none exists."""
+    probe = path
+    while not probe.exists():
+        parent = probe.parent
+        if parent == probe:
+            return None
+        probe = parent
+    return probe
+
+
+def _probe_writable_dir(dir_path: Path, report_path: Path) -> str | None:
+    """
+    Actually probe whether a directory is writable.
+
+    Checks os.access first, then tries to create a temporary directory as a
+    second safeguard. MING added the temporary-directory test because some
+    mount/network paths report writable via access but fail on real writes.
+    """
+    try:
+        resolved = dir_path.resolve()
+    except OSError:
+        return get_string('cli_output_not_writable', path=report_path)
+
+    if not resolved.is_dir():
+        return get_string('cli_output_not_writable', path=report_path)
+
+    if not os.access(resolved, os.W_OK):
+        return get_string('cli_output_not_writable', path=resolved)
+    if os.name != 'nt' and not os.access(resolved, os.X_OK):
+        return get_string('cli_output_not_writable', path=resolved)
+
+    try:
+        test_dir = tempfile.mkdtemp(prefix='.treeing-write-test-', dir=str(resolved))
+        os.rmdir(test_dir)
+    except OSError:
+        return get_string('cli_output_not_writable', path=report_path)
+    return None
+
+
+def verify_output_writable(output: str | Path) -> str | None:
+    """
+    Check whether the output path is ultimately writable.
+
+    If the target directory does not exist, walk up to the nearest existing
+    parent before probing.
+    """
+    err = verify_output_is_directory(output)
+    if err:
+        return err
+
+    target = Path(output).expanduser()
+    if target.exists():
+        return _probe_writable_dir(target, target)
+
+    existing = _nearest_existing(target)
+    if existing is None:
+        return get_string('cli_output_not_writable', path=output)
+    return _probe_writable_dir(existing, target)

treeing/strings.bootstrap.json

@@ -0,0 +1,7 @@
+{
+  "config_err_missing": "Could not find config file strings.json: {path}",
+  "config_err_invalid_json": "strings.json has invalid JSON: {path} ({error})",
+  "config_err_read": "Could not read config file strings.json: {path} ({error})",
+  "config_err_not_object": "strings.json root must be a JSON object: {path}",
+  "config_err_bootstrap_missing": "Could not load the bootstrap strings file strings.bootstrap.json: {path}"
+}