kuerzel 0.1.0__tar.gz

kuerzel-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+node_modules
+out
+dist
+release
+*.log
+.DS_Store
+Thumbs.db
+.vscode/*
+!.vscode/extensions.json
+.env*
+coverage
+__pycache__
+*.egg-info
+python/dist
+python/build

kuerzel-0.1.0/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.5
+Name: kuerzel
+Version: 0.1.0
+Summary: Kürzel, a desktop studio for Espanso snippets. This package downloads and starts the app.
+Project-URL: Homepage, https://github.com/maximilianfeix/kuerzel
+Project-URL: Releases, https://github.com/maximilianfeix/kuerzel/releases
+Project-URL: Issues, https://github.com/maximilianfeix/kuerzel/issues
+Project-URL: Changelog, https://github.com/maximilianfeix/kuerzel/blob/main/CHANGELOG.md
+Author: Maxi
+License-Expression: MIT
+Keywords: espanso,gui,productivity,snippets,text-expander
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: MacOS X
+Classifier: Environment :: Win32 (MS Windows)
+Classifier: Environment :: X11 Applications
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Text Processing
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# Kürzel
+
+A desktop studio for [Espanso](https://espanso.org) snippets: write, test and check your text expansions without editing YAML.
+
+![A tour of Kürzel](https://raw.githubusercontent.com/maximilianfeix/kuerzel/main/docs/tour.gif)
+
+## Run it
+
+```sh
+pipx run kuerzel
+```
+
+or install the command for good:
+
+```sh
+pipx install kuerzel
+kuerzel
+```
+
+`uvx kuerzel` and `pip install kuerzel` work too.
+
+## What this package is
+
+Kürzel is a desktop app, and too large for a Python wheel. This package is a small launcher with no dependencies. On first run it:
+
+1. downloads the build for your system from the project's [GitHub release](https://github.com/maximilianfeix/kuerzel/releases) of the same version,
+2. checks it against the release's published SHA-256 checksum and deletes it if it does not match,
+3. keeps it in your user cache folder and starts it.
+
+Later runs start the cached app straight away.
+
+| System              | What is downloaded | What happens                                         |
+| ------------------- | ------------------ | ---------------------------------------------------- |
+| Windows, 64-bit     | portable `.exe`    | The app starts.                                      |
+| Linux, x86-64       | `.AppImage`        | The app starts.                                      |
+| macOS, Intel or ARM | `.dmg`             | The disk image opens; drag Kürzel to Applications.   |
+
+## Options
+
+```text
+kuerzel             download if needed, then start the app
+kuerzel --path      print where the app is stored
+kuerzel --remove    delete the downloaded app
+kuerzel --version   print the version
+```
+
+## Good to know
+
+- The builds are not code-signed yet, so Windows and macOS warn on first launch.
+- Kürzel edits the files of an existing [Espanso installation](https://espanso.org/install/). Without Espanso it opens a sample workspace.
+- Kürzel is an independent project and is not affiliated with Espanso.
+
+What the app does, how it works and its limits are described in the [main README](https://github.com/maximilianfeix/kuerzel#readme).
+
+## License
+
+MIT

kuerzel-0.1.0/README.md

@@ -0,0 +1,57 @@
+# Kürzel
+
+A desktop studio for [Espanso](https://espanso.org) snippets: write, test and check your text expansions without editing YAML.
+
+![A tour of Kürzel](https://raw.githubusercontent.com/maximilianfeix/kuerzel/main/docs/tour.gif)
+
+## Run it
+
+```sh
+pipx run kuerzel
+```
+
+or install the command for good:
+
+```sh
+pipx install kuerzel
+kuerzel
+```
+
+`uvx kuerzel` and `pip install kuerzel` work too.
+
+## What this package is
+
+Kürzel is a desktop app, and too large for a Python wheel. This package is a small launcher with no dependencies. On first run it:
+
+1. downloads the build for your system from the project's [GitHub release](https://github.com/maximilianfeix/kuerzel/releases) of the same version,
+2. checks it against the release's published SHA-256 checksum and deletes it if it does not match,
+3. keeps it in your user cache folder and starts it.
+
+Later runs start the cached app straight away.
+
+| System              | What is downloaded | What happens                                         |
+| ------------------- | ------------------ | ---------------------------------------------------- |
+| Windows, 64-bit     | portable `.exe`    | The app starts.                                      |
+| Linux, x86-64       | `.AppImage`        | The app starts.                                      |
+| macOS, Intel or ARM | `.dmg`             | The disk image opens; drag Kürzel to Applications.   |
+
+## Options
+
+```text
+kuerzel             download if needed, then start the app
+kuerzel --path      print where the app is stored
+kuerzel --remove    delete the downloaded app
+kuerzel --version   print the version
+```
+
+## Good to know
+
+- The builds are not code-signed yet, so Windows and macOS warn on first launch.
+- Kürzel edits the files of an existing [Espanso installation](https://espanso.org/install/). Without Espanso it opens a sample workspace.
+- Kürzel is an independent project and is not affiliated with Espanso.
+
+What the app does, how it works and its limits are described in the [main README](https://github.com/maximilianfeix/kuerzel#readme).
+
+## License
+
+MIT

kuerzel-0.1.0/kuerzel/__init__.py

@@ -0,0 +1,3 @@
+"""Launcher for Kürzel, a desktop studio for Espanso snippets."""
+
+__version__ = "0.1.0"

kuerzel-0.1.0/kuerzel/__main__.py

@@ -0,0 +1,4 @@
+from kuerzel.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

kuerzel-0.1.0/kuerzel/cli.py

@@ -0,0 +1,210 @@
+"""Downloads the Kürzel desktop app for this computer and starts it.
+
+The app itself is an Electron program and far too large for a Python wheel,
+so this package stays tiny: it fetches the matching build from the project's
+GitHub release, checks it against the published SHA-256 checksum, keeps it in
+the user's cache folder and runs it from there.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import os
+import platform
+import shutil
+import stat
+import subprocess
+import sys
+import tempfile
+import urllib.parse
+import urllib.request
+from pathlib import Path
+
+from kuerzel import __version__
+
+REPOSITORY = "maximilianfeix/kuerzel"
+RELEASES = f"https://github.com/{REPOSITORY}/releases"
+CHECKSUMS = "SHA256SUMS.txt"
+# GitHub serves release files from these hosts after a redirect.
+ALLOWED_HOSTS = (
+    "github.com",
+    "objects.githubusercontent.com",
+    "release-assets.githubusercontent.com",
+)
+
+
+class LauncherError(Exception):
+    """A problem the user can act on; shown without a traceback."""
+
+
+def asset_name(version: str, system: str | None = None, machine: str | None = None) -> str:
+    """Returns the release file for a platform, or raises if there is none."""
+    system = (system or platform.system()).lower()
+    machine = (machine or platform.machine()).lower()
+    is_x64 = machine in ("x86_64", "amd64")
+    is_arm = machine in ("arm64", "aarch64")
+
+    if system == "windows" and is_x64:
+        return f"Kuerzel-{version}-windows-portable.exe"
+    if system == "darwin" and (is_x64 or is_arm):
+        return f"Kuerzel-{version}-macos-{'arm64' if is_arm else 'x64'}.dmg"
+    if system == "linux" and is_x64:
+        return f"Kuerzel-{version}-linux-x86_64.AppImage"
+    raise LauncherError(
+        f"There is no Kürzel build for {system} on {machine} yet.\n"
+        f"See {RELEASES} for the available downloads."
+    )
+
+
+def cache_dir() -> Path:
+    """The per-user folder where downloaded builds are kept."""
+    home = Path.home()
+    if sys.platform == "win32":
+        base = Path(os.environ.get("LOCALAPPDATA") or home / "AppData" / "Local")
+    elif sys.platform == "darwin":
+        base = home / "Library" / "Caches"
+    else:
+        base = Path(os.environ.get("XDG_CACHE_HOME") or home / ".cache")
+    return base / "kuerzel" / "app"
+
+
+def expected_checksum(listing: str, name: str) -> str:
+    """Finds a file's SHA-256 in the text of a `sha256sum` listing."""
+    for line in listing.splitlines():
+        parts = line.split()
+        if len(parts) == 2 and parts[1].lstrip("*") == name:
+            digest = parts[0].lower()
+            if len(digest) == 64 and all(c in "0123456789abcdef" for c in digest):
+                return digest
+    raise LauncherError(f"The release does not list a checksum for {name}.")
+
+
+def sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def _open(url: str):
+    if not url.startswith("https://"):
+        raise LauncherError("Refusing to download over an insecure connection.")
+    request = urllib.request.Request(url, headers={"User-Agent": f"kuerzel-launcher/{__version__}"})
+    try:
+        response = urllib.request.urlopen(request, timeout=60)  # noqa: S310 - https only, checked above
+    except OSError as error:
+        raise LauncherError(
+            f"Could not download {url}\n{error}\nYou can download the app by hand from {RELEASES}"
+        ) from error
+    host = urllib.parse.urlparse(response.geturl()).hostname or ""
+    if response.geturl().split(":", 1)[0] != "https" or host not in ALLOWED_HOSTS:
+        response.close()
+        raise LauncherError(f"The download was redirected to an unexpected address: {host}")
+    return response
+
+
+def download(url: str, target: Path, show_progress: bool) -> None:
+    with _open(url) as response, target.open("wb") as out:
+        total = int(response.headers.get("Content-Length") or 0)
+        megabytes = f" ({total // (1024 * 1024)} MB)" if total else ""
+        # A live percentage only makes sense on a terminal; in a log or a pipe
+        # it would print hundreds of lines, so a single line is written there.
+        live = show_progress and total > 0 and sys.stderr.isatty()
+        if show_progress and not live:
+            print(f"Downloading Kürzel{megabytes}...", file=sys.stderr)
+        done = 0
+        shown = -1
+        while chunk := response.read(256 * 1024):
+            out.write(chunk)
+            done += len(chunk)
+            percent = done * 100 // total if total else 0
+            if live and percent != shown:
+                shown = percent
+                print(f"\rDownloading Kürzel{megabytes} {percent:3d}%", end="", file=sys.stderr)
+    if live:
+        print(file=sys.stderr)
+
+
+def ensure_app(version: str = __version__, show_progress: bool = True) -> Path:
+    """Returns the path of the app for this version, downloading it if needed."""
+    name = asset_name(version)
+    folder = cache_dir()
+    target = folder / name
+    if target.is_file():
+        return target
+
+    base = f"{RELEASES}/download/v{version}"
+    with _open(f"{base}/{CHECKSUMS}") as response:
+        listing = response.read(1024 * 1024).decode("utf-8", "replace")
+    expected = expected_checksum(listing, name)
+
+    folder.mkdir(parents=True, exist_ok=True)
+    handle, temp_name = tempfile.mkstemp(dir=folder, suffix=".part")
+    os.close(handle)
+    temp = Path(temp_name)
+    try:
+        download(f"{base}/{name}", temp, show_progress)
+        actual = sha256(temp)
+        if actual != expected:
+            raise LauncherError(
+                "The downloaded file does not match its published checksum and was deleted.\n"
+                f"Expected {expected}\nGot      {actual}"
+            )
+        if sys.platform != "win32":
+            temp.chmod(temp.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+        temp.replace(target)
+    finally:
+        temp.unlink(missing_ok=True)
+
+    # Older versions are no longer needed once a newer one is in place.
+    for old in folder.iterdir():
+        if old.is_file() and old != target and old.name.startswith("Kuerzel-"):
+            old.unlink(missing_ok=True)
+    return target
+
+
+def launch(app: Path) -> None:
+    """Starts the app without tying it to this terminal."""
+    if sys.platform == "darwin":
+        # A disk image cannot be run in place: open it so the app can be
+        # dragged to Applications, as with a manual download.
+        subprocess.run(["open", str(app)], check=False)  # noqa: S603, S607
+        print("Drag Kürzel to Applications, then start it from there.", file=sys.stderr)
+        return
+    options: dict = {"stdin": subprocess.DEVNULL, "stdout": subprocess.DEVNULL, "stderr": subprocess.DEVNULL}
+    if sys.platform == "win32":
+        options["creationflags"] = subprocess.DETACHED_PROCESS | subprocess.CREATE_NEW_PROCESS_GROUP  # type: ignore[attr-defined]
+    else:
+        options["start_new_session"] = True
+    subprocess.Popen([str(app)], **options)  # noqa: S603 - a file we downloaded and verified
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="kuerzel",
+        description="Kürzel, a desktop studio for Espanso snippets. "
+        "Running this command downloads the app on first use and starts it.",
+    )
+    parser.add_argument("--version", action="version", version=f"kuerzel {__version__}")
+    parser.add_argument("--path", action="store_true", help="download if needed, print where the app is, and exit")
+    parser.add_argument("--remove", action="store_true", help="delete the downloaded app and exit")
+    args = parser.parse_args(argv)
+
+    try:
+        if args.remove:
+            shutil.rmtree(cache_dir(), ignore_errors=True)
+            print("Removed the downloaded app.")
+            return 0
+        app = ensure_app()
+        if args.path:
+            print(app)
+            return 0
+        launch(app)
+        return 0
+    except LauncherError as error:
+        print(error, file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        return 130

kuerzel-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "kuerzel"
+dynamic = ["version"]
+description = "Kürzel, a desktop studio for Espanso snippets. This package downloads and starts the app."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "Maxi" }]
+keywords = ["espanso", "text-expander", "snippets", "gui", "productivity"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Win32 (MS Windows)",
+  "Environment :: MacOS X",
+  "Environment :: X11 Applications",
+  "Intended Audience :: End Users/Desktop",
+  "Operating System :: Microsoft :: Windows",
+  "Operating System :: MacOS",
+  "Operating System :: POSIX :: Linux",
+  "Programming Language :: Python :: 3",
+  "Topic :: Text Processing",
+  "Topic :: Utilities",
+]
+
+[project.urls]
+Homepage = "https://github.com/maximilianfeix/kuerzel"
+Releases = "https://github.com/maximilianfeix/kuerzel/releases"
+Issues = "https://github.com/maximilianfeix/kuerzel/issues"
+Changelog = "https://github.com/maximilianfeix/kuerzel/blob/main/CHANGELOG.md"
+
+[project.scripts]
+kuerzel = "kuerzel.cli:main"
+
+[tool.hatch.version]
+path = "kuerzel/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["kuerzel"]
+
+[tool.hatch.build.targets.sdist]
+include = ["kuerzel", "tests", "README.md"]

kuerzel-0.1.0/tests/test_cli.py

@@ -0,0 +1,123 @@
+import hashlib
+import io
+import tempfile
+import unittest
+from pathlib import Path
+from unittest import mock
+
+from kuerzel import __version__, cli
+
+
+class AssetNameTests(unittest.TestCase):
+    def test_picks_the_build_for_each_platform(self):
+        self.assertEqual(cli.asset_name("1.2.3", "Windows", "AMD64"), "Kuerzel-1.2.3-windows-portable.exe")
+        self.assertEqual(cli.asset_name("1.2.3", "Darwin", "arm64"), "Kuerzel-1.2.3-macos-arm64.dmg")
+        self.assertEqual(cli.asset_name("1.2.3", "Darwin", "x86_64"), "Kuerzel-1.2.3-macos-x64.dmg")
+        self.assertEqual(cli.asset_name("1.2.3", "Linux", "x86_64"), "Kuerzel-1.2.3-linux-x86_64.AppImage")
+
+    def test_explains_when_there_is_no_build(self):
+        for system, machine in (("Linux", "aarch64"), ("Windows", "ARM64"), ("FreeBSD", "amd64")):
+            with self.assertRaises(cli.LauncherError) as caught:
+                cli.asset_name("1.2.3", system, machine)
+            self.assertIn("releases", str(caught.exception))
+
+
+class ChecksumTests(unittest.TestCase):
+    DIGEST = "a" * 64
+
+    def test_reads_plain_and_binary_mode_listings(self):
+        listing = f"{'b' * 64}  other.exe\n{self.DIGEST} *app.exe\n"
+        self.assertEqual(cli.expected_checksum(listing, "app.exe"), self.DIGEST)
+
+    def test_rejects_missing_and_malformed_entries(self):
+        for listing in ("", "nothex  app.exe\n", f"{self.DIGEST}  another.exe\n", f"{'z' * 64}  app.exe\n"):
+            with self.assertRaises(cli.LauncherError):
+                cli.expected_checksum(listing, "app.exe")
+
+    def test_hashes_a_file(self):
+        with tempfile.TemporaryDirectory() as folder:
+            path = Path(folder) / "file"
+            path.write_bytes(b"kuerzel")
+            self.assertEqual(cli.sha256(path), hashlib.sha256(b"kuerzel").hexdigest())
+
+
+class FakeResponse(io.BytesIO):
+    def __init__(self, data: bytes, url: str):
+        super().__init__(data)
+        self._url = url
+        self.headers = {"Content-Length": str(len(data))}
+
+    def geturl(self):
+        return self._url
+
+
+class EnsureAppTests(unittest.TestCase):
+    def setUp(self):
+        self.folder = tempfile.TemporaryDirectory()
+        self.addCleanup(self.folder.cleanup)
+        self.name = "Kuerzel-9.9.9-linux-x86_64.AppImage"
+        patches = [
+            mock.patch.object(cli, "cache_dir", return_value=Path(self.folder.name)),
+            mock.patch.object(cli, "asset_name", return_value=self.name),
+        ]
+        for patch in patches:
+            patch.start()
+            self.addCleanup(patch.stop)
+
+    def serve(self, payload: bytes, listed: bytes, host: str = "github.com"):
+        def opener(request, timeout=0):
+            url = request.full_url
+            body = f"{hashlib.sha256(listed).hexdigest()}  {self.name}\n".encode() if url.endswith(cli.CHECKSUMS) else payload
+            return FakeResponse(body, f"https://{host}/file")
+
+        return mock.patch("urllib.request.urlopen", side_effect=opener)
+
+    def test_downloads_verifies_and_reuses(self):
+        with self.serve(b"app", b"app") as opened:
+            path = cli.ensure_app("9.9.9", show_progress=False)
+            self.assertEqual(path.read_bytes(), b"app")
+            self.assertEqual(opened.call_count, 2)
+            cli.ensure_app("9.9.9", show_progress=False)
+            self.assertEqual(opened.call_count, 2)
+
+    def test_deletes_a_file_that_fails_its_checksum(self):
+        with self.serve(b"tampered", b"app"):
+            with self.assertRaises(cli.LauncherError) as caught:
+                cli.ensure_app("9.9.9", show_progress=False)
+        self.assertIn("checksum", str(caught.exception))
+        self.assertEqual(list(Path(self.folder.name).iterdir()), [])
+
+    def test_refuses_unexpected_hosts_and_plain_http(self):
+        with self.serve(b"app", b"app", host="evil.example"):
+            with self.assertRaises(cli.LauncherError):
+                cli.ensure_app("9.9.9", show_progress=False)
+        with self.assertRaises(cli.LauncherError):
+            cli._open("http://github.com/file")
+
+    def test_removes_older_builds(self):
+        old = Path(self.folder.name) / "Kuerzel-0.0.1-linux-x86_64.AppImage"
+        old.write_bytes(b"old")
+        with self.serve(b"app", b"app"):
+            cli.ensure_app("9.9.9", show_progress=False)
+        self.assertFalse(old.exists())
+
+
+class MainTests(unittest.TestCase):
+    def test_reports_problems_without_a_traceback(self):
+        with mock.patch.object(cli, "ensure_app", side_effect=cli.LauncherError("no build")):
+            with mock.patch("sys.stderr", new_callable=io.StringIO) as stderr:
+                self.assertEqual(cli.main([]), 1)
+        self.assertIn("no build", stderr.getvalue())
+
+    def test_prints_the_path(self):
+        with mock.patch.object(cli, "ensure_app", return_value=Path("/tmp/app")):
+            with mock.patch("sys.stdout", new_callable=io.StringIO) as stdout:
+                self.assertEqual(cli.main(["--path"]), 0)
+        self.assertIn("app", stdout.getvalue())
+
+    def test_version_matches_the_package(self):
+        self.assertRegex(__version__, r"^\d+\.\d+\.\d+$")
+
+
+if __name__ == "__main__":
+    unittest.main()