pingmonitor 1.0.0__py3-none-any.whl

pingmon/scoring.py

@@ -0,0 +1,70 @@
+"""Region Advisor: composite per-target quality score by use-case profile."""
+
+from __future__ import annotations
+
+from .stats import TargetStats
+
+# profile key -> (label, one-line description)
+PROFILES = ["voip", "gaming", "web", "bulk"]
+PROFILE_META = {
+    "voip": ("VoIP / Video call", "jitter & loss dominate (MOS / E-model)"),
+    "gaming": ("Gaming", "raw latency + jitter, loss punished hard"),
+    "web": ("Web / API", "latency-led, mild loss penalty"),
+    "bulk": ("Bulk / Backup", "loss-led, tolerant of latency"),
+}
+
+
+def score(st: TargetStats, profile: str) -> float | None:
+    """Return a 0–100 quality score (higher is better), or None if no data."""
+    if st.status in ("DOWN",):
+        return 0.0
+    lat = st.avg
+    if lat is None:
+        return None
+    jit = st.jitter or 0.0
+    loss = st.loss
+
+    if profile == "voip":
+        mos = st.mos
+        if mos is None:
+            return None
+        return (mos - 1.0) / 3.5 * 100.0  # map MOS 1..4.5 -> 0..100
+
+    if profile == "gaming":
+        penalty = lat * 0.25 + jit * 1.0 + loss * 6.0
+    elif profile == "web":
+        penalty = lat * 0.18 + jit * 0.3 + loss * 4.0
+    elif profile == "bulk":
+        penalty = lat * 0.05 + jit * 0.1 + loss * 8.0
+    else:
+        penalty = lat * 0.2 + jit * 0.5 + loss * 5.0
+
+    return max(0.0, 100.0 - penalty)
+
+
+def grade(score_value: float | None) -> str:
+    if score_value is None:
+        return "—"
+    if score_value >= 85:
+        return "A"
+    if score_value >= 70:
+        return "B"
+    if score_value >= 50:
+        return "C"
+    if score_value >= 30:
+        return "D"
+    return "F"
+
+
+def reason(st: TargetStats, profile: str) -> str:
+    """Short human explanation for the score of a target under a profile."""
+    if st.status == "DOWN":
+        return "unreachable"
+    lat = st.avg
+    if lat is None:
+        return "warming up"
+    jit = st.jitter or 0.0
+    loss = st.loss
+    if profile == "voip" and st.mos is not None:
+        return f"MOS {st.mos:.1f} · {lat:.0f}ms / jit {jit:.0f} / loss {loss:.0f}%"
+    return f"{lat:.0f}ms · jit {jit:.0f}ms · loss {loss:.0f}%"

pingmon/stats.py

