sevaht-gui 1.0.0__tar.gz

sevaht_gui-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

sevaht_gui-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>

sevaht_gui-1.0.0/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: sevaht-gui
+Version: 1.0.0
+Summary: Cross-platform tray icons and a tkinter app base for small GUIs.
+Project-URL: Homepage, https://github.com/sevaht/sevaht-gui
+Project-URL: Documentation, https://sevaht.github.io/sevaht-gui/
+Project-URL: Source, https://github.com/sevaht/sevaht-gui
+Project-URL: Issues, https://github.com/sevaht/sevaht-gui/issues
+Author-email: Jacob McIntosh <nacitar.sevaht@gmail.com>
+License-Expression: Unlicense
+License-File: LICENSE
+Keywords: gui,pystray,status-icon,statusnotifieritem,system-tray,tkinter,tray,xembed
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: Microsoft :: Windows
+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 :: Desktop Environment
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: dbus-next>=0.2.3; sys_platform == 'linux'
+Requires-Dist: pillow>=12.2.0
+Requires-Dist: pystray>=0.19.5; sys_platform == 'win32'
+Requires-Dist: python-xlib>=0.33; sys_platform == 'linux'
+Requires-Dist: sevaht-utility>=1.0.0
+Description-Content-Type: text/markdown
+
+# sevaht-gui
+
+Small cross-platform GUI building blocks: a system-tray icon and a tkinter
+application base, shared across Sevaht desktop tools.
+
+## Tray icon
+
+`create_tray_icon` returns a single `TrayIcon` interface backed by the right
+implementation for the platform:
+
+- **Windows** — [pystray](https://pypi.org/project/pystray/).
+- **Linux** — a `StatusNotifierItem` (D-Bus) item when a usable SNI host is
+  present (KDE/GNOME, Wayland, or fluxbox with `snixembed`), falling back to a
+  self-contained XEmbed icon on bare X11 window managers with no SNI host.
+
+The feature model is deliberately small: a default **activate** action
+(left-click, and the default menu item where a menu is available) and a
+**quit** action. Backends that can show a menu (pystray, SNI) offer both on
+right-click; the menu-less XEmbed backend maps right-click straight to quit.
+
+The icon is any **`IconSource`** — a prepared `PIL.Image`, a path to an image
+file (both static; the common case), or a renderer `Callable[[int], Image]`
+for apps that draw their own artwork. The tooltip and the icon can be changed
+live (`set_icon` accepts any `IconSource`), so an app can reflect state either
+by swapping prepared images or by re-rendering.
+
+macOS is intentionally unsupported: a real menu-bar item there needs a single
+main-thread Cocoa loop shared with tk (custom PyObjC), which the threaded model
+used here cannot provide.
+
+## TkApp
+
+`TkApp` owns a `tkinter.Tk` root and runs its `mainloop()` on the main thread,
+running the tray icon's own event loop on a worker thread. Work originating off
+the UI thread (e.g. tray menu callbacks) is marshalled back with
+`run_on_ui_thread` / `call_on_ui_thread`. `show()` / `hide()` and the
+`run(start_hidden=...)` flag manage window visibility (all thread-safe), and
+`set_window_icon` accepts the same `IconSource` as the tray.
+
+```python
+from sevaht_gui import TkApp, create_tray_icon
+
+app = TkApp()
+app.root.title("Example")
+app.set_window_icon("icon.png")  # static file; or a PIL image / renderer
+
+icon = create_tray_icon(
+    "example",
+    "Example",
+    "icon.png",          # any IconSource: path, PIL image, or renderer
+    on_activate=app.show,
+    on_quit=app.stop,
+)
+app.run(icon, start_hidden=True)  # only the tray shows until activated
+```
+
+The library manages the tray lifecycle, window visibility, and threading;
+choosing and (re)drawing the artwork is left to the application.
+
+## Documentation
+
+Full documentation lives in `docs/` and is published to GitHub Pages:
+<https://sevaht.github.io/sevaht-gui/>.
+
+### Building the docs locally
+
+```console
+$ uv run --group docs sphinx-build -b html docs docs/_build/html
+```
+
+Then open `docs/_build/html/index.html`. (Publishing to GitHub Pages requires
+enabling Pages with the "GitHub Actions" source in the repository settings.)

sevaht_gui-1.0.0/README.md

@@ -0,0 +1,72 @@
+# sevaht-gui
+
+Small cross-platform GUI building blocks: a system-tray icon and a tkinter
+application base, shared across Sevaht desktop tools.
+
+## Tray icon
+
+`create_tray_icon` returns a single `TrayIcon` interface backed by the right
+implementation for the platform:
+
+- **Windows** — [pystray](https://pypi.org/project/pystray/).
+- **Linux** — a `StatusNotifierItem` (D-Bus) item when a usable SNI host is
+  present (KDE/GNOME, Wayland, or fluxbox with `snixembed`), falling back to a
+  self-contained XEmbed icon on bare X11 window managers with no SNI host.
+
+The feature model is deliberately small: a default **activate** action
+(left-click, and the default menu item where a menu is available) and a
+**quit** action. Backends that can show a menu (pystray, SNI) offer both on
+right-click; the menu-less XEmbed backend maps right-click straight to quit.
+
+The icon is any **`IconSource`** — a prepared `PIL.Image`, a path to an image
+file (both static; the common case), or a renderer `Callable[[int], Image]`
+for apps that draw their own artwork. The tooltip and the icon can be changed
+live (`set_icon` accepts any `IconSource`), so an app can reflect state either
+by swapping prepared images or by re-rendering.
+
+macOS is intentionally unsupported: a real menu-bar item there needs a single
+main-thread Cocoa loop shared with tk (custom PyObjC), which the threaded model
+used here cannot provide.
+
+## TkApp
+
+`TkApp` owns a `tkinter.Tk` root and runs its `mainloop()` on the main thread,
+running the tray icon's own event loop on a worker thread. Work originating off
+the UI thread (e.g. tray menu callbacks) is marshalled back with
+`run_on_ui_thread` / `call_on_ui_thread`. `show()` / `hide()` and the
+`run(start_hidden=...)` flag manage window visibility (all thread-safe), and
+`set_window_icon` accepts the same `IconSource` as the tray.
+
+```python
+from sevaht_gui import TkApp, create_tray_icon
+
+app = TkApp()
+app.root.title("Example")
+app.set_window_icon("icon.png")  # static file; or a PIL image / renderer
+
+icon = create_tray_icon(
+    "example",
+    "Example",
+    "icon.png",          # any IconSource: path, PIL image, or renderer
+    on_activate=app.show,
+    on_quit=app.stop,
+)
+app.run(icon, start_hidden=True)  # only the tray shows until activated
+```
+
+The library manages the tray lifecycle, window visibility, and threading;
+choosing and (re)drawing the artwork is left to the application.
+
+## Documentation
+
+Full documentation lives in `docs/` and is published to GitHub Pages:
+<https://sevaht.github.io/sevaht-gui/>.
+
+### Building the docs locally
+
+```console
+$ uv run --group docs sphinx-build -b html docs docs/_build/html
+```
+
+Then open `docs/_build/html/index.html`. (Publishing to GitHub Pages requires
+enabling Pages with the "GitHub Actions" source in the repository settings.)

sevaht_gui-1.0.0/pyproject.toml

@@ -0,0 +1,146 @@
+[build-system]
+requires = ["hatchling (>=1.29.0,<2.0.0)", "hatch-vcs (>=0.5.0,<1.0.0)"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sevaht-gui"
+dynamic = ["version"]
+description = "Cross-platform tray icons and a tkinter app base for small GUIs."
+authors = [
+    {name = "Jacob McIntosh", email = "nacitar.sevaht@gmail.com"}
+]
+readme = "README.md"
+license = "Unlicense"
+requires-python = ">=3.12"
+keywords = [
+    "tray", "system-tray", "status-icon", "tkinter", "gui", "pystray",
+    "statusnotifieritem", "xembed",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: Microsoft :: Windows",
+    "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 :: Desktop Environment",
+    "Topic :: Software Development :: Libraries",
+    "Typing :: Typed",
+]
+dependencies = [
+    "Pillow>=12.2.0",
+    # Notifications (notify-send/dbus-send/console) live in sevaht-utility so
+    # they need no GUI/D-Bus library.
+    "sevaht-utility>=1.0.0",
+    # Windows uses pystray; Linux uses the StatusNotifierItem (dbus-next)
+    # backend, falling back to a self-contained XEmbed icon (python-xlib) on
+    # bare X11 window managers with no SNI host. macOS is intentionally
+    # unsupported: a real menu-bar item there needs a single main-thread Cocoa
+    # loop shared with tk (custom PyObjC), which the threaded model here cannot
+    # provide.
+    "pystray>=0.19.5; sys_platform == 'win32'",
+    "dbus-next>=0.2.3; sys_platform == 'linux'",
+    "python-xlib>=0.33; sys_platform == 'linux'",
+]
+
+[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)",
+]
+docs = [
+    "sphinx (>=8.1.0,<9.0.0)",
+    "furo (>=2024.8.6)",
+    "myst-parser (>=4.0.0,<5.0.0)",
+]
+
+[project.urls]
+Homepage = "https://github.com/sevaht/sevaht-gui"
+Documentation = "https://sevaht.github.io/sevaht-gui/"
+Source = "https://github.com/sevaht/sevaht-gui"
+Issues = "https://github.com/sevaht/sevaht-gui/issues"
+
+[tool.hatch.version]
+source = "vcs"
+
+# Allow building before any tags/commits exist (fresh repo, or a source tree
+# with no .git): hatch-vcs/setuptools-scm falls back to this instead of erroring.
+# Real tags/commits override it, so this only matters pre-history.
+[tool.hatch.version.raw-options]
+fallback_version = "0.0.0"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sevaht_gui"]
+
+[tool.hatch.build.targets.sdist]
+# Allowlist so dev/local files (.claude, checks, publish-test.sh, .github, ...)
+# never leak into a published sdist. pyproject.toml/PKG-INFO/README/.gitignore
+# are force-included by hatchling regardless.
+include = ["/src", "/tests", "/LICENSE"]
+
+[tool.black]
+line-length = 79
+skip-magic-trailing-comma = true
+
+[tool.mypy]
+strict = true
+mypy_path = ["typings"]
+exclude = ["^docs/", "^dist/"]
+
+# The SNI backend annotates D-Bus methods with the bus type-signature strings
+# the dbus-next decorators require (e.g. ``x: "i"``); these are not Python
+# types, so type-checking the module is not meaningful.
+[[tool.mypy.overrides]]
+module = "sevaht_gui._tray_sni"
+ignore_errors = true
+
+# pystray is a Windows-only dependency (not installed on Linux, where the
+# linters run) and ships no type stubs.
+[[tool.mypy.overrides]]
+module = "pystray"
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 79
+extend-exclude = ["docs"]
+
+[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"]
+"**/_tray_sni.py" = [
+    "ANN201", "ANN202", "ARG002", "F722", "F821", "N802", "PLR0913", "UP037"
+]
+"typings/Xlib/**/*.pyi" = ["ANN401", "A002", "N818"]
+
+[tool.vulture]
+# This is a library: public API surface looks "unused" to vulture since
+# nothing in-repo calls it, which is the false positive vulture's own docs
+# tell you to address by raising min_confidence rather than whitelisting.
+min_confidence = 70
+# The SNI backend implements a D-Bus protocol: its interface methods are
+# invoked over the bus (never from Python) and carry spec-mandated, unused
+# arguments (x, y, ...). vulture matches identifiers by name across the whole
+# tree, so these only look unused in a codebase this small; skip the file, as
+# it is already exempted from mypy for the same protocol-shaped reasons.
+exclude = ["*_tray_sni.py"]

sevaht_gui-1.0.0/src/sevaht_gui/__init__.py

@@ -0,0 +1,53 @@
+"""Small cross-platform GUI building blocks.
+
+Submodules:
+
+* :mod:`sevaht_gui.tray` -- a cross-platform system-tray icon
+  (:func:`~sevaht_gui.tray.create_tray_icon`) backed by pystray on Windows and
+  StatusNotifierItem/XEmbed on Linux.
+* :mod:`sevaht_gui.tkapp` -- :class:`~sevaht_gui.tkapp.TkApp`, a tkinter base
+  that owns the main thread and runs a tray icon on a worker thread.
+* :mod:`sevaht_gui.theme` -- default ttk theming (clam + checkmark indicator).
+* :mod:`sevaht_gui.widgets` -- reusable widgets (e.g. ``LabelGrooveFrame``).
+* :mod:`sevaht_gui.monitors` -- monitor geometry
+  (:func:`~sevaht_gui.monitors.primary_monitor_bounds`).
+
+:meth:`~sevaht_gui.tkapp.TkApp.notify` shows a desktop notification, using the
+tray icon when one exists and falling back to a standalone notifier otherwise,
+so notifications work with or without a tray.
+
+Attributes:
+    __version__: The installed distribution version.
+"""
+
+from __future__ import annotations
+
+import importlib.metadata
+
+from .monitors import primary_monitor_bounds
+from .theme import apply_theme
+from .tkapp import TkApp, WindowPlacement
+from .tray import (
+    SNIRegistrationError,
+    TrayIcon,
+    as_renderer,
+    create_tray_icon,
+    tray_available,
+)
+from .widgets import LabelGrooveFrame
+
+__version__ = importlib.metadata.version(__package__)
+
+__all__ = [
+    "LabelGrooveFrame",
+    "SNIRegistrationError",
+    "TkApp",
+    "TrayIcon",
+    "WindowPlacement",
+    "__version__",
+    "apply_theme",
+    "as_renderer",
+    "create_tray_icon",
+    "primary_monitor_bounds",
+    "tray_available",
+]