Metadata-Version: 2.4
Name: nico579-commons
Version: 0.3.2
Summary: Briques communes à blink2video, lidar2map, watch2notif et gpxsolar
License: GPL-3.0-or-later
Project-URL: Source, https://github.com/nico579/nico579-commons
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: tray
Requires-Dist: pystray>=0.19; extra == "tray"
Requires-Dist: Pillow; extra == "tray"
Dynamic: license-file

# nico579-commons

Shared building blocks for four small open-source apps:
[blink2video](https://github.com/nico579/blink2video),
[lidar2map](https://github.com/nico579/lidar2map),
[watch2notif](https://github.com/nico579/watch2notif) and
[gpxsolar](https://github.com/nico579/gpxsolar).

Each of them grew its own copy of the same pieces: the system tray icon, the
local web server, atomic file writes, the update check. Every fix had to be
carried by hand into the other copies, and some were forgotten. This package
gathers those pieces in one place, one module each, so that the four apps
behave the same and a fix lands everywhere at once.

## Modules

- `nico579_commons.tray`: the tray icon, with the very same menu in all four
  apps: Open, "Update to x.y" only when a newer version is known, Restart,
  Stop, and "Create a Desktop shortcut". There is no room for app-specific
  entries on purpose: everything else lives in the page that Open brings
  up. The menu is rebuilt every five seconds, on the main thread under
  macOS; Restart, Stop and Update run off the icon's message loop, and the
  icon waits for them before returning.
- `nico579_commons.raccourci`: a desktop shortcut in one call, as a .lnk on
  Windows, a small .app on macOS and a trusted .desktop file on Linux.
- `nico579_commons.maj`: a light check for a newer GitHub release, asked at
  most once an hour by a background thread, so the tray menu and the page
  read the answer without waiting for the network.
- `nico579_commons.relance`: what "Restart" needs. Under the app's own
  systemd user service, systemd itself restarts it, since a process spawned
  from inside the service would be killed along with it; elsewhere, a new
  detached process, in its own session so that launchd leaves it alone.
  `hors_du_service()` does the same for a second process that must outlive
  the app, such as lidar2map's "New instance": under the service, it starts
  in a scope of its own (`systemd-run --user --scope`).
- `nico579_commons.environnement`: gives system programs (systemctl,
  xdg-open, the browser) the `LD_LIBRARY_PATH` they had before the
  PyInstaller bootloader prefixed it with the app's own libraries.

The inventory of what is shared, and where the work stands, lives in
[INVENTAIRE.md](INVENTAIRE.md) (in French).

## Install

```sh
pip install nico579-commons          # relance, raccourci, maj, environnement
pip install "nico579-commons[tray]"  # plus pystray and Pillow, for the icon
```

The package on its own requires nothing: only `tray` needs pystray and Pillow
(the `tray` extra), and `tray.disponible()` says whether they, and a
notification area, are there. An app that lists them itself does not need the
extra.

## Use

```python
from nico579_commons import tray

actions = tray.Actions(ouvrir=open_page, redemarrer=restart, arreter=stop,
                       version_disponible=cached_newer_version,
                       mettre_a_jour=start_update,
                       creer_raccourci=create_desktop_shortcut,
                       langue=current_language)
tray.Tray("myapp", Path("assets/myapp.ico"), actions).executer()
```

Python 3.8 or later: blink2video still ships a Windows 7 build on 3.8.

## License

GPL-3.0-or-later, like the four apps.
