kappman 0.1.0__tar.gz

kappman-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

kappman-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

kappman-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KAppMan Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kappman-0.1.0/PKG-INFO

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: kappman
+Version: 0.1.0
+Summary: A KDE-native AppImage manager — watch, integrate, and manage AppImages from your desktop.
+Author: KAppMan Contributors
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: pyqt6>=6.6.0
+Requires-Dist: watchdog>=4.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-mock>=3.12; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# KAppMan – KDE AppImage Manager
+
+> A lightweight, KDE-native AppImage manager built with Python + PyQt6. Managed by [uv](https://github.com/astral-sh/uv).
+
+## Features
+
+- **Auto-integrate** AppImages from any directory you choose
+- **Desktop entries** auto-generated in `~/.local/share/applications/` (XDG compliant)
+- **Folder watcher** — drop an AppImage and it's integrated instantly
+- **Configurable watch directory** — set it from the GUI or CLI
+- **Live theme switching** — pick any `.qss` file from a directory; ships with four themes:
+  - Catppuccin Mocha (default)
+  - Catppuccin Macchiato
+  - Catppuccin Latte
+  - Breeze Dark
+- **Custom themes** — drop your own `.qss` into the themes directory and it appears in the selector instantly
+
+---
+
+## Install
+
+```bash
+# Requires uv — https://docs.astral.sh/uv/
+git clone https://github.com/you/KAppMan
+cd KAppMan
+uv sync
+```
+
+---
+
+## Usage
+
+```bash
+# Launch the GUI (default)
+uv run kappman
+
+# Headless folder watcher (default dir: ~/AppImages)
+uv run kappman --watch
+
+# Watch a custom directory
+uv run kappman --watch /mnt/storage/Apps
+
+# One-shot: integrate a single AppImage
+uv run kappman --integrate ~/Downloads/MyApp.AppImage
+
+# Remove a desktop entry
+uv run kappman --remove ~/AppImages/MyApp.AppImage
+
+# List all KAppMan-integrated apps
+uv run kappman --list
+```
+
+---
+
+## Adding Themes
+
+1. Create a `.qss` file (standard Qt stylesheet syntax)
+2. Drop it into `kappman/themes/` **or** any custom directory
+3. In the GUI, point the **Themes Directory** field to your folder
+4. Select your theme from the dropdown — applied instantly, no restart needed
+
+Your theme choice and directory are persisted to `~/.config/kappman/config.ini`.
+
+---
+
+## KDE Autostart
+
+To auto-run the watcher on every login:
+
+```bash
+cp kappman/autostart/kappman-watcher.desktop ~/.config/autostart/
+```
+
+---
+
+## Development
+
+```bash
+uv sync
+uv run pytest tests/ -v
+```
+
+---
+
+## License
+
+MIT

kappman-0.1.0/README.md

@@ -0,0 +1,87 @@
+# KAppMan – KDE AppImage Manager
+
+> A lightweight, KDE-native AppImage manager built with Python + PyQt6. Managed by [uv](https://github.com/astral-sh/uv).
+
+## Features
+
+- **Auto-integrate** AppImages from any directory you choose
+- **Desktop entries** auto-generated in `~/.local/share/applications/` (XDG compliant)
+- **Folder watcher** — drop an AppImage and it's integrated instantly
+- **Configurable watch directory** — set it from the GUI or CLI
+- **Live theme switching** — pick any `.qss` file from a directory; ships with four themes:
+  - Catppuccin Mocha (default)
+  - Catppuccin Macchiato
+  - Catppuccin Latte
+  - Breeze Dark
+- **Custom themes** — drop your own `.qss` into the themes directory and it appears in the selector instantly
+
+---
+
+## Install
+
+```bash
+# Requires uv — https://docs.astral.sh/uv/
+git clone https://github.com/you/KAppMan
+cd KAppMan
+uv sync
+```
+
+---
+
+## Usage
+
+```bash
+# Launch the GUI (default)
+uv run kappman
+
+# Headless folder watcher (default dir: ~/AppImages)
+uv run kappman --watch
+
+# Watch a custom directory
+uv run kappman --watch /mnt/storage/Apps
+
+# One-shot: integrate a single AppImage
+uv run kappman --integrate ~/Downloads/MyApp.AppImage
+
+# Remove a desktop entry
+uv run kappman --remove ~/AppImages/MyApp.AppImage
+
+# List all KAppMan-integrated apps
+uv run kappman --list
+```
+
+---
+
+## Adding Themes
+
+1. Create a `.qss` file (standard Qt stylesheet syntax)
+2. Drop it into `kappman/themes/` **or** any custom directory
+3. In the GUI, point the **Themes Directory** field to your folder
+4. Select your theme from the dropdown — applied instantly, no restart needed
+
+Your theme choice and directory are persisted to `~/.config/kappman/config.ini`.
+
+---
+
+## KDE Autostart
+
+To auto-run the watcher on every login:
+
+```bash
+cp kappman/autostart/kappman-watcher.desktop ~/.config/autostart/
+```
+
+---
+
+## Development
+
+```bash
+uv sync
+uv run pytest tests/ -v
+```
+
+---
+
+## License
+
+MIT

kappman-0.1.0/kappman/__init__.py

@@ -0,0 +1,4 @@
+"""KAppMan - KDE AppImage Manager package."""
+
+__version__ = "0.1.0"
+__app_name__ = "KAppMan"

kappman-0.1.0/kappman/autostart/kappman-watcher.desktop

@@ -0,0 +1,9 @@
+[Desktop Entry]
+Name=KAppMan Watcher
+Comment=Automatically integrates AppImages from your watch directory into the KDE menu
+Exec=kappman --watch
+Icon=application-x-executable
+Type=Application
+X-KDE-autostart-condition=
+X-KDE-AutostartScript=true
+Hidden=false

kappman-0.1.0/kappman/config.py

@@ -0,0 +1,110 @@
+"""
+kappman.config
+==============
+Persistent user configuration stored at ~/.config/kappman/config.ini.
+
+Stores:
+  - watch_dir  : directory to monitor for new AppImages (default: ~/AppImages)
+  - theme      : name of the active .qss theme file without extension
+                 (default: catppuccin_mocha)
+  - themes_dir : directory scanned for .qss theme files
+                 (default: the built-in kappman/themes/ package directory)
+"""
+
+from __future__ import annotations
+
+import configparser
+from pathlib import Path
+
+_CONFIG_DIR = Path.home() / ".config" / "kappman"
+_CONFIG_FILE = _CONFIG_DIR / "config.ini"
+
+# Built-in themes bundled with the package
+_BUILTIN_THEMES_DIR = Path(__file__).parent / "themes"
+
+_SECTION = "kappman"
+_DEFAULTS: dict[str, str] = {
+    "watch_dir": str(Path.home() / "AppImages"),
+    "theme": "catppuccin_mocha",
+    "themes_dir": str(_BUILTIN_THEMES_DIR),
+}
+
+
+def _load() -> configparser.ConfigParser:
+    cfg = configparser.ConfigParser()
+    cfg[_SECTION] = _DEFAULTS.copy()
+    if _CONFIG_FILE.exists():
+        cfg.read(_CONFIG_FILE, encoding="utf-8")
+    return cfg
+
+
+def _save(cfg: configparser.ConfigParser) -> None:
+    _CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    with open(_CONFIG_FILE, "w", encoding="utf-8") as fh:
+        cfg.write(fh)
+
+
+# ── Watch directory ────────────────────────────────────────────────────────
+
+def get_watch_dir() -> Path:
+    return Path(_load()[_SECTION]["watch_dir"]).expanduser()
+
+
+def set_watch_dir(directory: str | Path) -> None:
+    cfg = _load()
+    cfg[_SECTION]["watch_dir"] = str(Path(directory).expanduser().resolve())
+    _save(cfg)
+
+
+# ── Themes directory ───────────────────────────────────────────────────────
+
+def get_themes_dir() -> Path:
+    return Path(_load()[_SECTION]["themes_dir"]).expanduser()
+
+
+def set_themes_dir(directory: str | Path) -> None:
+    cfg = _load()
+    cfg[_SECTION]["themes_dir"] = str(Path(directory).expanduser().resolve())
+    _save(cfg)
+
+
+def list_themes(themes_dir: Path | None = None) -> list[str]:
+    """
+    Return a sorted list of theme names (filename stems) found in *themes_dir*.
+    Falls back to the built-in themes directory if none given.
+    """
+    d = themes_dir or get_themes_dir()
+    if not d.exists():
+        return []
+    return sorted(p.stem for p in d.glob("*.qss"))
+
+
+def load_theme_stylesheet(theme_name: str, themes_dir: Path | None = None) -> str:
+    """
+    Read and return the QSS content for *theme_name*.
+    Looks in *themes_dir* first, then in the built-in themes directory.
+    Returns an empty string if the file is not found.
+    """
+    dirs = []
+    if themes_dir:
+        dirs.append(Path(themes_dir))
+    dirs.append(get_themes_dir())
+    dirs.append(_BUILTIN_THEMES_DIR)
+
+    for d in dirs:
+        qss_file = d / f"{theme_name}.qss"
+        if qss_file.exists():
+            return qss_file.read_text(encoding="utf-8")
+    return ""
+
+
+# ── Active theme ───────────────────────────────────────────────────────────
+
+def get_theme() -> str:
+    return _load()[_SECTION]["theme"]
+
+
+def set_theme(theme_name: str) -> None:
+    cfg = _load()
+    cfg[_SECTION]["theme"] = theme_name
+    _save(cfg)

kappman-0.1.0/kappman/core.py

@@ -0,0 +1,239 @@
+"""
+kappman.core
+============
+Core logic for AppImage integration and removal.
+
+Responsibilities
+----------------
+- Make an AppImage executable (``chmod +x``).
+- Write an XDG-compliant ``.desktop`` entry to
+  ``~/.local/share/applications/`` so the application appears in the KDE
+  (and any other XDG-conformant) application menu.
+- Optionally extract an icon from the AppImage via ``unsquashfs``.
+- Remove a previously created ``.desktop`` entry.
+- List all AppImages currently managed by KAppMan (identified by the
+  ``X-KAppMan-Source`` key injected into every entry we create).
+
+All public functions raise :class:`FileNotFoundError` when given a path that
+does not exist and return plain dicts or booleans so that callers (GUI,
+watcher, CLI) can present output in whatever way is appropriate for their
+context.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import shutil
+import stat
+import subprocess
+import tempfile
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+APPLICATIONS_DIR = Path.home() / ".local" / "share" / "applications"
+ICONS_DIR = Path.home() / ".local" / "share" / "icons" / "kappman"
+
+
+def _ensure_dirs() -> None:
+    APPLICATIONS_DIR.mkdir(parents=True, exist_ok=True)
+    ICONS_DIR.mkdir(parents=True, exist_ok=True)
+
+
+def _desktop_path(app_name: str) -> Path:
+    return APPLICATIONS_DIR / f"{app_name}.desktop"
+
+
+def _sanitize_name(file_path: Path) -> str:
+    """Return a display name by stripping the ``.AppImage`` / ``.appimage`` suffix."""
+    name = file_path.name
+    for suffix in (".AppImage", ".appimage"):
+        if name.endswith(suffix):
+            return name[: -len(suffix)]
+    return name
+
+
+def _extract_icon(appimage_path: Path, app_name: str) -> Path | None:
+    """Attempt to extract an icon from *appimage_path* using ``unsquashfs``.
+
+    The extraction is best-effort.  If ``unsquashfs`` is not installed, or if
+    the AppImage does not contain a recognisable icon, ``None`` is returned and
+    the caller falls back to a generic system icon.
+
+    Parameters
+    ----------
+    appimage_path:
+        Absolute path to the AppImage file.
+    app_name:
+        Sanitised application name used to name the extracted icon file.
+
+    Returns
+    -------
+    Path | None
+        Absolute path to the extracted icon, or ``None`` on failure.
+    """
+    if not shutil.which("unsquashfs"):
+        logger.debug("unsquashfs not found — skipping icon extraction")
+        return None
+
+    try:
+        with tempfile.TemporaryDirectory(prefix="kappman_") as tmpdir:
+            subprocess.run(
+                [
+                    "unsquashfs", "-n", "-i",
+                    "-d", f"{tmpdir}/squash",
+                    str(appimage_path),
+                    "*.png", "*.svg", "*.DirIcon",
+                ],
+                capture_output=True,
+                timeout=15,
+            )
+            squash_root = Path(tmpdir) / "squash"
+            for pattern in ("*.png", "*.svg", ".DirIcon"):
+                candidates = sorted(squash_root.rglob(pattern))
+                if candidates:
+                    src = candidates[0]
+                    dest = ICONS_DIR / f"{app_name}{src.suffix}"
+                    shutil.copy2(src, dest)
+                    logger.info("Extracted icon: %s", dest)
+                    return dest
+    except Exception:
+        logger.debug("Icon extraction failed for %s", appimage_path, exc_info=True)
+
+    return None
+
+
+def integrate_appimage(file_path: str | Path) -> dict:
+    """Make *file_path* executable and register it in the application menu.
+
+    Steps performed:
+
+    1. Resolve the absolute path and verify the file exists.
+    2. Set the executable bit (equivalent to ``chmod +x``).
+    3. Attempt icon extraction via :func:`_extract_icon`.
+    4. Write a ``.desktop`` entry to :data:`APPLICATIONS_DIR`.
+
+    Parameters
+    ----------
+    file_path:
+        Path to the AppImage, accepts ``~`` expansion.
+
+    Returns
+    -------
+    dict
+        A dict with keys ``app_name``, ``exec_path``, ``desktop_path``, and
+        ``icon_path`` (``None`` if no icon could be extracted).
+
+    Raises
+    ------
+    FileNotFoundError
+        If *file_path* does not exist.
+    """
+    _ensure_dirs()
+
+    path = Path(os.path.abspath(os.path.expanduser(file_path)))
+    if not path.exists():
+        raise FileNotFoundError(f"AppImage not found: {path}")
+
+    current_mode = path.stat().st_mode
+    path.chmod(current_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+    logger.info("Made executable: %s", path)
+
+    app_name = _sanitize_name(path)
+    icon_path = _extract_icon(path, app_name)
+    icon_value = str(icon_path) if icon_path else "application-x-executable"
+
+    desktop_content = (
+        "[Desktop Entry]\n"
+        f"Name={app_name}\n"
+        f"Exec={path}\n"
+        f"Icon={icon_value}\n"
+        "Type=Application\n"
+        "Categories=Utility;\n"
+        "Terminal=false\n"
+        "StartupNotify=true\n"
+        f"Comment=AppImage managed by KAppMan\n"
+        f"X-KAppMan-Source={path}\n"
+    )
+
+    dp = _desktop_path(app_name)
+    dp.write_text(desktop_content, encoding="utf-8")
+    logger.info("Desktop entry written: %s", dp)
+
+    return {
+        "app_name": app_name,
+        "exec_path": str(path),
+        "desktop_path": str(dp),
+        "icon_path": str(icon_path) if icon_path else None,
+    }
+
+
+def remove_appimage(file_path: str | Path) -> bool:
+    """Remove the ``.desktop`` entry associated with *file_path*.
+
+    The AppImage file itself is **not** deleted.
+
+    Parameters
+    ----------
+    file_path:
+        Path to the AppImage whose desktop entry should be removed.
+
+    Returns
+    -------
+    bool
+        ``True`` if a desktop entry was found and deleted; ``False`` if no
+        matching entry existed.
+    """
+    path = Path(os.path.abspath(os.path.expanduser(file_path)))
+    app_name = _sanitize_name(path)
+    dp = _desktop_path(app_name)
+
+    if not dp.exists():
+        logger.warning("Desktop entry not found for %s", app_name)
+        return False
+
+    dp.unlink()
+    logger.info("Removed desktop entry: %s", dp)
+
+    for suffix in (".png", ".svg", ""):
+        icon = ICONS_DIR / f"{app_name}{suffix}"
+        if icon.exists():
+            icon.unlink()
+            logger.info("Removed icon: %s", icon)
+            break
+
+    return True
+
+
+def list_integrated() -> list[dict]:
+    """Return a list of all AppImages currently managed by KAppMan.
+
+    Only ``.desktop`` files that contain the ``X-KAppMan-Source`` marker key
+    are included.  This prevents KAppMan from claiming ownership of desktop
+    entries created by other tools.
+
+    Returns
+    -------
+    list[dict]
+        Each item has keys ``app_name``, ``exec_path``, and ``desktop_path``.
+    """
+    if not APPLICATIONS_DIR.exists():
+        return []
+
+    results = []
+    for desktop_file in sorted(APPLICATIONS_DIR.glob("*.desktop")):
+        content = desktop_file.read_text(encoding="utf-8", errors="ignore")
+        if "X-KAppMan-Source=" not in content:
+            continue
+        exec_path = ""
+        for line in content.splitlines():
+            if line.startswith("X-KAppMan-Source="):
+                exec_path = line.split("=", 1)[1]
+                break
+        results.append({
+            "app_name": desktop_file.stem,
+            "exec_path": exec_path,
+            "desktop_path": str(desktop_file),
+        })
+    return results