usage-cli 0.29.32__py3-none-any.whl

update_checker.py

@@ -0,0 +1,156 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright (C) 2026 lollapalooza <https://github.com/aqua5230>
+#
+# Part of "usage". Free software licensed under the GNU Affero General Public
+# License v3.0 only; see the LICENSE file for full terms and the warranty disclaimer.
+
+from __future__ import annotations
+
+import json
+import re
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from typing import Any
+
+GITHUB_RELEASES_API = "https://api.github.com/repos/aqua5230/usage/releases/latest"
+# A release payload is tens of KB; cap the read so a broken endpoint cannot make
+# us buffer an unbounded response.
+MAX_RESPONSE_BYTES = 4 * 1024 * 1024
+
+
+@dataclass(frozen=True, slots=True)
+class ReleaseInfo:
+    version: str
+    html_url: str
+    body: str
+
+
+@dataclass(frozen=True, slots=True)
+class ReleaseCheckResult:
+    release: ReleaseInfo | None
+    failed: bool = False
+
+
+def _parse_version(version: str) -> tuple[int, int, int, tuple[str, ...] | None] | None:
+    match = re.match(r"^(\d+)\.(\d+)\.(\d+)(.*)?$", version)
+    if match is None:
+        return None
+    suffix = match.group(4) or ""
+    prerelease: tuple[str, ...] | None = None
+    if suffix.startswith("-") or suffix.startswith("."):
+        prerelease = tuple(part for part in suffix[1:].split("+", 1)[0].split(".") if part)
+        if not prerelease:
+            return None
+    elif suffix and not suffix.startswith("+"):
+        return None
+    return (int(match.group(1)), int(match.group(2)), int(match.group(3)), prerelease)
+
+
+def compare_versions(a: str, b: str) -> int:
+    parsed_a = _parse_version(a)
+    parsed_b = _parse_version(b)
+    if parsed_a is None or parsed_b is None:
+        raise ValueError("versions must use MAJOR.MINOR.PATCH numeric format")
+    base_a = parsed_a[:3]
+    base_b = parsed_b[:3]
+    if base_a < base_b:
+        return -1
+    if base_a > base_b:
+        return 1
+    prerelease_a = parsed_a[3]
+    prerelease_b = parsed_b[3]
+    if prerelease_a is None and prerelease_b is None:
+        return 0
+    if prerelease_a is None:
+        return 1
+    if prerelease_b is None:
+        return -1
+    for part_a, part_b in zip(prerelease_a, prerelease_b, strict=False):
+        is_digit_a = part_a.isdigit()
+        is_digit_b = part_b.isdigit()
+        if is_digit_a and is_digit_b:
+            value_a = int(part_a)
+            value_b = int(part_b)
+            if value_a < value_b:
+                return -1
+            if value_a > value_b:
+                return 1
+            continue
+        if is_digit_a != is_digit_b:
+            return -1 if is_digit_a else 1
+        if part_a < part_b:
+            return -1
+        if part_a > part_b:
+            return 1
+    if len(prerelease_a) < len(prerelease_b):
+        return -1
+    if len(prerelease_a) > len(prerelease_b):
+        return 1
+    return 0
+
+
+def check_latest_release(current_version: str, *, timeout: float = 5.0) -> ReleaseInfo | None:
+    return check_latest_release_result(current_version, timeout=timeout).release
+
+
+def check_latest_release_result(
+    current_version: str,
+    *,
+    timeout: float = 5.0,
+) -> ReleaseCheckResult:
+    if _parse_version(current_version) is None:
+        return ReleaseCheckResult(None)
+
+    request = urllib.request.Request(
+        GITHUB_RELEASES_API,
+        headers={
+            "Accept": "application/vnd.github+json",
+            "User-Agent": f"usage/{current_version}",
+        },
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            raw = response.read(MAX_RESPONSE_BYTES + 1)
+        if len(raw) > MAX_RESPONSE_BYTES:
+            raise ValueError("release response exceeds the size limit")
+        payload = json.loads(raw.decode("utf-8"))
+    except (
+        OSError,
+        UnicodeDecodeError,
+        ValueError,
+        urllib.error.URLError,
+        urllib.error.HTTPError,
+    ):
+        return ReleaseCheckResult(None, failed=True)
+
+    release = _release_from_payload(payload)
+    if release is None:
+        return ReleaseCheckResult(None)
+    try:
+        if compare_versions(current_version, release.version) >= 0:
+            return ReleaseCheckResult(None)
+    except ValueError:
+        return ReleaseCheckResult(None)
+    return ReleaseCheckResult(release)
+
+
+def _release_from_payload(payload: Any) -> ReleaseInfo | None:
+    if not isinstance(payload, dict):
+        return None
+
+    tag_name = payload.get("tag_name")
+    html_url = payload.get("html_url")
+    body = payload.get("body", "")
+    if not isinstance(tag_name, str) or not isinstance(html_url, str):
+        return None
+    # The URL is handed to webbrowser.open(); anything but https is not a release page.
+    if not html_url.startswith("https://"):
+        return None
+    if not isinstance(body, str):
+        body = ""
+
+    version = tag_name.removeprefix("v")
+    if _parse_version(version) is None:
+        return None
+    return ReleaseInfo(version=version, html_url=html_url, body=body)

update_gate.py

@@ -0,0 +1,66 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright (C) 2026 lollapalooza <https://github.com/aqua5230>
+#
+# Part of "usage". Free software licensed under the GNU Affero General Public
+# License v3.0 only; see the LICENSE file for full terms and the warranty disclaimer.
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+import update_checker
+
+AUTO_CHECK_TTL_SECONDS = 24 * 60 * 60
+UPDATE_DISMISS_SECONDS = 24 * 3600
+
+
+def dismissed_recently(prefs: dict[str, Any]) -> bool:
+    dismissed_at = prefs.get("update_dismissed_at")
+    if isinstance(dismissed_at, int | float):
+        return (time.time() - float(dismissed_at)) < UPDATE_DISMISS_SECONDS
+    return False
+
+
+def auto_check_is_due(prefs: dict[str, Any]) -> bool:
+    cached = prefs.get("last_update_check")
+    checked_at = cached.get("checked_at") if isinstance(cached, dict) else None
+    if not isinstance(checked_at, int | float):
+        return True
+    return (time.time() - float(checked_at)) >= AUTO_CHECK_TTL_SECONDS
+
+
+def stale_cache_reset(prefs: dict[str, Any], current_version: str) -> dict[str, Any] | None:
+    cached = prefs.get("last_update_check")
+    if (
+        isinstance(cached, dict)
+        and isinstance(cached.get("latest_version"), str)
+        and cached.get("current_version") != current_version
+        and update_checker.compare_versions(current_version, cached["latest_version"]) >= 0
+    ):
+        return {
+            **cached,
+            "current_version": current_version,
+            "latest_version": current_version,
+        }
+    return None
+
+
+def build_check_cache_entry(
+    current_version: str,
+    release: update_checker.ReleaseInfo | None,
+) -> dict[str, Any]:
+    return {
+        "checked_at": time.time(),
+        "current_version": current_version,
+        "latest_version": release.version if release else current_version,
+        "release_url": release.html_url if release else None,
+    }
+
+
+def resolve_alert_choice(result_code: int, release_version: str) -> tuple[str, dict[str, str]]:
+    if result_code == 1000:
+        return ("open", {})
+    if result_code == 1002:
+        return ("skip", {"update_skipped_version": release_version})
+    return ("dismiss", {})

update_release_notes.py

@@ -0,0 +1,49 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright (C) 2026 lollapalooza <https://github.com/aqua5230>
+#
+# Part of "usage". Free software licensed under the GNU Affero General Public
+# License v3.0 only; see the LICENSE file for full terms and the warranty disclaimer.
+
+import re
+
+_HEADING_RE = re.compile(r"^[ \t]{0,3}#{1,6}[ \t]+(.*?)[ \t]*#*[ \t]*$")
+_BULLET_RE = re.compile(r"^([ \t]*)[-*][ \t]+(.*)$")
+_LINK_RE = re.compile(r"\[([^\]]+)\]\([^)]+\)")
+_STRONG_RE = re.compile(r"\*\*(.+?)\*\*|__(.+?)__")
+_INLINE_CODE_RE = re.compile(r"`([^`\n]+)`")
+
+
+def _format_inline_markdown(text: str) -> str:
+    text = _LINK_RE.sub(r"\1", text)
+    text = _STRONG_RE.sub(lambda match: match.group(1) or match.group(2), text)
+    return _INLINE_CODE_RE.sub(r"\1", text)
+
+
+def format_release_notes(body: str, limit: int) -> str:
+    """Convert GitHub Release Markdown into compact plain text for an alert."""
+    if not isinstance(body, str) or limit <= 0:
+        return ""
+
+    lines: list[str] = []
+    for line in body.replace("\r\n", "\n").replace("\r", "\n").split("\n"):
+        heading = _HEADING_RE.match(line)
+        if heading:
+            if lines and lines[-1]:
+                lines.append("")
+            lines.append(_format_inline_markdown(heading.group(1)))
+            lines.append("")
+            continue
+
+        line = _format_inline_markdown(line)
+        lines.append(_BULLET_RE.sub(r"\1• \2", line))
+
+    text = re.sub(r"\n{3,}", "\n\n", "\n".join(lines)).strip()
+    if len(text) <= limit:
+        return text
+    if limit == 1:
+        return "…"
+
+    boundary = max(text.rfind(" ", 0, limit), text.rfind("\n", 0, limit))
+    if boundary < 0:
+        return "…"
+    return f"{text[:boundary].rstrip()}…"