@@ -0,0 +1,150 @@
+"""Rolling per-target statistics: latency, jitter, loss, trend."""
+
+from __future__ import annotations
+
+from collections import deque
+from dataclasses import dataclass, field
+
+# Latency status thresholds (ms)
+EXCELLENT = 40.0
+GOOD = 90.0
+FAIR = 180.0
+POOR = 350.0
+
+
+@dataclass
+class TargetStats:
+    """Ring buffer of one target's samples plus derived metrics."""
+
+    maxlen: int = 90
+    samples: deque[float | None] = field(default_factory=deque)
+    sent: int = 0
+    lost: int = 0
+    last_ok: float | None = None
+    consecutive_fail: int = 0
+
+    def __post_init__(self) -> None:
+        self.samples = deque(maxlen=self.maxlen)
+
+    def record(self, latency: float | None) -> None:
+        self.sent += 1
+        self.samples.append(latency)
+        if latency is None:
+            self.lost += 1
+            self.consecutive_fail += 1
+        else:
+            self.last_ok = latency
+            self.consecutive_fail = 0
+
+    def reset(self) -> None:
+        self.samples.clear()
+        self.sent = 0
+        self.lost = 0
+        self.last_ok = None
+        self.consecutive_fail = 0
+
+    # --- derived values ---
+
+    @property
+    def ok_values(self) -> list[float]:
+        return [s for s in self.samples if s is not None]
+
+    @property
+    def last(self) -> float | None:
+        return self.samples[-1] if self.samples else None
+
+    @property
+    def avg(self) -> float | None:
+        v = self.ok_values
+        return sum(v) / len(v) if v else None
+
+    @property
+    def vmin(self) -> float | None:
+        v = self.ok_values
+        return min(v) if v else None
+
+    @property
+    def vmax(self) -> float | None:
+        v = self.ok_values
+        return max(v) if v else None
+
+    def percentile(self, p: float) -> float | None:
+        """Linear-interpolated percentile of successful samples (p in 0–100)."""
+        v = sorted(self.ok_values)
+        if not v:
+            return None
+        if len(v) == 1:
+            return v[0]
+        k = (len(v) - 1) * p / 100.0
+        f = int(k)
+        c = min(f + 1, len(v) - 1)
+        if f == c:
+            return v[f]
+        return v[f] + (v[c] - v[f]) * (k - f)
+
+    @property
+    def median(self) -> float | None:
+        return self.percentile(50.0)
+
+    @property
+    def jitter(self) -> float | None:
+        """Mean absolute difference between consecutive successful samples."""
+        v = self.ok_values
+        if len(v) < 2:
+            return None
+        diffs = [abs(v[i] - v[i - 1]) for i in range(1, len(v))]
+        return sum(diffs) / len(diffs)
+
+    @property
+    def loss(self) -> float:
+        return 100.0 * self.lost / self.sent if self.sent else 0.0
+
+    @property
+    def r_factor(self) -> float | None:
+        """ITU-T E-model R-factor (0–100) from avg latency, jitter and loss.
+
+        Uses effective latency = latency + 2·jitter (jitter hurts ~2× as much
+        as latency) and a linear packet-loss impairment.
+        """
+        lat = self.avg
+        if lat is None:
+            return None
+        jit = self.jitter or 0.0
+        eff = lat + 2.0 * jit + 10.0  # +10ms codec/processing allowance
+        if eff < 160.0:
+            r = 93.2 - eff / 40.0
+        else:
+            r = 93.2 - (eff - 120.0) / 10.0
+        r -= 2.5 * self.loss  # packet-loss impairment
+        return max(0.0, min(100.0, r))
+
+    @property
+    def mos(self) -> float | None:
+        """Pseudo Mean Opinion Score (1.0–4.5) derived from the R-factor."""
+        r = self.r_factor
+        if r is None:
+            return None
+        mos = 1.0 + 0.035 * r + 7e-6 * r * (r - 60.0) * (100.0 - r)
+        return max(1.0, min(4.5, mos))
+
+    @property
+    def status(self) -> str:
+        """PENDING | DOWN | UNSTABLE | EXCELLENT | GOOD | FAIR | POOR."""
+        if not self.samples:
+            return "PENDING"
+        if self.consecutive_fail >= 3:
+            return "DOWN"
+        last = self.last
+        if last is None:
+            return "UNSTABLE"
+        if self.loss >= 20.0:
+            return "UNSTABLE"
+        if last < EXCELLENT:
+            return "EXCELLENT"
+        if last < GOOD:
+            return "GOOD"
+        if last < FAIR:
+            return "FAIR"
+        if last < POOR:
+            return "POOR"
+        return "POOR"

pingmonitor-1.0.0.dist-info/METADATA

