battery-tray 1.0.0__tar.gz

battery_tray-1.0.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+.ipynb_checkpoints/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.venv/
+build/
+dist/
+docs/_build/
+.claude/settings.local.json

battery_tray-1.0.0/LICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+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 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.
+
+For more information, please refer to <https://unlicense.org>

battery_tray-1.0.0/PKG-INFO

@@ -0,0 +1,61 @@
+Metadata-Version: 2.4
+Name: battery-tray
+Version: 1.0.0
+Summary: A system-tray battery monitor with a battery-selection window.
+Project-URL: Homepage, https://github.com/sevaht/battery-tray
+Project-URL: Source, https://github.com/sevaht/battery-tray
+Project-URL: Issues, https://github.com/sevaht/battery-tray/issues
+Author-email: Jacob McIntosh <nacitar.sevaht@gmail.com>
+License-Expression: Unlicense
+License-File: LICENSE
+Keywords: battery,linux,monitor,power,tkinter,tray
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: pillow>=12.2.0
+Requires-Dist: platformdirs>=4.10.0
+Requires-Dist: sevaht-gui
+Description-Content-Type: text/markdown
+
+# battery-tray
+
+A small Linux system-tray battery monitor, built on
+[sevaht-gui](https://github.com/sevaht/sevaht-gui).
+
+- A tray icon shows the selected battery's charge as a colour-graded battery
+  glyph (green → red) with charge/charging state in the tooltip.
+- Left-click (or the tray menu's **Configure…**) opens a window to pick which
+  battery to monitor and set the refresh interval; both are saved under
+  `sevaht/battery-tray`.
+- Desktop notifications (via `notify-send`) fire when the charge level or
+  charging state changes.
+- If no system tray is available, the window simply runs on its own.
+
+## Running
+
+```console
+$ battery-tray            # start in the tray (window hidden)
+$ battery-tray --show     # start with the window open
+```
+
+## Configuring from the CLI
+
+These update the saved config and exit (handy for scripts/keybinds); the
+running app picks the same values up from config:
+
+```console
+$ battery-tray --list-batteries       # show detected batteries and exit
+$ battery-tray --battery BAT0         # set the monitored battery by name
+$ battery-tray --select-battery       # choose interactively from a list
+$ battery-tray --set-poll-seconds 10  # set the refresh interval (1-3600s)
+```
+
+Reads battery state from `/sys/class/power_supply` (Linux only).

battery_tray-1.0.0/README.md

@@ -0,0 +1,34 @@
+# battery-tray
+
+A small Linux system-tray battery monitor, built on
+[sevaht-gui](https://github.com/sevaht/sevaht-gui).
+
+- A tray icon shows the selected battery's charge as a colour-graded battery
+  glyph (green → red) with charge/charging state in the tooltip.
+- Left-click (or the tray menu's **Configure…**) opens a window to pick which
+  battery to monitor and set the refresh interval; both are saved under
+  `sevaht/battery-tray`.
+- Desktop notifications (via `notify-send`) fire when the charge level or
+  charging state changes.
+- If no system tray is available, the window simply runs on its own.
+
+## Running
+
+```console
+$ battery-tray            # start in the tray (window hidden)
+$ battery-tray --show     # start with the window open
+```
+
+## Configuring from the CLI
+
+These update the saved config and exit (handy for scripts/keybinds); the
+running app picks the same values up from config:
+
+```console
+$ battery-tray --list-batteries       # show detected batteries and exit
+$ battery-tray --battery BAT0         # set the monitored battery by name
+$ battery-tray --select-battery       # choose interactively from a list
+$ battery-tray --set-poll-seconds 10  # set the refresh interval (1-3600s)
+```
+
+Reads battery state from `/sys/class/power_supply` (Linux only).

battery_tray-1.0.0/pyproject.toml

@@ -0,0 +1,94 @@
+[build-system]
+requires = ["hatchling (>=1.29.0,<2.0.0)", "hatch-vcs (>=0.5.0,<1.0.0)"]
+build-backend = "hatchling.build"
+
+[project]
+name = "battery-tray"
+dynamic = ["version"]
+description = "A system-tray battery monitor with a battery-selection window."
+authors = [
+    {name = "Jacob McIntosh", email = "nacitar.sevaht@gmail.com"}
+]
+readme = "README.md"
+license = "Unlicense"
+requires-python = ">=3.12"
+keywords = ["battery", "tray", "monitor", "power", "tkinter", "linux"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: End Users/Desktop",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Utilities",
+    "Typing :: Typed",
+]
+dependencies = [
+    "Pillow>=12.2.0",
+    "sevaht-gui",
+    "platformdirs>=4.10.0",
+]
+
+[project.scripts]
+battery-tray = "battery_tray.__main__:main"
+
+[dependency-groups]
+dev = [
+    "black (>=26.3.1,<27.0.0)",
+    "build (>=1.4.2,<2.0.0)",
+    "mypy (>=1.20.0,<2.0.0)",
+    "pytest (>=9.0.2,<10.0.0)",
+    "ruff (>=0.15.8,<0.16.0)",
+    "twine (>=6.2.0,<7.0.0)",
+    "vulture (>=2.14,<3.0.0)",
+]
+
+[project.urls]
+Homepage = "https://github.com/sevaht/battery-tray"
+Source = "https://github.com/sevaht/battery-tray"
+Issues = "https://github.com/sevaht/battery-tray/issues"
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.version.raw-options]
+fallback_version = "0.0.0"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/battery_tray"]
+
+[tool.hatch.build.targets.sdist]
+include = ["/src", "/tests", "/LICENSE"]
+
+[tool.black]
+line-length = 79
+skip-magic-trailing-comma = true
+
+[tool.mypy]
+strict = true
+exclude = ["^docs/", "^dist/"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 79
+
+[tool.ruff.lint]
+extend-ignore = ["COM812", "COM819", "E203", "E501", "TD003"]
+select = [
+    "A", "ANN", "ARG", "ASYNC", "B", "BLE", "C4", "C90", "COM",
+    "DTZ", "E", "EM", "ERA", "F", "FA", "FLY", "FURB", "I",
+    "ISC", "LOG", "N", "PERF", "PGH", "PIE", "PLR", "PLW", "PTH",
+    "Q", "RET", "RSE", "RUF", "S", "SIM", "TC", "TCH", "TD",
+    "TID", "TRY", "UP"
+]
+
+[tool.ruff.lint.per-file-ignores]
+"checks" = ["S603"]
+"tests/**/*" = ["PLR2004", "S101"]
+
+[tool.vulture]
+min_confidence = 70

battery_tray-1.0.0/src/battery_tray/__init__.py

@@ -0,0 +1,33 @@
+"""A system-tray battery monitor built on sevaht-gui.
+
+Attributes:
+    __version__: The installed distribution version.
+"""
+
+from __future__ import annotations
+
+import importlib.metadata
+from functools import cache
+from typing import TYPE_CHECKING
+
+from platformdirs import PlatformDirs
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+__version__ = importlib.metadata.version(__package__)
+
+APP_NAME = "battery-tray"
+APP_AUTHOR = "sevaht"
+CONFIG_FILE_NAME = "config.json"
+
+
+@cache
+def user_config_path() -> Path:
+    """Return the per-user config directory (``<author>/<appname>``)."""
+    path = PlatformDirs(APP_NAME, appauthor=APP_AUTHOR).user_config_path
+    # platformdirs omits appauthor from the path on non-Windows platforms;
+    # insert it so all platforms use <author>/<appname>.
+    if path.parent.name != APP_AUTHOR:
+        path = path.parent / APP_AUTHOR / APP_NAME
+    return path

battery_tray-1.0.0/src/battery_tray/__main__.py

@@ -0,0 +1,205 @@
+"""Command-line entry point for battery-tray."""
+
+from __future__ import annotations
+
+import argparse
+import logging
+from typing import TYPE_CHECKING
+
+from . import CONFIG_FILE_NAME, user_config_path
+from .battery import list_batteries, read_battery
+from .config import (
+    MAX_POLL_SECONDS,
+    MIN_POLL_SECONDS,
+    load_config,
+    save_config,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+    from pathlib import Path
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="battery-tray",
+        description="Monitor battery status from the system tray.",
+    )
+
+    config_group = parser.add_argument_group(
+        "config mode",
+        "Update saved settings and exit."
+        " Cannot be combined with run mode arguments.",
+    )
+    config_group.add_argument(
+        "--list-batteries",
+        action="store_true",
+        help="List available batteries and exit.",
+    )
+    config_group.add_argument(
+        "--battery",
+        metavar="NAME",
+        help="Save the battery to monitor by name and exit.",
+    )
+    config_group.add_argument(
+        "--select-battery",
+        action="store_true",
+        help="Interactively choose a battery to monitor, save it, and exit.",
+    )
+    config_group.add_argument(
+        "--set-poll-seconds",
+        type=float,
+        metavar="SECONDS",
+        help="Save the refresh interval"
+        f" ({MIN_POLL_SECONDS:g}-{MAX_POLL_SECONDS:g}s) and exit.",
+    )
+
+    run_group = parser.add_argument_group(
+        "run mode",
+        "Start the tray. Cannot be combined with config mode arguments.",
+    )
+    run_group.add_argument(
+        "--show",
+        action="store_true",
+        help="Show the window at startup instead of starting tray-only.",
+    )
+
+    verbosity = parser.add_mutually_exclusive_group()
+    verbosity.add_argument(
+        "-v", "--verbose", action="store_true", help="Enable debug logging."
+    )
+    verbosity.add_argument(
+        "-q", "--quiet", action="store_true", help="Only log warnings."
+    )
+    return parser
+
+
+def _configure_logging(args: argparse.Namespace) -> None:
+    level = logging.INFO
+    if args.verbose:
+        level = logging.DEBUG
+    elif args.quiet:
+        level = logging.WARNING
+    logging.basicConfig(level=level, format="%(levelname)s: %(message)s")
+
+
+def _battery_label(name: str) -> str:
+    status = read_battery(name)
+    if status is None:
+        return f"{name} (unavailable)"
+    state = "charging" if status.charging else "discharging"
+    return f"{name} - {status.capacity}% ({state})"
+
+
+def _print_batteries() -> int:
+    batteries = list_batteries()
+    if not batteries:
+        print("No batteries detected.")
+        return 0
+    for name in batteries:
+        print(_battery_label(name))
+    return 0
+
+
+def _save_battery(name: str, config_path: Path) -> int:
+    config = load_config(config_path)
+    config.battery = name
+    save_config(config_path, config)
+    note = "" if name in list_batteries() else " (not currently detected)"
+    print(f"Battery set to {name}{note}.")
+    return 0
+
+
+def _select_and_save_battery(config_path: Path) -> int:
+    batteries = list_batteries()
+    if not batteries:
+        print("No batteries detected.")
+        return 1
+    print("Available batteries:")
+    for menu_number, name in enumerate(batteries, start=1):
+        print(f"  {menu_number}) {_battery_label(name)}")
+    while True:
+        try:
+            choice = input("Select battery number (blank to cancel): ").strip()
+        except (KeyboardInterrupt, EOFError):
+            print()
+            return 1
+        if choice == "":
+            print("No battery selected.")
+            return 1
+        if choice.isdigit() and 1 <= int(choice) <= len(batteries):
+            return _save_battery(batteries[int(choice) - 1], config_path)
+        print("Invalid selection.")
+
+
+def _save_poll_seconds(
+    seconds: float, parser: argparse.ArgumentParser, config_path: Path
+) -> int:
+    if not (MIN_POLL_SECONDS <= seconds <= MAX_POLL_SECONDS):
+        parser.error(
+            "--set-poll-seconds must be between"
+            f" {MIN_POLL_SECONDS:g} and {MAX_POLL_SECONDS:g}"
+        )
+    config = load_config(config_path)
+    config.poll_seconds = seconds
+    save_config(config_path, config)
+    print(f"Refresh interval set to {seconds:g}s.")
+    return 0
+
+
+def _validate_mode_combination(
+    args: argparse.Namespace, parser: argparse.ArgumentParser
+) -> None:
+    config_flags = [
+        label
+        for active, label in (
+            (args.list_batteries, "--list-batteries"),
+            (args.battery is not None, "--battery"),
+            (args.select_battery, "--select-battery"),
+            (args.set_poll_seconds is not None, "--set-poll-seconds"),
+        )
+        if active
+    ]
+    if len(config_flags) > 1:
+        parser.error(
+            f"these arguments cannot be combined: {', '.join(config_flags)}"
+        )
+    if config_flags and args.show:
+        parser.error(
+            f"config argument {config_flags[0]} cannot be combined with --show"
+        )
+
+
+def _run_config_mode(
+    args: argparse.Namespace,
+    parser: argparse.ArgumentParser,
+    config_path: Path,
+) -> int | None:
+    """Handle a config-mode argument, or return None if none is active."""
+    if args.list_batteries:
+        return _print_batteries()
+    if args.select_battery:
+        return _select_and_save_battery(config_path)
+    if args.battery is not None:
+        return _save_battery(args.battery, config_path)
+    if args.set_poll_seconds is not None:
+        return _save_poll_seconds(args.set_poll_seconds, parser, config_path)
+    return None
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    _configure_logging(args)
+
+    config_path = user_config_path() / CONFIG_FILE_NAME
+    _validate_mode_combination(args, parser)
+
+    config_result = _run_config_mode(args, parser, config_path)
+    if config_result is not None:
+        return config_result
+
+    # Imported lazily so config mode does not require a display / sevaht-gui.
+    from .app import BatteryTray
+
+    return BatteryTray(config_path=config_path).run(start_hidden=not args.show)

battery_tray-1.0.0/src/battery_tray/app.py

@@ -0,0 +1,167 @@
+"""Wires the tray icon, selection window, and battery polling together."""
+
+from __future__ import annotations
+
+import contextlib
+import logging
+from tkinter import TclError
+from typing import TYPE_CHECKING
+
+from sevaht_gui import TkApp
+
+from . import APP_NAME, CONFIG_FILE_NAME, user_config_path
+from .battery import list_batteries, read_battery, status_lines
+from .config import clamp_poll_seconds, load_config, save_config
+from .render import IconStyle, battery_renderer
+from .window import BatterySelectorWindow
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+    from pathlib import Path
+
+    from PIL import Image
+
+    from .battery import BatteryStatus
+
+logger = logging.getLogger(__name__)
+
+# Charge buckets (every 5%) at which the icon is re-rendered; finer changes do
+# not visibly alter the icon.
+_ICON_BUCKET = 5
+
+
+class BatteryTray:
+    def __init__(
+        self,
+        config_path: Path | None = None,
+        *,
+        style: IconStyle | None = None,
+    ) -> None:
+        self.config_path = config_path or user_config_path() / CONFIG_FILE_NAME
+        self.style = style or IconStyle()
+        self._config = load_config(self.config_path)
+        self.poll_ms = int(self._config.poll_seconds * 1000)
+
+        self._batteries = list_batteries()
+        self._selected = self._initial_selection()
+        self._status: BatteryStatus | None = (
+            read_battery(self._selected) if self._selected else None
+        )
+        self._icon_key = self._current_icon_key()
+        self._notified_level = self._status.level if self._status else None
+        self._notified_charging = (
+            self._status.charging if self._status else None
+        )
+        self._poll_after: str | None = None
+
+        # TkApp defaults handle theme, centering/position, quit confirmation,
+        # the window icon (matched to the tray icon), and window-close behavior.
+        self.app = TkApp()
+        self.tray_icon = self.app.create_tray_icon(
+            APP_NAME,
+            self._tooltip(),
+            self._render(),
+            activate_label="Configure...",
+        )
+        self.window = BatterySelectorWindow(
+            self.app,
+            on_select=self._on_select,
+            on_poll_change=self._on_poll_change,
+            has_tray=self.app.has_tray,
+        )
+        self.window.set_batteries(self._batteries, self._selected)
+        self.window.set_poll_seconds(self._config.poll_seconds)
+        self.window.set_status(self._status)
+
+    def _initial_selection(self) -> str | None:
+        saved = self._config.battery
+        if saved is not None and saved in self._batteries:
+            return saved
+        return self._batteries[0] if self._batteries else None
+
+    def _current_icon_key(self) -> tuple[int, bool] | None:
+        if self._status is None:
+            return None
+        return (self._status.capacity // _ICON_BUCKET, self._status.charging)
+
+    def _render(self) -> Callable[[int], Image.Image]:
+        percent = self._status.capacity if self._status else 0
+        connected = self._status.charging if self._status else False
+        return battery_renderer(percent, connected=connected, style=self.style)
+
+    def _tooltip(self) -> str:
+        if self._status is None:
+            return "Battery Tray\nNo battery"
+        # First line is the header; the rest render as the tooltip body
+        # (multiline where the tray host supports it).
+        return f"{self._status.name}\n" + "\n".join(status_lines(self._status))
+
+    def _on_select(self, name: str) -> None:
+        self._selected = name
+        self._config.battery = name
+        save_config(self.config_path, self._config)
+        self._refresh()
+
+    def _on_poll_change(self, seconds: float) -> None:
+        seconds = clamp_poll_seconds(seconds)
+        self.poll_ms = int(seconds * 1000)
+        self._config.poll_seconds = seconds
+        save_config(self.config_path, self._config)
+        self._schedule_poll()
+
+    def _refresh(self) -> None:
+        # Runs on the UI thread (poll timer or a window callback).
+        batteries = list_batteries()
+        if batteries != self._batteries:
+            self._batteries = batteries
+            if self._selected not in batteries:
+                self._selected = batteries[0] if batteries else None
+            self.window.set_batteries(batteries, self._selected)
+        self._status = read_battery(self._selected) if self._selected else None
+        self._apply_status()
+        self.window.set_status(self._status)
+        self._maybe_notify()
+
+    def _apply_status(self) -> None:
+        # Push the current status to the tray tooltip and to both the tray and
+        # window icons (set_app_icon keeps them in sync).
+        if self.tray_icon is not None:
+            self.tray_icon.title = self._tooltip()
+        key = self._current_icon_key()
+        if key != self._icon_key:
+            self.app.set_app_icon(self._render())
+            self._icon_key = key
+
+    def _maybe_notify(self) -> None:
+        status = self._status
+        if status is None:
+            return
+        if (
+            status.level == self._notified_level
+            and status.charging == self._notified_charging
+        ):
+            return
+        # app.notify uses the tray when present and falls back to a standalone
+        # notifier otherwise -- no need to handle the no-tray case here.
+        self.app.notify(
+            f"Battery - {status.level.name.title()}",
+            "\n".join(status_lines(status)),
+            icon=status.level.value,
+        )
+        self._notified_level = status.level
+        self._notified_charging = status.charging
+
+    def _schedule_poll(self) -> None:
+        if self._poll_after is not None:
+            with contextlib.suppress(TclError):
+                self.app.root.after_cancel(self._poll_after)
+        self._poll_after = self.app.root.after(self.poll_ms, self._poll)
+
+    def _poll(self) -> None:
+        self._refresh()
+        self._poll_after = self.app.root.after(self.poll_ms, self._poll)
+
+    def run(self, *, start_hidden: bool = True) -> int:
+        self._schedule_poll()
+        self.app.run(self.tray_icon, start_hidden=start_hidden)
+        return 0

battery_tray-1.0.0/src/battery_tray/battery.py

@@ -0,0 +1,137 @@
+"""Reading battery state from the Linux ``/sys/class/power_supply`` tree."""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from datetime import timedelta
+from enum import StrEnum
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+POWER_SUPPLY_ROOT = Path("/sys/class/power_supply")
+
+# Above this charge, a battery reporting "Not charging" (e.g. a charge-limit
+# threshold reached) is treated as on AC rather than discharging.
+_NOT_CHARGING_FULL_PERCENT = 75
+
+# Lower bounds (exclusive) for each coarse charge level.
+_HIGH_MIN_PERCENT = 90
+_GOOD_MIN_PERCENT = 50
+_LOW_MIN_PERCENT = 10
+
+
+class BatteryLevel(StrEnum):
+    """Coarse charge level, mapped to a freedesktop icon name for notices."""
+
+    HIGH = "battery-full"
+    GOOD = "battery-good"
+    LOW = "battery-low"
+    CAUTION = "battery-caution"
+
+    @classmethod
+    def for_capacity(cls, capacity: int) -> BatteryLevel:
+        if capacity > _HIGH_MIN_PERCENT:
+            return cls.HIGH
+        if capacity > _GOOD_MIN_PERCENT:
+            return cls.GOOD
+        if capacity > _LOW_MIN_PERCENT:
+            return cls.LOW
+        return cls.CAUTION
+
+
+@dataclass(frozen=True, kw_only=True)
+class BatteryStatus:
+    name: str
+    capacity: int
+    charging: bool
+    status: str
+    remaining: timedelta
+
+    @property
+    def level(self) -> BatteryLevel:
+        return BatteryLevel.for_capacity(self.capacity)
+
+
+def _clamp_percent(percent: int) -> int:
+    return max(0, min(percent, 100))
+
+
+def _read_text(path: Path) -> str | None:
+    try:
+        return path.read_text(encoding="utf-8").strip()
+    except OSError:
+        return None
+
+
+def _read_int(path: Path) -> int | None:
+    text = _read_text(path)
+    if text is None:
+        return None
+    try:
+        return int(text)
+    except ValueError:
+        return None
+
+
+def list_batteries(root: Path = POWER_SUPPLY_ROOT) -> list[str]:
+    """Return the names of power supplies of type ``Battery``, sorted."""
+    if not root.is_dir():
+        return []
+    return [
+        entry.name
+        for entry in sorted(root.iterdir())
+        if _read_text(entry / "type") == "Battery"
+    ]
+
+
+def _time_remaining(base: Path) -> timedelta:
+    # Prefer energy/power (µWh / µW); fall back to charge/current (µAh / µA).
+    for amount_name, rate_name in (
+        ("energy_now", "power_now"),
+        ("charge_now", "current_now"),
+    ):
+        amount = _read_int(base / amount_name)
+        rate = _read_int(base / rate_name)
+        if amount is not None and rate:
+            return timedelta(hours=amount / rate)
+    return timedelta(0)
+
+
+def read_battery(
+    name: str, *, root: Path = POWER_SUPPLY_ROOT
+) -> BatteryStatus | None:
+    """Read the current status of battery ``name``, or None if unavailable."""
+    base = root / name
+    capacity = _read_int(base / "capacity")
+    if capacity is None:
+        return None
+    capacity = _clamp_percent(capacity)
+    status = _read_text(base / "status") or "Unknown"
+    charging = status in {"Charging", "Full"} or (
+        status == "Not charging" and capacity > _NOT_CHARGING_FULL_PERCENT
+    )
+    # Truncate to whole minutes: it is the granularity we display and makes
+    # change-detection stable across polls.
+    remaining = timedelta(minutes=_time_remaining(base).total_seconds() // 60)
+    return BatteryStatus(
+        name=name,
+        capacity=capacity,
+        charging=charging,
+        status=status,
+        remaining=remaining,
+    )
+
+
+def status_lines(status: BatteryStatus) -> list[str]:
+    """Human-readable status lines (tooltip / notification body)."""
+    lines = [
+        f"Charge: {status.capacity}%",
+        f"Power: {'' if status.charging else 'dis'}connected",
+    ]
+    total_minutes = int(status.remaining.total_seconds() // 60)
+    if total_minutes:
+        hours, minutes = divmod(total_minutes, 60)
+        lines.append(f"Life: {f'{hours}h ' if hours else ''}{minutes}m")
+    return lines

battery_tray-1.0.0/src/battery_tray/config.py

@@ -0,0 +1,65 @@
+"""Persisting battery-tray settings to a small JSON config file."""
+
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_POLL_SECONDS = 5.0
+MIN_POLL_SECONDS = 1.0
+MAX_POLL_SECONDS = 3600.0
+
+
+def clamp_poll_seconds(seconds: float) -> float:
+    return max(MIN_POLL_SECONDS, min(seconds, MAX_POLL_SECONDS))
+
+
+@dataclass
+class Config:
+    battery: str | None = None
+    poll_seconds: float = DEFAULT_POLL_SECONDS
+
+
+def load_config(config_path: Path) -> Config:
+    """Load settings, falling back to defaults for anything missing/invalid."""
+    try:
+        data = json.loads(config_path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return Config()
+    if not isinstance(data, dict):
+        return Config()
+    battery = data.get("battery")
+    if not isinstance(battery, str):
+        battery = None
+    poll = data.get("poll_seconds")
+    poll_seconds = (
+        clamp_poll_seconds(float(poll))
+        if isinstance(poll, (int, float)) and not isinstance(poll, bool)
+        else DEFAULT_POLL_SECONDS
+    )
+    return Config(battery=battery, poll_seconds=poll_seconds)
+
+
+def save_config(config_path: Path, config: Config) -> None:
+    """Persist settings, creating the config directory if needed."""
+    try:
+        config_path.parent.mkdir(parents=True, exist_ok=True)
+        config_path.write_text(
+            json.dumps(
+                {
+                    "battery": config.battery,
+                    "poll_seconds": config.poll_seconds,
+                },
+                indent=2,
+            ),
+            encoding="utf-8",
+        )
+    except OSError:
+        logger.warning("Could not save config", exc_info=True)

battery_tray-1.0.0/src/battery_tray/render.py

@@ -0,0 +1,162 @@
+"""Draws the battery tray/window icon with PIL.
+
+The icon is a battery outline (optionally with a nub) filled from the bottom in
+proportion to the charge, colored on a green-to-red gradient. It renders at any
+requested square size so the tray host can scale it cleanly.
+"""
+
+from __future__ import annotations
+
+import colorsys
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from PIL import Image, ImageDraw
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+_FULL_PERCENT = 100
+
+
+def _clamp_percent(percent: int) -> int:
+    return max(0, min(percent, _FULL_PERCENT))
+
+
+def power_gradient_color(percent: int) -> tuple[int, int, int]:
+    """Green (100%) to red (0%) through yellow/orange, as an RGB tuple."""
+    percent = _clamp_percent(percent)
+    # Hue 120deg (green) at full, 0deg (red) at empty.
+    hue = (percent / _FULL_PERCENT) * 120 / 360
+    red, green, blue = colorsys.hsv_to_rgb(hue, 1.0, 1.0)
+    return (int(red * 255), int(green * 255), int(blue * 255))
+
+
+@dataclass(kw_only=True)
+class IconStyle:
+    show_nub: bool = True
+    rounded: bool = True
+    connected_border_color: str = "rgb(211,215,207)"
+    disconnected_border_color: str = "rgb(255,255,0)"
+    gap_units: int = 1
+
+
+@dataclass(kw_only=True)
+class _Rectangle:
+    left: int = 0
+    top: int = 0
+    right: int = 0
+    bottom: int = 0
+
+    @property
+    def components(self) -> list[int]:
+        return [self.left, self.top, self.right - 1, self.bottom - 1]
+
+    @property
+    def height(self) -> int:
+        return abs(self.bottom - self.top)
+
+    def offset(self, *, top: int = 0) -> _Rectangle:
+        return _Rectangle(
+            left=self.left,
+            top=self.top + top,
+            right=self.right,
+            bottom=self.bottom,
+        )
+
+    def offset_edges(self, amount: int) -> _Rectangle:
+        return _Rectangle(
+            left=self.left + amount,
+            top=self.top + amount,
+            right=self.right - amount,
+            bottom=self.bottom - amount,
+        )
+
+    def draw(
+        self,
+        draw: ImageDraw.ImageDraw,
+        *,
+        radius: int = 0,
+        width: int = 1,
+        fill: str | tuple[int, int, int] | None = None,
+        outline: str | tuple[int, int, int] | None = None,
+    ) -> None:
+        # Skip empty or inverted rectangles (can occur at degenerate sizes).
+        if self.right <= self.left or self.bottom <= self.top:
+            return
+        if radius:
+            draw.rounded_rectangle(
+                self.components,
+                radius=radius,
+                fill=fill,
+                outline=outline,
+                width=width,
+            )
+        else:
+            draw.rectangle(
+                self.components, fill=fill, outline=outline, width=width
+            )
+
+
+def render_battery(
+    size: int, percent: int, *, connected: bool, style: IconStyle
+) -> Image.Image:
+    """Render the battery icon at ``size`` x ``size`` pixels."""
+    size = max(1, size)
+    percent = _clamp_percent(percent)
+    image = Image.new("RGBA", (size, size), (0, 0, 0, 0))
+    draw = ImageDraw.Draw(image)
+
+    unit = max(1, size // 16)
+    border_width = unit * 2
+    body_width = (size * 3) // 4
+    padding = (size - body_width) // 2
+    border_color = (
+        style.connected_border_color
+        if connected
+        else style.disconnected_border_color
+    )
+
+    border = _Rectangle(
+        left=padding, right=padding + body_width, top=0, bottom=size
+    )
+    if style.show_nub:
+        nub_width = border_width * 2
+        nub_padding = (size - nub_width) // 2
+        nub = _Rectangle(
+            left=nub_padding,
+            right=nub_padding + nub_width,
+            top=0,
+            bottom=border_width
+            * 3
+            // 2,  # overlaps the body border on purpose
+        )
+        nub.draw(
+            draw,
+            fill=border_color,
+            radius=border_width // 2 if style.rounded else 0,
+        )
+        border = border.offset(top=border_width)
+
+    border.draw(
+        draw,
+        outline=border_color,
+        width=border_width,
+        radius=border_width * 3 // 2 if style.rounded else 0,
+    )
+
+    inner = border.offset_edges(border_width + style.gap_units * unit)
+    inner.top += inner.height * (_FULL_PERCENT - percent) // _FULL_PERCENT
+    inner.draw(draw, fill=power_gradient_color(percent))
+    return image
+
+
+def battery_renderer(
+    percent: int, *, connected: bool, style: IconStyle
+) -> Callable[[int], Image.Image]:
+    """Return an icon renderer (``size -> image``) for a fixed battery state."""
+
+    def render(size: int) -> Image.Image:
+        return render_battery(size, percent, connected=connected, style=style)
+
+    return render

battery_tray-1.0.0/src/battery_tray/window.py

@@ -0,0 +1,136 @@
+"""The battery-selection window."""
+
+from __future__ import annotations
+
+import tkinter as tk
+from tkinter import ttk
+from typing import TYPE_CHECKING
+
+from sevaht_gui import LabelGrooveFrame
+
+from .battery import status_lines
+from .config import MAX_POLL_SECONDS, MIN_POLL_SECONDS
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from sevaht_gui import TkApp
+
+    from .battery import BatteryStatus
+
+
+class BatterySelectorWindow:
+    """Lets the user pick which battery to monitor and shows its status.
+
+    Built on the app's root window; the app drives :meth:`set_batteries` /
+    :meth:`set_status` from its poll, and :meth:`show` from the tray.
+    """
+
+    def __init__(
+        self,
+        app: TkApp,
+        *,
+        on_select: Callable[[str], None],
+        on_poll_change: Callable[[float], None],
+        has_tray: bool,
+    ) -> None:
+        self.app = app
+        self.root = app.root
+        self._on_select = on_select
+        self._on_poll_change = on_poll_change
+        self._has_tray = has_tray
+        self._battery_var = tk.StringVar(master=self.root)
+        self._poll_var = tk.StringVar(master=self.root)
+        self._build_ui()
+
+    def _build_ui(self) -> None:
+        self.root.title("Battery Tray")
+        self.root.resizable(False, False)
+        self.root.minsize(260, 0)
+
+        content = ttk.Frame(self.root, padding=16)
+        content.pack(fill=tk.BOTH, expand=True)
+
+        box = LabelGrooveFrame(content, text="Battery")
+        box.pack(fill=tk.X)
+
+        self._combo = ttk.Combobox(
+            box.interior,
+            textvariable=self._battery_var,
+            state="readonly",
+            width=24,
+        )
+        self._combo.pack(fill=tk.X, padx=6, pady=(0, 8))
+        self._combo.bind("<<ComboboxSelected>>", self._on_combo_selected)
+
+        self._status_label = ttk.Label(box.interior, justify=tk.LEFT, text="")
+        self._status_label.pack(anchor="w", padx=6, pady=(0, 4))
+
+        settings = LabelGrooveFrame(content, text="Settings")
+        settings.pack(fill=tk.X, pady=(8, 0))
+        ttk.Label(settings.interior, text="Refresh every (seconds):").pack(
+            side=tk.LEFT, padx=(6, 6)
+        )
+        poll_spinbox = ttk.Spinbox(
+            settings.interior,
+            textvariable=self._poll_var,
+            from_=MIN_POLL_SECONDS,
+            to=MAX_POLL_SECONDS,
+            increment=1,
+            width=7,
+            command=self._on_poll_committed,
+        )
+        poll_spinbox.pack(side=tk.LEFT, padx=(0, 6))
+        # Commit on spin (command), on Enter, and on leaving the field.
+        poll_spinbox.bind("<Return>", self._on_poll_committed)
+        poll_spinbox.bind("<FocusOut>", self._on_poll_committed)
+
+        buttons = ttk.Frame(content)
+        buttons.pack(fill=tk.X, pady=(12, 0))
+        # The window-close (X) is handled by TkApp: hide when a tray houses the
+        # window, quit otherwise.
+        if self._has_tray:
+            ttk.Button(buttons, text="Hide", command=self.app.hide).pack(
+                side=tk.RIGHT
+            )
+        ttk.Button(buttons, text="Quit", command=self.app.quit).pack(
+            side=tk.RIGHT, padx=(0, 6) if self._has_tray else (0, 0)
+        )
+
+    def _on_combo_selected(self, _event: tk.Event[ttk.Combobox]) -> None:
+        name = self._battery_var.get()
+        if name:
+            self._on_select(name)
+
+    def _on_poll_committed(
+        self, _event: tk.Event[ttk.Spinbox] | None = None
+    ) -> None:
+        try:
+            seconds = float(self._poll_var.get())
+        except ValueError:
+            return  # leave the field as-is so the user can correct it
+        seconds = max(MIN_POLL_SECONDS, min(seconds, MAX_POLL_SECONDS))
+        self.set_poll_seconds(seconds)
+        self._on_poll_change(seconds)
+
+    def set_poll_seconds(self, seconds: float) -> None:
+        """Show the current refresh interval (UI thread)."""
+        self._poll_var.set(f"{seconds:g}")
+
+    def set_batteries(self, names: list[str], selected: str | None) -> None:
+        """Update the battery choices and the current selection (UI thread)."""
+        self._combo["values"] = names
+        if selected is not None and selected in names:
+            self._battery_var.set(selected)
+        else:
+            self._battery_var.set(names[0] if names else "")
+
+    def set_status(self, status: BatteryStatus | None) -> None:
+        """Update the shown status for the selected battery (UI thread)."""
+        if status is None:
+            self.root.title("Battery Tray - No battery")
+            self._status_label.configure(text="No battery detected.")
+            return
+        charge_state = "charging" if status.charging else "discharging"
+        self.root.title(f"Battery Tray - {status.capacity}% ({charge_state})")
+        self._status_label.configure(text="\n".join(status_lines(status)))

battery_tray-1.0.0/tests/test_battery.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from battery_tray.battery import (
+    BatteryLevel,
+    list_batteries,
+    read_battery,
+    status_lines,
+)
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+def _make_supply(root: Path, name: str, **files: str) -> None:
+    supply = root / name
+    supply.mkdir(parents=True)
+    for key, value in files.items():
+        (supply / key).write_text(value, encoding="utf-8")
+
+
+def test_list_batteries_filters_non_batteries(tmp_path: Path) -> None:
+    _make_supply(tmp_path, "AC", type="Mains")
+    _make_supply(tmp_path, "BAT1", type="Battery", capacity="50")
+    _make_supply(tmp_path, "BAT0", type="Battery", capacity="80")
+    assert list_batteries(tmp_path) == ["BAT0", "BAT1"]
+
+
+def test_list_batteries_missing_root(tmp_path: Path) -> None:
+    assert list_batteries(tmp_path / "nope") == []
+
+
+def test_read_battery_discharging_with_remaining(tmp_path: Path) -> None:
+    _make_supply(
+        tmp_path,
+        "BAT0",
+        type="Battery",
+        capacity="80",
+        status="Discharging",
+        energy_now="50000000",
+        power_now="10000000",  # 5 hours remaining
+    )
+    status = read_battery("BAT0", root=tmp_path)
+    assert status is not None
+    assert status.capacity == 80
+    assert status.charging is False
+    assert status.remaining.total_seconds() == 5 * 3600
+    assert status.level is BatteryLevel.GOOD
+
+
+def test_read_battery_charging(tmp_path: Path) -> None:
+    _make_supply(
+        tmp_path, "BAT0", type="Battery", capacity="95", status="Charging"
+    )
+    status = read_battery("BAT0", root=tmp_path)
+    assert status is not None
+    assert status.charging is True
+    assert status.level is BatteryLevel.HIGH
+
+
+def test_read_battery_missing(tmp_path: Path) -> None:
+    assert read_battery("BAT9", root=tmp_path) is None
+
+
+def test_status_lines(tmp_path: Path) -> None:
+    _make_supply(
+        tmp_path,
+        "BAT0",
+        type="Battery",
+        capacity="42",
+        status="Discharging",
+        charge_now="4200000",
+        current_now="2100000",  # 2 hours
+    )
+    status = read_battery("BAT0", root=tmp_path)
+    assert status is not None
+    lines = status_lines(status)
+    assert lines[0] == "Charge: 42%"
+    assert "disconnected" in lines[1]
+    assert lines[2] == "Life: 2h 0m"

battery_tray-1.0.0/tests/test_config.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from battery_tray.config import (
+    DEFAULT_POLL_SECONDS,
+    MAX_POLL_SECONDS,
+    Config,
+    load_config,
+    save_config,
+)
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+def test_load_missing_returns_defaults(tmp_path: Path) -> None:
+    config = load_config(tmp_path / "config.json")
+    assert config.battery is None
+    assert config.poll_seconds == DEFAULT_POLL_SECONDS
+
+
+def test_save_then_load_roundtrip(tmp_path: Path) -> None:
+    # Parent dir does not exist yet; save should create it.
+    path = tmp_path / "sevaht" / "battery-tray" / "config.json"
+    save_config(path, Config(battery="BAT0", poll_seconds=10.0))
+    loaded = load_config(path)
+    assert loaded.battery == "BAT0"
+    assert loaded.poll_seconds == 10.0
+
+
+def test_load_ignores_garbage(tmp_path: Path) -> None:
+    path = tmp_path / "config.json"
+    path.write_text("not json", encoding="utf-8")
+    assert load_config(path).battery is None
+
+
+def test_poll_seconds_clamped_on_load(tmp_path: Path) -> None:
+    path = tmp_path / "config.json"
+    save_config(path, Config(poll_seconds=99999.0))
+    assert load_config(path).poll_seconds == MAX_POLL_SECONDS

battery_tray-1.0.0/tests/test_package_version.py

@@ -0,0 +1,5 @@
+from battery_tray import __version__
+
+
+def test_version_defined() -> None:
+    assert bool(__version__)

battery_tray-1.0.0/tests/test_render.py

@@ -0,0 +1,22 @@
+from battery_tray.render import IconStyle, power_gradient_color, render_battery
+
+
+def test_gradient_endpoints() -> None:
+    assert power_gradient_color(100) == (0, 255, 0)  # full -> green
+    assert power_gradient_color(0) == (255, 0, 0)  # empty -> red
+
+
+def test_gradient_clamps_out_of_range() -> None:
+    assert power_gradient_color(150) == power_gradient_color(100)
+    assert power_gradient_color(-10) == power_gradient_color(0)
+
+
+def test_render_battery_size_and_mode() -> None:
+    image = render_battery(48, 50, connected=True, style=IconStyle())
+    assert image.size == (48, 48)
+    assert image.mode == "RGBA"
+
+
+def test_render_battery_tiny_size_does_not_crash() -> None:
+    image = render_battery(1, 0, connected=False, style=IconStyle())
+    assert image.size == (1, 1)