desktop-lifecycle 0.1.0__py3-none-any.whl

desktop_lifecycle/__init__.py

@@ -0,0 +1,56 @@
+"""The boring parts of a small Python desktop application.
+
+Single-instance guard, XDG paths, autostart, menu entries, session detection,
+tray capability and rotating logs - without a framework and without a
+dependency.
+
+    from desktop_lifecycle import App
+
+    app = App("my-tool").ensure_dirs()
+    app.setup_logging()
+    if not app.acquire():
+        raise SystemExit(0)          # asked the running copy to show itself
+"""
+
+from __future__ import annotations
+
+from ._util import validate_app_name
+from .autostart import Autostart
+from .desktop_entry import (
+    build_entry,
+    install_icon,
+    install_menu_entry,
+    remove_menu_entry,
+)
+from .lifecycle import App
+from .logging_setup import setup_logging
+from .paths import Paths
+from .session import has_gui, is_linux, is_wayland, is_x11, session_type
+from .single_instance import AlreadyRunning, SingleInstance
+from .tray import TrayUnavailable, available as tray_available, backend as tray_backend, create as create_tray
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "App",
+    "Autostart",
+    "AlreadyRunning",
+    "Paths",
+    "SingleInstance",
+    "TrayUnavailable",
+    "build_entry",
+    "create_tray",
+    "has_gui",
+    "install_icon",
+    "install_menu_entry",
+    "is_linux",
+    "is_wayland",
+    "is_x11",
+    "remove_menu_entry",
+    "session_type",
+    "setup_logging",
+    "tray_available",
+    "tray_backend",
+    "validate_app_name",
+    "__version__",
+]

desktop_lifecycle/__main__.py

