Metadata-Version: 2.4
Name: pingpoll
Version: 0.1.0
Summary: Live network device ping dashboard — status, latency, uptime, and subnet discovery
License: MIT
Project-URL: Homepage, https://github.com/greyliedtke/PyExplore
Keywords: ping,network,monitoring,uptime,latency,discovery,dashboard
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Networking :: Monitoring
Classifier: Topic :: Internet :: WWW/HTTP :: WSGI :: Application
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: flask>=3.0
Dynamic: license-file

# PingPoll

A small Flask library and app that pings a list of network devices, resolves
their hostnames, and shows live status, latency and uptime on a dashboard — plus
a subnet discovery sweep to find live hosts that aren't on your list yet.

## Install

```bash
pip install -e .
```

## Run

```bash
pingpoll --init        # write an example NetFile into the current directory
pingpoll               # serve the dashboard on http://localhost:5001
```

Or without installing:

```bash
pip install -r requirements.txt
python run.py
```

## Use as a library

```python
from pingpoll import serve
serve("NetFile", port=5001)          # blocking dev server
```

```python
from pingpoll import create_app       # build the Flask app (e.g. for gunicorn)
app = create_app("NetFile")
```

```python
from pingpoll import Monitor, Scanner # the pieces on their own
```

## How it works

- **`NetFile`** — your device list. One entry per line:
  `<ip_or_host>   [optional friendly name]`. Lines starting with `#` are ignored.
  The path defaults to `$PINGPOLL_NETFILE`, else `./NetFile`.
- **`pingpoll.monitor`** — a background thread pings every device on an interval
  (default 10s), keeps rolling history, and computes uptime %, average
  latency, and up/down transitions. Hostnames are reverse-resolved.
- **`pingpoll.app`** — the Flask app factory serving the dashboard and JSON API.
- **`templates/` + `static/`** — the dashboard (auto-refreshes every 5s).

## Network discovery

PingPoll can sweep your local subnet to find live hosts that **aren't** in the
NetFile. It auto-detects the local `/24` (and any private `/24`s implied by
addresses already in the NetFile), pings every host, resolves hostnames, and
flags each as **In NetFile** (defined) or **Undefined**.

- **In the dashboard:** click **Scan network**. Undefined hosts get a checkbox;
  select the ones you want and click **Add selected to NetFile** to append them
  (with their resolved hostname) and start monitoring immediately.
- **From the terminal:**

  ```bash
  pingpoll --scan
  ```

  prints a table of every live host and whether it's defined.

## CLI

```
pingpoll [--netfile PATH] [--port 5001] [--host 0.0.0.0] [--open] [--debug]
pingpoll --init     # write an example NetFile and exit
pingpoll --scan     # one-off terminal subnet scan and exit
```

## API

| Endpoint          | Method | Purpose                                  |
|-------------------|--------|------------------------------------------|
| `/`               | GET    | Dashboard                                |
| `/api/status`     | GET    | Full status snapshot (JSON)              |
| `/api/reload`     | POST   | Re-read the NetFile without restarting   |
| `/api/scan`       | POST   | Start a subnet discovery sweep           |
| `/api/discovery`  | GET    | Discovery results + progress (JSON)      |
| `/api/adopt`      | POST   | Append discovered hosts to the NetFile   |

## Configuration

Tunables live at the top of `pingpoll/monitor.py`: `PING_INTERVAL`,
`PING_TIMEOUT`, `HISTORY_LEN`, `WORKERS`. Ping flags auto-adjust for
macOS / Linux / Windows.