@@ -0,0 +1,224 @@
+Metadata-Version: 2.4
+Name: pingmonitor
+Version: 1.0.0
+Summary: TUI monitor of latency and availability to servers by country
+Project-URL: Homepage, https://github.com/kottot13/pingmon
+Project-URL: Repository, https://github.com/kottot13/pingmon
+Author: pingmon contributors
+License: MIT
+License-File: LICENSE
+Keywords: geoip,latency,monitoring,network,ping,textual,tui
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: System :: Networking :: Monitoring
+Requires-Python: >=3.11
+Requires-Dist: textual>=0.80
+Description-Content-Type: text/markdown
+
+# pingmon
+
+A full-featured terminal UI for monitoring **latency and availability** to
+servers in different countries. Built with [Textual](https://textual.textualize.io/).
+
+It continuously TCP-pings a set of targets (one or more reachable hosts per
+country), and shows a live, colour-coded dashboard with per-target latency,
+average, jitter, packet loss, a status indicator, and an animated trend graph.
+
+![pingmon screenshot](docs/screenshot.svg)
+
+## Features
+
+- **Live dashboard** — sortable table of targets with status dot, latency, average, loss and an inline coloured sparkline trend.
+- **Detail panel** — for the selected target: live latency graph, quality gauge, min / max / avg / jitter / loss, **MOS** call-quality score, resolved IP, **GeoIP city / region and the hosting network (ASN + ISP)**, sample count.
+- **★ Region Advisor** *(unique)* — ranks regions by a composite 0–100 score under a chosen **use-case profile** (VoIP / Gaming / Web / Bulk) and highlights the best region to pick right now. Press `g`. See [below](#region-advisor).
+- **MOS / R-factor** — turns latency + jitter + loss into the single VoIP call-quality number (ITU-T E-model), the same metric paid monitoring suites charge for.
+- **Threshold alerts** — fire when a target stays slow or lossy for N samples: terminal bell, an in-app toast, an OS desktop notification, and a blinking row marker. Auto-clears on recovery.
+- **Traceroute drill-down** — press `Enter` (or click) on a row for an mtr-style hop-by-hop path with per-hop loss and per-probe timings, plus **GeoIP per hop** (flag, city and ASN) so you can see which countries and networks the traffic crosses.
+- **Per-country set, ready to go** — the Netherlands, Germany, United Kingdom, France, Cyprus, Italy, Spain, Greece, Sweden, Ireland and the United States are pre-configured with reachable hosts.
+- **Editable targets** — add (`a`), edit (`E`) and delete (`d`) targets right inside the TUI, or edit the TOML config by hand; reset stats with `r`. In-app changes are saved to the config immediately.
+- **GeoIP auto-detect & enrichment** — every target is looked up via ip-api.com: the detail panel shows its **city, region and hosting network (ASN + ISP)**, and when you add a target with country/flag left blank they are filled in automatically.
+- **Show filter** — flip the table between **all**, **mine only** (targets you added) and **others only** (the built-in set) with `f`.
+- **No root required** — uses TCP connect timing (port 443/80), so it works without raw-socket / ICMP privileges and measures real service latency.
+- **Modern terminal UX** — truecolor, mouse support, zebra-striped table, a live "heartbeat" spinner, keyboard and mouse navigation, sort modes and modal dialogs.
+
+| Region Advisor | Traceroute drill-down |
+| -------------- | --------------------- |
+| ![advisor](docs/advisor.svg) | ![traceroute](docs/traceroute.svg) |
+
+## Requirements
+
+- Python 3.11+ (not needed for the standalone binary below)
+- `textual >= 0.80` (installed automatically)
+
+## Install as a system command
+
+Use it like `htop` — install once, run `pingmon` from anywhere.
+
+### pipx / uv (recommended, Linux + macOS)
+
+```bash
+pipx install pingmon            # from PyPI once published
+pipx install .                  # or from a checkout of this repo
+pipx install git+https://github.com/kottot13/pingmon
+# uv works the same:  uv tool install pingmon   /   uvx pingmon
+```
+
+`pipx` keeps pingmon in its own isolated environment and puts the `pingmon`
+command on your `PATH`.
+
+### Homebrew (macOS / Linuxbrew)
+
+A formula skeleton lives in [`packaging/pingmon.rb`](packaging/pingmon.rb).
+Publish to PyPI, fill in the sdist URL + `brew update-python-resources`, then:
+
+```bash
+brew install kottot13/tap/pingmon
+```
+
+### Standalone binary (no Python on the target)
+
+The most htop-like option — a single executable built with PyInstaller
+([`packaging/pingmon.spec`](packaging/pingmon.spec)):
+
+```bash
+pip install pyinstaller
+pyinstaller packaging/pingmon.spec
+sudo cp dist/pingmon /usr/local/bin/     # macOS
+cp dist/pingmon ~/.local/bin/            # Linux
+```
+
+Build once per OS/architecture (PyInstaller does not cross-compile).
+
+### From source (development)
+
+```bash
+./run.sh                # makes a local venv, installs Textual, launches
+# or
+python3 -m venv .venv && .venv/bin/pip install -e . && .venv/bin/pingmon
+```
+
+Config lives at `~/.config/pingmon/config.toml` by default (or a local
+`./config.toml` if present, or `$PINGMON_CONFIG`). Run `pingmon --help` for the
+CLI flags (`-V/--version`, `-c/--config PATH`).
+
+## Keys
+
+| Key            | Action                          |
+| -------------- | ------------------------------- |
+| `↑ / ↓`, `j/k` | Move selection                  |
+| `Enter`        | Traceroute drill-down for the selected target |
+| `g`            | Open the Region Advisor (`[` `]` / `p` switch profile inside) |
+| `p`            | Cycle the Advisor profile (VoIP / Gaming / Web / Bulk) |
+| `f`            | Cycle the show filter (all / mine only / others only) |
+| `space`        | Pause / resume probing          |
+| `m` / `M`      | Sort by latency (ms); press again to flip fastest ⇄ slowest first |
+| `s`            | Cycle sort (country / latency / loss / jitter) |
+| `a`            | Add a target                    |
+| `E`            | Edit the selected target (form pre-filled) |
+| `A`            | Toggle the alert system on / off |
+| `d`            | Delete the selected target      |
+| `r`            | Reset all statistics            |
+| `e`            | Show the config file path       |
+| `q`            | Quit                            |
+
+## Region Advisor
+
+The Advisor (`g`) answers the question the tool was born from — *which region
+should I actually pick right now?* It computes a **0–100 score** per region from
+latency, jitter and loss, under a selectable **profile**:
+
+| Profile | What it optimises for |
+| ------- | --------------------- |
+| **VoIP / Video call** | jitter & loss dominate; driven by the MOS / E-model score |
+| **Gaming** | raw latency + jitter, loss punished hard |
+| **Web / API** | latency-led, mild loss penalty |
+| **Bulk / Backup** | loss-led, tolerant of high latency |
+
+Regions are ranked best-first with the #1 pick highlighted, each with a score
+bar, a letter grade (A–F) and a one-line reason. Switch profile with `[` / `]`,
+`p` or `Tab`; close with `Esc`.
+
+## Alerts
+
+A target enters **alert** state when, for `alert_window` consecutive samples, it
+is unreachable, slower than `alert_latency` ms, or its recent loss exceeds
+`alert_loss` %. On entry pingmon rings the terminal bell, shows a toast, raises
+an OS desktop notification (macOS `osascript` / Linux `notify-send`, toggle with
+`desktop_notify`) and blinks the row's status marker; it auto-clears with a
+"Recovered" toast. Press `A` to switch the whole alert system off or on at any
+time (the banner shows `⚲ alerts off` while disabled); tune or permanently
+disable the triggers in `config.toml`.
+
+## Status colours
+
+| Status      | Meaning (last sample)         |
+| ----------- | ----------------------------- |
+| `EXCELLENT` | < 40 ms                       |
+| `GOOD`      | < 90 ms                       |
+| `FAIR`      | < 180 ms                      |
+| `POOR`      | < 350 ms / ≥ 350 ms           |
+| `UNSTABLE`  | loss ≥ 20% or a recent drop   |
+| `DOWN`      | 3+ consecutive failures       |
+| `PENDING`   | no samples yet                |
+
+## Configuration
+
+On first run a `config.toml` is created at `~/.config/pingmon/config.toml` (or a
+local `./config.toml` if one already exists, or wherever `$PINGMON_CONFIG` /
+`--config` points). It is plain TOML and meant to be hand-edited:
+
+```toml
+interval = 2.0        # poll period per target, seconds
+timeout  = 2.0        # TCP connect timeout, seconds
+history  = 90         # samples kept in memory for the graph
+
+alert_latency = 300.0 # alert if latency stays above this (ms); 0 disables
+alert_loss    = 20.0  # alert if recent loss exceeds this (%); 0 disables
+alert_window  = 3     # consecutive bad samples before an alert fires
+desktop_notify = true # also raise an OS desktop notification on alert
+
+[[targets]]
+country = "Netherlands"
+flag = "🇳🇱"
+host = "speedtest.ams1.nl.leaseweb.net"
+port = 80
+source = "builtin"   # "builtin" (shipped) or "user" (added in-app) — drives the `f` filter
+
+[[targets]]
+country = "United States"
+flag = "🇺🇸"
+host = "speedtest.newark.linode.com"
+port = 443
+source = "builtin"
+```
+
+Add as many `[[targets]]` blocks as you like; any host or IP works, and the
+port is per-target. `source` is optional — if omitted it is inferred (hosts in
+the built-in set are `builtin`, everything else `user`).
+
+## How latency is measured
+
+`pingmon` opens a TCP connection to `host:port` and times the round-trip of the
+connection handshake (SYN → SYN/ACK). That is close to true network RTT and,
+unlike ICMP, needs no elevated privileges and reflects whether the service port
+is actually answering. Failed or timed-out connects count as packet loss.
+
+## Project layout
+
+```
+pingmon/
+  app.py      # Textual app: table, detail panel, graphs, advisor, alerts, actions
+  pinger.py   # async TCP ping + DNS resolve
+  stats.py    # rolling per-target stats (latency, jitter, loss, MOS, status)
+  scoring.py  # Region Advisor: composite score + use-case profiles
+  netutil.py  # async traceroute + OS desktop notifications
+  render.py   # colours, status meta, text sparklines
+  config.py   # TOML load/save + built-in per-country target set
+  app.tcss    # dark theme / layout
+```

pingmonitor-1.0.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+pingmon/__init__.py,sha256=HIXX6lx2XDgyr6ed8sRKJzil4K7sKWd3Zos-Rj9ih2U,104
+pingmon/__main__.py,sha256=876xZTqhPeDBD2GKKr8pKX33Af8PhFTosAI8bYQsFgQ,61
+pingmon/app.py,sha256=1jkCjRE4h297Gdi-Se94erllwaLmxDlno30VtbAZ56c,35541
+pingmon/config.py,sha256=IC1Qrlbf3iABuHvCKE3zvXoxNrMeNY0crAKkUYaA7tc,6852
+pingmon/netutil.py,sha256=779wJIN3-KykdmdKUh-01uMdnNFcgN9VcL9U9QUAN_Y,4409
+pingmon/pinger.py,sha256=VNDjv9FLxLlKVlhcxXNfoF69e0dsaw-BXe-TRzbRbns,1378
+pingmon/render.py,sha256=06jxLBhvRHLjvudac_UTkVEvCI62jpOne9_8may1Rqc,4177
+pingmon/scoring.py,sha256=mnpWsClFus45HfUTT4kYKYFCuqx6AKTdm2J9YCVN92s,2122
+pingmon/stats.py,sha256=v4J3Wu90YP-4Fi8RtkBIHC3DJdDoo1axG0W3pVsqgyY,4245
+pingmon/app.tcss,sha256=ufMOKPeLxZVKSkrFg1aFR6nYKm1_dhMM0L6l-bgpkw0,2383
+pingmonitor-1.0.0.dist-info/METADATA,sha256=YFbdFKYdye_9w0YtV1rvNJnpx3EudjAxOOam04Vl6DE,10511
+pingmonitor-1.0.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+pingmonitor-1.0.0.dist-info/entry_points.txt,sha256=opcNVMcB7CdmgQdhj6qI-niT_Mn-P-EMaWzQdG7UnDo,45
+pingmonitor-1.0.0.dist-info/licenses/LICENSE,sha256=FdUqEswHPGcrSfDe0hRzOIIDLcq3SdamHR_Y1_gUVGI,1077
+pingmonitor-1.0.0.dist-info/RECORD,,

pingmonitor-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

pingmonitor-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pingmon = pingmon.app:main

pingmonitor-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pingmon contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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 OR COPYRIGHT HOLDERS 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.