@@ -0,0 +1,80 @@
+"""``python -m desktop_lifecycle`` - a read-only environment report.
+
+Paste this into a bug report instead of pasting ``ls -la ~``.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import platform
+import sys
+
+from . import __version__
+from .lifecycle import App
+from .tray import _INSTALL_HINT, backend as tray_backend
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="desktop-lifecycle",
+        description="Report where a desktop application would write and which "
+        "tray backend this session can use.",
+    )
+    parser.add_argument(
+        "--app",
+        default="desktop-lifecycle-example",
+        help="application name to resolve paths for (default: %(default)s)",
+    )
+    parser.add_argument("--json", action="store_true", help="machine-readable output")
+    parser.add_argument(
+        "--init",
+        action="store_true",
+        help="create the directories (all other runs are read-only)",
+    )
+    return parser
+
+
+def main(argv=None) -> int:
+    arguments = _build_parser().parse_args(argv)
+    try:
+        app = App(arguments.app, argv=[])
+    except ValueError as error:
+        print(f"error: {error}", file=sys.stderr)
+        return 2
+
+    if arguments.init:
+        app.ensure_dirs()
+
+    report = app.describe()
+    report["tray_install_hint"] = "" if report["tray_backend"] != "none" else _INSTALL_HINT
+    report["directories_exist"] = {
+        key: Path(value).is_dir()
+        for key, value in report["paths"].items()
+        if key != "app"
+    }
+
+    if arguments.json:
+        print(json.dumps(report, indent=2, sort_keys=True))
+        return 0
+
+    print(f"desktop-lifecycle {__version__}")
+    print(f"  python        {platform.python_version()}")
+    print(f"  platform      {report['platform']}")
+    print(f"  session       {report['session']}")
+    print(f"  tray backend  {report['tray_backend']}")
+    print(f"  app name      {report['name']}")
+    print("  directories")
+    for key, value in report["paths"].items():
+        if key == "app":
+            continue
+        state = "exists" if report["directories_exist"].get(key) else "missing"
+        print(f"    {key:<7} {value}  [{state}]")
+    if report["tray_install_hint"]:
+        print(f"  note          {report['tray_install_hint']}")
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

desktop_lifecycle/_util.py

@@ -0,0 +1,133 @@
+"""Internal helpers: name validation, atomic writes and Exec= quoting.
+
+Everything in here is deliberately small and dependency-free. The quoting
+rules matter: a wrong ``Exec=`` line is the number one reason a desktop entry
+silently refuses to launch, and an unescaped ``$`` or backtick in a path can be
+executed by the shell that some launchers still use.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+import re
+import tempfile
+
+__all__ = [
+    "validate_app_name",
+    "ensure_dir",
+    "atomic_write",
+    "quote_exec_arg",
+    "quote_exec",
+    "escape_entry_value",
+]
+
+# 1-64 characters, must start with a letter or digit, no path separators.
+# Reversed-DNS names (com.example.app) are accepted on purpose.
+_APP_NAME_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$")
+
+
+def validate_app_name(name: str) -> str:
+    """Return a safe application name or raise ``ValueError``.
+
+    The name becomes a directory name, a file name and a registry value, so it
+    must not be able to escape any of those places.
+    """
+    if not isinstance(name, str):
+        raise TypeError("application name must be a string")
+    candidate = name.strip()
+    if (
+        not candidate
+        or not _APP_NAME_RE.match(candidate)
+        or ".." in candidate
+        or candidate.endswith(".")
+    ):
+        raise ValueError(
+            f"invalid application name {name!r}: use 1-64 characters from "
+            "[A-Za-z0-9._-], starting with a letter or digit"
+        )
+    return candidate
+
+
+def ensure_dir(path, mode: int = 0o700) -> Path:
+    """Create ``path`` (and parents) if needed and return it as a ``Path``."""
+    target = Path(path)
+    target.mkdir(parents=True, exist_ok=True, mode=mode)
+    return target
+
+
+def atomic_write(path, text: str, mode: int = 0o644) -> Path:
+    """Write ``text`` to ``path`` atomically with an explicit mode.
+
+    A half-written autostart entry or settings file is worse than no file at
+    all, so the data goes to a temporary file in the same directory first and
+    is then renamed into place.
+    """
+    target = Path(path)
+    ensure_dir(target.parent, mode=0o700)
+    fd, temporary = tempfile.mkstemp(
+        dir=str(target.parent), prefix=f".{target.name}.", suffix=".tmp"
+    )
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8", newline="\n") as handle:
+            handle.write(text)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.chmod(temporary, mode)
+        os.replace(temporary, target)
+    except BaseException:
+        try:
+            os.unlink(temporary)
+        except OSError:
+            pass
+        raise
+    return target
+
+
+def escape_entry_value(value: str) -> str:
+    """Escape a desktop-entry *value* (``Name=``, ``Comment=``, ...).
+
+    The specification reserves backslash and newline inside values.
+    """
+    return (
+        str(value)
+        .replace("\\", "\\\\")
+        .replace("\r", "")
+        .replace("\n", "\\n")
+    )
+
+
+def quote_exec_arg(value: str, *, windows=None) -> str:
+    """Quote a single argument for an ``Exec=`` field or a Windows command.
+
+    ``windows`` defaults to the host platform, but callers that produce a file
+    for a *different* platform pass it explicitly: a ``.desktop`` file uses
+    POSIX quoting even when it is written from Windows, and the Windows
+    ``Run`` registry value uses Windows quoting even when the test suite runs
+    on Linux.
+
+    POSIX quoting follows the rules every mainstream launcher applies:
+    backslash escapes ``"``, `````, ``$`` and ``\\`` inside a double-quoted
+    argument, and ``%`` is doubled because a single ``%`` starts a field code
+    (``%f``, ``%U``).
+    """
+    text = str(value).replace("\r", " ").replace("\n", " ")
+    if (os.name == "nt") if windows is None else windows:
+        # Windows command lines use their own quoting rules; only quote when
+        # the argument actually needs it.
+        if text and not any(character in text for character in ' \t"'):
+            return text
+        return '"' + text.replace('"', '\\"') + '"'
+    escaped = (
+        text.replace("\\", "\\\\")
+        .replace('"', '\\"')
+        .replace("`", "\\`")
+        .replace("$", "\\$")
+        .replace("%", "%%")
+    )
+    return f'"{escaped}"'
+
+
+def quote_exec(parts, *, windows=None) -> str:
+    """Quote a whole command line for ``Exec=`` / autostart use."""
+    return " ".join(quote_exec_arg(part, windows=windows) for part in parts)

