ipmg 2.0.0__tar.gz → 2.1.0__tar.gz

{ipmg-2.0.0/src/ipmg.egg-info → ipmg-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ipmg
-Version: 2.0.0
+Version: 2.1.0
 Summary: IP Management & Ping Monitoring CLI Tool
 Author: Sameer Alam
 Maintainer-email: Sameer Alam <sameeralam3127@gmail.com>
@@ -10,7 +10,7 @@ Project-URL: Documentation, https://github.com/sameeralam3127/ipmg#readme
 Project-URL: Repository, https://github.com/sameeralam3127/ipmg
 Project-URL: Issues, https://github.com/sameeralam3127/ipmg/issues
 Project-URL: Changelog, https://github.com/sameeralam3127/ipmg/releases
-Keywords: ip,network,ping,monitoring,cli,port-scan
+Keywords: ip,network,ping,monitoring,cli,port-scan,network-scanner,ping-sweep,subnet-scanner,homelab,sysadmin
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Python :: 3.9
@@ -29,7 +29,7 @@ Classifier: Environment :: Console
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: pandas>=2.0
+Requires-Dist: pandas>=2.2.2
 Requires-Dist: openpyxl>=3.1
 Requires-Dist: rich>=13.0
 Requires-Dist: fastapi>=0.110
@@ -38,6 +38,7 @@ Requires-Dist: websockets>=12
 Requires-Dist: python-multipart>=0.0.9
 Provides-Extra: dev
 Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
 Requires-Dist: ruff>=0.4; extra == "dev"
 Requires-Dist: pre-commit>=3.5.0; extra == "dev"
 Requires-Dist: python-semantic-release>=10.5.3; extra == "dev"
@@ -58,8 +59,19 @@ can send to someone: Excel, CSV, JSON, or Markdown. It works from the command
 line or from IPMG Web, a local browser UI, and it remembers every scan so it can tell
 you what moved.
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/sameeralam3127/ipmg/main/docs/assets/ipmg-demo.gif" alt="ipmg scanning 13 hosts in parallel: live results with reverse DNS names and latency, then a summary of 10 active and 3 timed out" width="820">
+</p>
+
+**Why not `nmap -sn`, `fping`, or Angry IP Scanner?** They tell you what is up
+right now. IPMG also remembers every scan and tells you what changed since the
+last one: the host that dropped off, the device that appeared, the latency that
+doubled. It writes the report you would otherwise build by hand.
+[How it compares](#how-it-compares)
+
 **Website:** [sameeralam3127.github.io/ipmg](https://sameeralam3127.github.io/ipmg/) ·
-**Live demo:** [IPMG Web with sample data](https://sameeralam3127.github.io/ipmg/demo/)
+**Live demo:** [IPMG Web with sample data](https://sameeralam3127.github.io/ipmg/demo/) ·
+**Command builder:** [pick what you want, copy the command](https://sameeralam3127.github.io/ipmg/#builder)
 
 ```bash
 pip install ipmg
@@ -71,6 +83,7 @@ ipmg --discover        # scan the network you are on, right now
 
 **Contents**
 
+[How it compares](#how-it-compares) ·
 [Install](#install) ·
 [Your first scan](#your-first-scan) ·
 [Common tasks](#common-tasks) ·
@@ -86,6 +99,26 @@ ipmg --discover        # scan the network you are on, right now
 
 ---
 
+## How it compares
+
+| | IPMG | `nmap -sn` | `fping` | Angry IP Scanner |
+| --- | --- | --- | --- | --- |
+| Parallel ping sweep | Yes | Yes | Yes | Yes |
+| Scan history and "what changed" | Built in | Save XML, compare with `ndiff` | No | No |
+| Reports | Excel, CSV, JSON, Markdown | XML, grepable text | Plain text | CSV, TXT, XML |
+| Browser UI | IPMG Web, local | No (Zenmap is a desktop app) | No | Desktop app (Java) |
+| Port checks | Common TCP ports | Full port and OS scanner | No | Via fetchers |
+
+Reach for nmap when you need a real port or OS scanner. Reach for IPMG when you
+look after a network and need to know what moved since yesterday, with a report
+you can hand to someone.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/sameeralam3127/ipmg/main/docs/assets/ipmg-web.png" alt="IPMG Web dashboard: scan totals, a status donut of 16 active, 1 timeout and 1 inactive host, a latency trend chart, and a list of recent scans" width="820">
+</p>
+
+---
+
 ## Install
 
 **Linux and macOS — one command, works on every distribution:**
@@ -280,6 +313,19 @@ exist yet. A file you name with `--input` must already exist.
 
 ## Common tasks
 
+Not sure which flags you need? The
+[command builder](https://sameeralam3127.github.io/ipmg/#builder) on the
+website puts the command together as you pick what you want to know, and
+explains every flag it adds.
+
+<p align="center">
+  <a href="https://sameeralam3127.github.io/ipmg/#builder">
+    <img src="https://raw.githubusercontent.com/sameeralam3127/ipmg/main/docs/assets/ipmg-builder.png" alt="IPMG command builder: choose Scan, Compare, History, or Web, enter a target such as 192.168.1.0/24, switch on options like live results or hostnames, and copy the generated ipmg command with each flag explained" width="820">
+  </a>
+</p>
+
+Or pick a ready-made command:
+
 | I want to… | Command |
 | --- | --- |
 | Scan the network I am on | `ipmg --discover` |
@@ -478,7 +524,16 @@ Status is one of `Active`, `Inactive`, `Timeout`, `Unreachable`, `Invalid IP`,
 or `Error`. `Hostname` is filled in when you pass `--resolve`.
 
 The `md` format produces a shareable Markdown report with a status summary
-table — handy for tickets, handoffs, and incident timelines.
+table — handy for tickets, handoffs, and incident timelines. `jsonl` writes one
+JSON object per line, which streams into `jq` and log pipelines.
+
+**Reports survive an interrupted scan.** A scan writes its report as it goes,
+so pressing Ctrl+C halfway through a /16 leaves a valid report of everything
+scanned so far instead of nothing at all. `csv` and `jsonl` are appended per
+host; `xlsx`, `json`, and `md` are re-saved every `--autosave` seconds (30 by
+default). A finished scan overwrites those files with the complete report, so
+the file names and contents are the same as they always were. Use
+`--no-incremental` to go back to writing only at the end.
 
 **Open ports.** `Open Ports` is only populated when `--scan-ports` is set: for
 each host that answers, IPMG probes a list of common TCP ports (SSH, HTTP,
@@ -507,7 +562,9 @@ them — so piping IPMG into a file or a log gives you clean text.
 | `--input` | `ip_list.xlsx` | What to scan: a file (`.xlsx`, `.xls`, `.csv`, `.txt`, `.list`), a single IP, a CIDR block, or a range (`10.0.0.1-10.0.0.50`) |
 | `--discover` | off | Auto-detect and scan the local subnet instead |
 | `--output` | `results` | Report file name prefix |
-| `--formats` | `xlsx` | One or more of `xlsx`, `csv`, `json`, `md` |
+| `--formats` | `xlsx` | One or more of `xlsx`, `csv`, `json`, `jsonl`, `md` |
+| `--no-incremental` | off | Only write the report once the scan has finished |
+| `--autosave` | `30` | How often a running scan re-saves `xlsx`, `json`, and `md` |
 
 **Speed and accuracy**
 

{ipmg-2.0.0 → ipmg-2.1.0}/README.md

@@ -12,8 +12,19 @@ can send to someone: Excel, CSV, JSON, or Markdown. It works from the command
 line or from IPMG Web, a local browser UI, and it remembers every scan so it can tell
 you what moved.
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/sameeralam3127/ipmg/main/docs/assets/ipmg-demo.gif" alt="ipmg scanning 13 hosts in parallel: live results with reverse DNS names and latency, then a summary of 10 active and 3 timed out" width="820">
+</p>
+
+**Why not `nmap -sn`, `fping`, or Angry IP Scanner?** They tell you what is up
+right now. IPMG also remembers every scan and tells you what changed since the
+last one: the host that dropped off, the device that appeared, the latency that
+doubled. It writes the report you would otherwise build by hand.
+[How it compares](#how-it-compares)
+
 **Website:** [sameeralam3127.github.io/ipmg](https://sameeralam3127.github.io/ipmg/) ·
-**Live demo:** [IPMG Web with sample data](https://sameeralam3127.github.io/ipmg/demo/)
+**Live demo:** [IPMG Web with sample data](https://sameeralam3127.github.io/ipmg/demo/) ·
+**Command builder:** [pick what you want, copy the command](https://sameeralam3127.github.io/ipmg/#builder)
 
 ```bash
 pip install ipmg
@@ -25,6 +36,7 @@ ipmg --discover        # scan the network you are on, right now
 
 **Contents**
 
+[How it compares](#how-it-compares) ·
 [Install](#install) ·
 [Your first scan](#your-first-scan) ·
 [Common tasks](#common-tasks) ·
@@ -40,6 +52,26 @@ ipmg --discover        # scan the network you are on, right now
 
 ---
 
+## How it compares
+
+| | IPMG | `nmap -sn` | `fping` | Angry IP Scanner |
+| --- | --- | --- | --- | --- |
+| Parallel ping sweep | Yes | Yes | Yes | Yes |
+| Scan history and "what changed" | Built in | Save XML, compare with `ndiff` | No | No |
+| Reports | Excel, CSV, JSON, Markdown | XML, grepable text | Plain text | CSV, TXT, XML |
+| Browser UI | IPMG Web, local | No (Zenmap is a desktop app) | No | Desktop app (Java) |
+| Port checks | Common TCP ports | Full port and OS scanner | No | Via fetchers |
+
+Reach for nmap when you need a real port or OS scanner. Reach for IPMG when you
+look after a network and need to know what moved since yesterday, with a report
+you can hand to someone.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/sameeralam3127/ipmg/main/docs/assets/ipmg-web.png" alt="IPMG Web dashboard: scan totals, a status donut of 16 active, 1 timeout and 1 inactive host, a latency trend chart, and a list of recent scans" width="820">
+</p>
+
+---
+
 ## Install
 
 **Linux and macOS — one command, works on every distribution:**
@@ -234,6 +266,19 @@ exist yet. A file you name with `--input` must already exist.
 
 ## Common tasks
 
+Not sure which flags you need? The
+[command builder](https://sameeralam3127.github.io/ipmg/#builder) on the
+website puts the command together as you pick what you want to know, and
+explains every flag it adds.
+
+<p align="center">
+  <a href="https://sameeralam3127.github.io/ipmg/#builder">
+    <img src="https://raw.githubusercontent.com/sameeralam3127/ipmg/main/docs/assets/ipmg-builder.png" alt="IPMG command builder: choose Scan, Compare, History, or Web, enter a target such as 192.168.1.0/24, switch on options like live results or hostnames, and copy the generated ipmg command with each flag explained" width="820">
+  </a>
+</p>
+
+Or pick a ready-made command:
+
 | I want to… | Command |
 | --- | --- |
 | Scan the network I am on | `ipmg --discover` |
@@ -432,7 +477,16 @@ Status is one of `Active`, `Inactive`, `Timeout`, `Unreachable`, `Invalid IP`,
 or `Error`. `Hostname` is filled in when you pass `--resolve`.
 
 The `md` format produces a shareable Markdown report with a status summary
-table — handy for tickets, handoffs, and incident timelines.
+table — handy for tickets, handoffs, and incident timelines. `jsonl` writes one
+JSON object per line, which streams into `jq` and log pipelines.
+
+**Reports survive an interrupted scan.** A scan writes its report as it goes,
+so pressing Ctrl+C halfway through a /16 leaves a valid report of everything
+scanned so far instead of nothing at all. `csv` and `jsonl` are appended per
+host; `xlsx`, `json`, and `md` are re-saved every `--autosave` seconds (30 by
+default). A finished scan overwrites those files with the complete report, so
+the file names and contents are the same as they always were. Use
+`--no-incremental` to go back to writing only at the end.
 
 **Open ports.** `Open Ports` is only populated when `--scan-ports` is set: for
 each host that answers, IPMG probes a list of common TCP ports (SSH, HTTP,
@@ -461,7 +515,9 @@ them — so piping IPMG into a file or a log gives you clean text.
 | `--input` | `ip_list.xlsx` | What to scan: a file (`.xlsx`, `.xls`, `.csv`, `.txt`, `.list`), a single IP, a CIDR block, or a range (`10.0.0.1-10.0.0.50`) |
 | `--discover` | off | Auto-detect and scan the local subnet instead |
 | `--output` | `results` | Report file name prefix |
-| `--formats` | `xlsx` | One or more of `xlsx`, `csv`, `json`, `md` |
+| `--formats` | `xlsx` | One or more of `xlsx`, `csv`, `json`, `jsonl`, `md` |
+| `--no-incremental` | off | Only write the report once the scan has finished |
+| `--autosave` | `30` | How often a running scan re-saves `xlsx`, `json`, and `md` |
 
 **Speed and accuracy**
 

{ipmg-2.0.0 → ipmg-2.1.0}/pyproject.toml

@@ -13,7 +13,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ipmg"
-version = "2.0.0"  # Managed automatically by semantic-release
+version = "2.1.0"  # Managed automatically by semantic-release
 description = "IP Management & Ping Monitoring CLI Tool"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -28,7 +28,7 @@ maintainers = [
     { name = "Sameer Alam", email = "sameeralam3127@gmail.com" }
 ]
 
-keywords = ["ip", "network", "ping", "monitoring", "cli", "port-scan"]
+keywords = ["ip", "network", "ping", "monitoring", "cli", "port-scan", "network-scanner", "ping-sweep", "subnet-scanner", "homelab", "sysadmin"]
 
 classifiers = [
     "Programming Language :: Python :: 3",
@@ -49,7 +49,7 @@ classifiers = [
 ]
 
 dependencies = [
-    "pandas>=2.0",
+    "pandas>=2.2.2",
     "openpyxl>=3.1",
     "rich>=13.0",
     "fastapi>=0.110",
@@ -68,6 +68,7 @@ Changelog = "https://github.com/sameeralam3127/ipmg/releases"
 [project.optional-dependencies]
 dev = [
     "pytest>=7.4",
+    "pytest-cov>=5.0",
     "ruff>=0.4",
     "pre-commit>=3.5.0",
     "python-semantic-release>=10.5.3",
@@ -85,6 +86,7 @@ ipmg = "ipmg.cli.commands:run"
 [dependency-groups]
 dev = [
     "pytest>=7.4",
+    "pytest-cov>=5.0",
     "ruff>=0.4",
     "pre-commit>=3.5.0",
     "python-semantic-release>=10.5.3",
@@ -130,6 +132,14 @@ where = ["src"]
 testpaths = ["tests"]
 pythonpath = ["src"]
 
+[tool.coverage.run]
+source = ["ipmg"]
+branch = true
+
+[tool.coverage.report]
+# Current coverage is ~95%; this floor catches a large untested addition.
+fail_under = 90
+
 
 # ==========================================================
 # Ruff

{ipmg-2.0.0 → ipmg-2.1.0}/src/ipmg/__init__.py

@@ -2,4 +2,4 @@
 ipmg - IP Management & Ping Monitoring Tool
 """
 
-__version__ = "2.0.0"
+__version__ = "2.1.0"

{ipmg-2.0.0 → ipmg-2.1.0}/src/ipmg/cli/parser.py

@@ -7,6 +7,12 @@ import argparse
 from ipmg import __version__
 from ipmg.core.portscan import DEFAULT_PORTS, parse_port_list
 from ipmg.infrastructure.file_io import DEFAULT_INPUT_FILE
+from ipmg.infrastructure.incremental import (
+    DEFAULT_AUTOSAVE_S,
+    MAX_AUTOSAVE_S,
+    MIN_AUTOSAVE_S,
+    REPORT_FORMATS,
+)
 from ipmg.reporting.diff_report import DIFF_FORMATS
 from ipmg.reporting.live import DEFAULT_REFRESH_S, MAX_REFRESH_S, MIN_REFRESH_S
 
@@ -135,9 +141,9 @@ def build_parser() -> argparse.ArgumentParser:
         "--formats",
         nargs="+",
         default=["xlsx"],
-        choices=["xlsx", "csv", "json", "md"],
+        choices=list(REPORT_FORMATS),
         metavar="FORMAT",
-        help="One or more report formats: xlsx, csv, json, md (default: xlsx).",
+        help=f"One or more report formats: {', '.join(REPORT_FORMATS)} (default: xlsx).",
     )
     parser.add_argument(
         "--discover",
@@ -196,6 +202,24 @@ def build_parser() -> argparse.ArgumentParser:
         help="Connect timeout per port when --scan-ports is set (default: 1).",
     )
 
+    reports = parser.add_argument_group("report writing")
+    reports.add_argument(
+        "--no-incremental",
+        action="store_true",
+        help="Only write the report once the scan has finished.",
+    )
+    reports.add_argument(
+        "--autosave",
+        type=float,
+        default=DEFAULT_AUTOSAVE_S,
+        metavar="SECONDS",
+        help=(
+            "How often a running scan re-saves the xlsx, json, and md reports "
+            f"(default: {DEFAULT_AUTOSAVE_S:g}, range: {MIN_AUTOSAVE_S:g}-{MAX_AUTOSAVE_S:g}). "
+            "csv and jsonl are written per host regardless."
+        ),
+    )
+
     live = parser.add_argument_group("live output")
     live.add_argument(
         "--stream",

{ipmg-2.0.0 → ipmg-2.1.0}/src/ipmg/core/engine.py

@@ -95,6 +95,12 @@ def execute_scan(
 
             if on_result is not None:
                 on_result(result, len(results), len(ips))
+    except BaseException:
+        # Ctrl+C must not be followed by minutes of queued pings: drop the
+        # hosts that have not started, and let the finally below wait only
+        # for the handful already in flight.
+        executor.shutdown(wait=False, cancel_futures=True)
+        raise
     finally:
         executor.shutdown(wait=True)
 

{ipmg-2.0.0 → ipmg-2.1.0}/src/ipmg/infrastructure/file_io.py

@@ -1,3 +1,6 @@
+from __future__ import annotations
+
+import io
 import ipaddress
 from pathlib import Path
 from typing import Iterable
@@ -6,6 +9,7 @@ import pandas as pd
 
 from ipmg.core.ping import validate_ip
 from ipmg.exceptions import FileIOError
+from ipmg.infrastructure.incremental import atomic_write_bytes, jsonl_record
 from ipmg.reporting import ui
 from ipmg.utils.helpers import markdown_cell, spreadsheet_escape, timestamp_str
 
@@ -270,24 +274,50 @@ def build_markdown_report(df: pd.DataFrame) -> str:
     return "\n".join(lines)
 
 
-def save_results(df, base: str, formats: list[str]) -> list[str]:
-    ts = timestamp_str()
+def write_report(df: pd.DataFrame, path: str, fmt: str) -> None:
+    """Write ``df`` to ``path`` in one format, replacing the file atomically.
+
+    The whole file is rendered in memory and swapped into place, so a reader
+    — or an incremental snapshot interrupted halfway — never finds a report
+    that is only partly written. Raises :class:`ValueError` for an unknown
+    format so callers can tell "not written" from "silently skipped".
+    """
+    if fmt == "xlsx":
+        buffer = io.BytesIO()
+        sanitize_export_frame(df).to_excel(buffer, index=False)
+        data = buffer.getvalue()
+    elif fmt == "csv":
+        data = sanitize_export_frame(df).to_csv(index=False).encode("utf-8")
+    elif fmt == "json":
+        data = df.to_json(orient="records").encode("utf-8")
+    elif fmt == "jsonl":
+        # Rendered row by row rather than through pandas, so the finished file
+        # is written exactly like the one a running scan appends to.
+        rows = df.astype(object).where(pd.notna(df), None).to_dict(orient="records")
+        data = "".join(jsonl_record(row) for row in rows).encode("utf-8")
+    elif fmt == "md":
+        data = build_markdown_report(df).encode("utf-8")
+    else:
+        raise ValueError(f"Unsupported report format: {fmt}")
+
+    atomic_write_bytes(path, data)
+
+
+def save_results(df, base: str, formats: list[str], timestamp: str | None = None) -> list[str]:
+    """Write the finished report in every requested format.
+
+    ``timestamp`` is passed in when a scan has already been writing reports
+    incrementally, so the final write lands on those same files instead of
+    creating a second, differently named set.
+    """
+    ts = timestamp or timestamp_str()
     saved_paths: list[str] = []
 
     for fmt in formats:
-        if fmt == "xlsx":
-            output_path = f"{base}_{ts}.xlsx"
-            sanitize_export_frame(df).to_excel(output_path, index=False)
-        elif fmt == "csv":
-            output_path = f"{base}_{ts}.csv"
-            sanitize_export_frame(df).to_csv(output_path, index=False)
-        elif fmt == "json":
-            output_path = f"{base}_{ts}.json"
-            df.to_json(output_path, orient="records")
-        elif fmt == "md":
-            output_path = f"{base}_{ts}.md"
-            Path(output_path).write_text(build_markdown_report(df), encoding="utf-8")
-        else:
+        output_path = f"{base}_{ts}.{fmt}"
+        try:
+            write_report(df, output_path, fmt)
+        except ValueError:
             continue
 
         saved_paths.append(output_path)