desktop_lifecycle/autostart.py

@@ -0,0 +1,222 @@
+"""Start at login, on every platform, without asking for root.
+
+Linux uses an XDG autostart entry, Windows uses the per-user ``Run`` registry
+key, macOS uses a LaunchAgent. All three are user-scoped: no administrator
+rights, no system-wide changes, and turning it off leaves nothing behind.
+"""
+
+from __future__ import annotations
+
+import os
+import platform
+import plistlib
+from pathlib import Path
+
+from ._util import (
+    atomic_write,
+    ensure_dir,
+    escape_entry_value,
+    quote_exec,
+    validate_app_name,
+)
+from .paths import Paths
+
+__all__ = ["Autostart"]
+
+
+class Autostart:
+    """Toggle "start when I log in" for one application.
+
+    >>> autostart = Autostart("my-app", ["/usr/bin/python3", "-m", "my_app"])
+    >>> autostart.enable()
+    True
+    >>> autostart.enabled
+    True
+    """
+
+    def __init__(
+        self,
+        app: str,
+        exec_parts,
+        *,
+        args=(),
+        comment: str = "",
+        icon=None,
+        hidden_arg: str | None = "--background",
+        paths=None,
+        system=None,
+        home=None,
+        env=None,
+    ):
+        self.app = validate_app_name(app)
+        if isinstance(exec_parts, (str, Path)):
+            raise TypeError("exec_parts must be a sequence, not a single string")
+        self.exec_parts = [str(part) for part in exec_parts]
+        if not self.exec_parts:
+            raise ValueError("exec_parts must contain at least the program to run")
+        self.args = [str(arg) for arg in args]
+        if hidden_arg and hidden_arg not in self.args:
+            self.args.append(hidden_arg)
+        self.comment = comment
+        self.icon = icon
+        self.system = platform.system() if system is None else system
+        self.env = os.environ if env is None else env
+        self.home = Path(home) if home is not None else Path.home()
+        self.paths = paths or Paths.for_app(
+            self.app, env=self.env, system=self.system, home=self.home
+        )
+
+    # -- locations -------------------------------------------------------
+    @property
+    def command(self) -> list[str]:
+        return [*self.exec_parts, *self.args]
+
+    @property
+    def target(self) -> Path:
+        """The file (or registry value) that represents the autostart entry."""
+        if self.system == "Windows":
+            return Path(f"HKCU:Software/Microsoft/Windows/CurrentVersion/Run/{self.app}")
+        if self.system == "Darwin":
+            return (
+                self.home
+                / "Library"
+                / "LaunchAgents"
+                / f"{self._label}.plist"
+            )
+        return Path(self.paths.config_home) / "autostart" / f"{self.app}.desktop"
+
+    @property
+    def _label(self) -> str:
+        """Reverse-DNS-ish launchd label; ``my-app`` becomes ``my-app``."""
+        return self.app
+
+    # -- state -----------------------------------------------------------
+    @property
+    def enabled(self) -> bool:
+        if self.system == "Windows":
+            return self._windows_value() is not None
+        return self.target.exists()
+
+    # -- public API ------------------------------------------------------
+    def enable(self) -> bool:
+        """Create the entry. Returns ``True`` when it is in place afterwards."""
+        if self.system == "Windows":
+            return self._windows_set(quote_exec(self.command))
+        if self.system == "Darwin":
+            return self._macos_set()
+        return self._linux_set()
+
+    def disable(self) -> bool:
+        """Remove the entry. Returns ``True`` when nothing is left behind."""
+        if self.system == "Windows":
+            self._windows_delete()
+            return not self.enabled
+        try:
+            self.target.unlink()
+        except FileNotFoundError:
+            return True
+        except OSError:
+            return False
+        return True
+
+    def toggle(self) -> bool:
+        return self.disable() if self.enabled else self.enable()
+
+    # -- Linux -----------------------------------------------------------
+    def _linux_set(self) -> bool:
+        lines = [
+            "[Desktop Entry]",
+            "Type=Application",
+            f"Name={escape_entry_value(self.app)}",
+        ]
+        if self.comment:
+            lines.append(f"Comment={escape_entry_value(self.comment)}")
+        lines.append(f"Exec={quote_exec(self.command, windows=False)}")
+        if self.icon:
+            # Desktop entries want an absolute path here; a bare name has to be
+            # looked up through the icon theme and often silently fails.
+            lines.append(f"Icon={escape_entry_value(str(self.icon))}")
+        lines.extend(
+            [
+                "Terminal=false",
+                "X-GNOME-Autostart-enabled=true",
+                "Hidden=false",
+                "",
+            ]
+        )
+        try:
+            atomic_write(self.target, "\n".join(lines), mode=0o644)
+        except OSError:
+            return False
+        return True
+
+    # -- macOS -----------------------------------------------------------
+    def _macos_set(self) -> bool:
+        payload = {
+            "Label": self._label,
+            "ProgramArguments": list(self.command),
+            "RunAtLoad": True,
+            "ProcessType": "Interactive",
+        }
+        try:
+            ensure_dir(self.target.parent)
+            data = plistlib.dumps(payload, fmt=plistlib.FMT_XML)
+            self.target.write_bytes(data)
+            self.target.chmod(0o644)
+        except OSError:
+            return False
+        return True
+
+    # -- Windows ---------------------------------------------------------
+    def _windows_key(self):
+        import winreg  # noqa: PLC0415 - Windows-only import
+
+        return winreg.OpenKey(
+            winreg.HKEY_CURRENT_USER,
+            r"Software\Microsoft\Windows\CurrentVersion\Run",
+            0,
+            winreg.KEY_SET_VALUE | winreg.KEY_QUERY_VALUE,
+        )
+
+    def _windows_value(self):
+        try:
+            import winreg  # noqa: PLC0415 - Windows-only import
+
+            with self._windows_key() as key:
+                value, _ = winreg.QueryValueEx(key, self.app)
+            return value
+        except (ImportError, OSError):
+            return None
+
+    def _windows_set(self, command: str) -> bool:
+        try:
+            import winreg  # noqa: PLC0415 - Windows-only import
+
+            with self._windows_key() as key:
+                winreg.SetValueEx(key, self.app, 0, winreg.REG_SZ, command)
+        except (ImportError, OSError):
+            return False
+        return True
+
+    def _windows_delete(self) -> bool:
+        try:
+            import winreg  # noqa: PLC0415 - Windows-only import
+
+            with self._windows_key() as key:
+                winreg.DeleteValue(key, self.app)
+        except FileNotFoundError:
+            return True
+        except (ImportError, OSError):
+            return False
+        return True
+
+    # -- diagnostics -----------------------------------------------------
+    def describe(self) -> dict:
+        return {
+            "app": self.app,
+            "system": self.system,
+            "enabled": self.enabled,
+            "target": str(self.target),
+            "command": self.command,
+            "exec_line": quote_exec(self.command, windows=self.system == "Windows"),
+        }

desktop_lifecycle/desktop_entry.py

@@ -0,0 +1,132 @@
+"""Menu entries and icons, written the way the specification asks for them.
+
+This module is pure and testable: :func:`build_entry` returns text, and
+:func:`install_menu_entry` only does file I/O. Nothing here runs a shell.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from pathlib import Path
+
+from ._util import (
+    atomic_write,
+    ensure_dir,
+    escape_entry_value,
+    quote_exec,
+    validate_app_name,
+)
+
+__all__ = [
+    "build_entry",
+    "install_menu_entry",
+    "remove_menu_entry",
+    "install_icon",
+    "applications_dir",
+]
+
+
+def build_entry(
+    *,
+    name: str,
+    exec_parts,
+    comment: str = "",
+    icon=None,
+    terminal: bool = False,
+    categories=("Utility",),
+    startup_notify: bool = True,
+    extra: dict | None = None,
+) -> str:
+    """Return a complete ``.desktop`` file as text.
+
+    ``exec_parts`` is a sequence (command, arg, arg...). Each part is quoted
+    separately, so paths with spaces, ``$``, backticks or quotes survive.
+    """
+    if isinstance(exec_parts, (str, Path)):
+        raise TypeError("exec_parts must be a sequence, not a single string")
+    parts = [str(part) for part in exec_parts]
+    if not parts or not parts[0]:
+        raise ValueError("exec_parts must contain at least the program to run")
+
+    lines = [
+        "[Desktop Entry]",
+        "Type=Application",
+        "Version=1.0",
+        f"Name={escape_entry_value(name)}",
+    ]
+    if comment:
+        lines.append(f"Comment={escape_entry_value(comment)}")
+    lines.append(f"Exec={quote_exec(parts, windows=False)}")
+    if icon:
+        lines.append(f"Icon={escape_entry_value(str(icon))}")
+    lines.append(f"Terminal={'true' if terminal else 'false'}")
+    lines.append(f"Categories={';'.join(categories)};")
+    if startup_notify:
+        lines.append("StartupNotify=true")
+    for key, value in (extra or {}).items():
+        lines.append(f"{key}={escape_entry_value(value)}")
+    return "\n".join(lines) + "\n"
+
+
+def applications_dir(paths) -> Path:
+    """``$XDG_DATA_HOME/applications`` for the given :class:`Paths`."""
+    return Path(paths.data_home) / "applications"
+
+
+def install_menu_entry(paths, name: str, exec_parts, **kwargs) -> Path:
+    """Write ``<data_home>/applications/<name>.desktop`` and refresh the cache."""
+    safe_name = validate_app_name(name)
+    target = applications_dir(paths) / f"{safe_name}.desktop"
+    text = build_entry(name=kwargs.pop("display_name", name), exec_parts=exec_parts, **kwargs)
+    atomic_write(target, text, mode=0o644)
+    _refresh_desktop_database(target.parent)
+    return target
+
+
+def remove_menu_entry(paths, name: str) -> bool:
+    """Delete the menu entry. Returns ``True`` when a file was removed."""
+    target = applications_dir(paths) / f"{validate_app_name(name)}.desktop"
+    try:
+        target.unlink()
+    except FileNotFoundError:
+        return False
+    _refresh_desktop_database(target.parent)
+    return True
+
+
+def install_icon(paths, icon_source, name: str) -> Path:
+    """Copy an icon into ``<data_home>/icons/hicolor/scalable/apps``.
+
+    The returned path is what belongs in ``Icon=``. SVG stays SVG; anything
+    else is copied byte-for-byte with its own suffix.
+    """
+    safe_name = validate_app_name(name)
+    source = Path(icon_source)
+    if not source.is_file():
+        raise FileNotFoundError(f"icon not found: {source}")
+    suffix = source.suffix.lower() or ".png"
+    target_dir = ensure_dir(
+        Path(paths.data_home) / "icons" / "hicolor" / "scalable" / "apps"
+    )
+    target = target_dir / f"{safe_name}{suffix}"
+    shutil.copyfile(source, target)
+    target.chmod(0o644)
+    return target
+
+
+def _refresh_desktop_database(directory: Path) -> None:
+    """Best-effort ``update-desktop-database``; never required, never a shell."""
+    executable = shutil.which("update-desktop-database")
+    if not executable:
+        return
+    try:
+        subprocess.run(
+            [executable, str(directory)],
+            check=False,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            timeout=10,
+        )
+    except (OSError, subprocess.SubprocessError):
+        pass