netshow 0.2.2__tar.gz → 0.3.0__tar.gz

netshow-0.3.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+.venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+build/
+dist/
+*.egg-info/
+.coverage
+htmlcov/
+.DS_Store

netshow-0.3.0/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.5
+Name: netshow
+Version: 0.3.0
+Summary: An interactive, process-aware network monitor for your terminal
+Project-URL: Homepage, https://github.com/taylorwilsdon/netshow
+Project-URL: Issues, https://github.com/taylorwilsdon/netshow/issues
+Author: Taylor Wilsdon
+License-Expression: MIT
+License-File: LICENSE
+Keywords: connections,monitoring,network,tui
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: System :: Networking :: Monitoring
+Requires-Python: >=3.11
+Requires-Dist: psutil<8,>=7.2.2
+Requires-Dist: rich<15,>=14.3
+Requires-Dist: textual<9,>=8.2.8
+Description-Content-Type: text/markdown
+
+<div align="center">
+<img width="50%" src="https://github.com/user-attachments/assets/51b8f028-2d25-4664-b4a1-44dcf9490140" alt="netshow" />
+
+**Interactive, process-aware network monitoring for your terminal.**
+
+Python 3.11+ · macOS & Linux · Built with Textual
+</div>
+
+![Netshow connection monitor showing example connections](docs/assets/connections.svg)
+
+> This checkout contains the UI refresh in development. Screenshots use example data.
+> `uvx netshow` runs the published release; use the source instructions below to try this version.
+
+## Install and run
+
+```sh
+uvx netshow
+```
+
+For this development version:
+
+```sh
+git clone https://github.com/taylorwilsdon/netshow.git
+cd netshow
+uv sync --locked
+uv run netshow
+```
+
+Or install the published package with `pipx install netshow`.
+
+## What it shows
+
+- Live TCP connections with PID, friendly service name, process, endpoints, and status.
+- Process details including executable, owner, command, working directory, threads, and live CPU/memory usage.
+- Host or interface bandwidth: separate receive/transmit rates and a 30-second sparkline.
+- Regex search across PID, names, addresses, and status; invalid patterns fall back to literal matching.
+- Process/status sorting that preserves your selection, plus full IPv6 details.
+- Confirmed process termination with a separate force-kill option if the process stays alive.
+- The original Selenized Dark palette and labeled metric chips, built-in light/dark/ANSI themes, and a compact layout for small terminals.
+
+Netshow tries psutil first and falls back to `lsof` when access is denied, as is common
+on macOS. Install `lsof` if your system doesn't include it. Without sufficient privileges,
+results may be incomplete; the status line marks limited visibility. Collection failures
+show an error and retain the last successful snapshot, marked stale.
+
+Bandwidth is measured for the entire host or chosen interface. It is **not per-process
+or per-connection throughput**. Summing interfaces may count traffic at multiple layers
+on hosts with bridges, tunnels, or virtual interfaces.
+
+## Usage
+
+```sh
+netshow --interval 1.5
+netshow --no-colors
+netshow --version
+```
+
+| Option | Behavior | Default |
+| --- | --- | --- |
+| `--interval SECONDS` | Positive, finite connection refresh interval | `3.0` |
+| `--no-colors` | Monochrome rendering; also enabled by a nonempty `NO_COLOR` | Off |
+| `--version` | Print installed version and exit | — |
+
+Bandwidth samples every 0.5 seconds while the connection screen is visible.
+Connection collection pauses during details/dialogs and resumes immediately on return.
+Process details refresh every second while visible.
+
+| Key | Action |
+| --- | --- |
+| ↑ / ↓ | Select a connection |
+| Enter | Open selected connection details |
+| Click | Highlight a row; click the highlighted row again to open details |
+| Esc / ← | Return from details |
+| Ctrl+R | Refresh the current connection/detail view |
+| `/` / `f` | Open search / toggle search field |
+| Enter in search | Return focus to the table |
+| Esc in search | Hide the field; the active filter remains visible in the status line |
+| `s` / `p` | Toggle status / process sorting; press again for default PID order |
+| `i` | Cycle bandwidth interfaces |
+| `e` | Toggle status symbols |
+| `v` | Toggle full IPv6 addresses in the table |
+| `k` | Confirm termination of the selected process |
+| `?` | Toggle contextual keyboard help |
+| Ctrl+P | Command palette, including theme selection |
+| `q` / Ctrl+C | Quit |
+
+Clear the search text to remove the filter. Settings last for the current session.
+Single-letter shortcuts leave typing in the search field uninterrupted.
+
+## Terminate a process
+
+Select a connection and press `k`, or use **Terminate process…** in its detail view.
+The dialog identifies the process and defaults to **Cancel**. Confirming **Terminate**
+sends SIGTERM and waits up to three seconds. If it remains alive, a second confirmation
+offers **Force kill**, which sends SIGKILL. Netshow never escalates automatically.
+
+![Process termination confirmation using example data](docs/assets/terminate.svg)
+
+The action affects the whole process and all its connections, so unsaved work may be
+lost. Netshow rechecks PID and creation time before each signal, blocks unknown identities,
+PID 0/1, and itself, and reports permission failures or exited/replaced processes.
+It does not terminate process trees or request elevated privileges.
+
+## Development
+
+```sh
+uv sync --locked
+uv run ruff format --check .
+uv run ruff check .
+uv run mypy src
+uv run pytest -q
+uv build
+```
+
+Run `uv run ruff format .` to format changes. CI tests Python 3.11–3.14 on Linux and
+Python 3.14 on macOS, and verifies installations from both wheel and source artifacts.
+Tests use synthetic connection data; process-control integration tests act only on
+children they start themselves.
+
+See [architecture](docs/architecture.md) and [release instructions](docs/releasing.md).
+The earlier published version remains available for Python 3.9/3.10 users.
+
+## License
+
+[MIT](LICENSE). Issues and contributions are welcome on
+[GitHub](https://github.com/taylorwilsdon/netshow/issues).

netshow-0.3.0/README.md

@@ -0,0 +1,126 @@
+<div align="center">
+<img width="50%" src="https://github.com/user-attachments/assets/51b8f028-2d25-4664-b4a1-44dcf9490140" alt="netshow" />
+
+**Interactive, process-aware network monitoring for your terminal.**
+
+Python 3.11+ · macOS & Linux · Built with Textual
+</div>
+
+![Netshow connection monitor showing example connections](docs/assets/connections.svg)
+
+> This checkout contains the UI refresh in development. Screenshots use example data.
+> `uvx netshow` runs the published release; use the source instructions below to try this version.
+
+## Install and run
+
+```sh
+uvx netshow
+```
+
+For this development version:
+
+```sh
+git clone https://github.com/taylorwilsdon/netshow.git
+cd netshow
+uv sync --locked
+uv run netshow
+```
+
+Or install the published package with `pipx install netshow`.
+
+## What it shows
+
+- Live TCP connections with PID, friendly service name, process, endpoints, and status.
+- Process details including executable, owner, command, working directory, threads, and live CPU/memory usage.
+- Host or interface bandwidth: separate receive/transmit rates and a 30-second sparkline.
+- Regex search across PID, names, addresses, and status; invalid patterns fall back to literal matching.
+- Process/status sorting that preserves your selection, plus full IPv6 details.
+- Confirmed process termination with a separate force-kill option if the process stays alive.
+- The original Selenized Dark palette and labeled metric chips, built-in light/dark/ANSI themes, and a compact layout for small terminals.
+
+Netshow tries psutil first and falls back to `lsof` when access is denied, as is common
+on macOS. Install `lsof` if your system doesn't include it. Without sufficient privileges,
+results may be incomplete; the status line marks limited visibility. Collection failures
+show an error and retain the last successful snapshot, marked stale.
+
+Bandwidth is measured for the entire host or chosen interface. It is **not per-process
+or per-connection throughput**. Summing interfaces may count traffic at multiple layers
+on hosts with bridges, tunnels, or virtual interfaces.
+
+## Usage
+
+```sh
+netshow --interval 1.5
+netshow --no-colors
+netshow --version
+```
+
+| Option | Behavior | Default |
+| --- | --- | --- |
+| `--interval SECONDS` | Positive, finite connection refresh interval | `3.0` |
+| `--no-colors` | Monochrome rendering; also enabled by a nonempty `NO_COLOR` | Off |
+| `--version` | Print installed version and exit | — |
+
+Bandwidth samples every 0.5 seconds while the connection screen is visible.
+Connection collection pauses during details/dialogs and resumes immediately on return.
+Process details refresh every second while visible.
+
+| Key | Action |
+| --- | --- |
+| ↑ / ↓ | Select a connection |
+| Enter | Open selected connection details |
+| Click | Highlight a row; click the highlighted row again to open details |
+| Esc / ← | Return from details |
+| Ctrl+R | Refresh the current connection/detail view |
+| `/` / `f` | Open search / toggle search field |
+| Enter in search | Return focus to the table |
+| Esc in search | Hide the field; the active filter remains visible in the status line |
+| `s` / `p` | Toggle status / process sorting; press again for default PID order |
+| `i` | Cycle bandwidth interfaces |
+| `e` | Toggle status symbols |
+| `v` | Toggle full IPv6 addresses in the table |
+| `k` | Confirm termination of the selected process |
+| `?` | Toggle contextual keyboard help |
+| Ctrl+P | Command palette, including theme selection |
+| `q` / Ctrl+C | Quit |
+
+Clear the search text to remove the filter. Settings last for the current session.
+Single-letter shortcuts leave typing in the search field uninterrupted.
+
+## Terminate a process
+
+Select a connection and press `k`, or use **Terminate process…** in its detail view.
+The dialog identifies the process and defaults to **Cancel**. Confirming **Terminate**
+sends SIGTERM and waits up to three seconds. If it remains alive, a second confirmation
+offers **Force kill**, which sends SIGKILL. Netshow never escalates automatically.
+
+![Process termination confirmation using example data](docs/assets/terminate.svg)
+
+The action affects the whole process and all its connections, so unsaved work may be
+lost. Netshow rechecks PID and creation time before each signal, blocks unknown identities,
+PID 0/1, and itself, and reports permission failures or exited/replaced processes.
+It does not terminate process trees or request elevated privileges.
+
+## Development
+
+```sh
+uv sync --locked
+uv run ruff format --check .
+uv run ruff check .
+uv run mypy src
+uv run pytest -q
+uv build
+```
+
+Run `uv run ruff format .` to format changes. CI tests Python 3.11–3.14 on Linux and
+Python 3.14 on macOS, and verifies installations from both wheel and source artifacts.
+Tests use synthetic connection data; process-control integration tests act only on
+children they start themselves.
+
+See [architecture](docs/architecture.md) and [release instructions](docs/releasing.md).
+The earlier published version remains available for Python 3.9/3.10 users.
+
+## License
+
+[MIT](LICENSE). Issues and contributions are welcome on
+[GitHub](https://github.com/taylorwilsdon/netshow/issues).

netshow-0.3.0/docs/architecture.md

@@ -0,0 +1,29 @@
+# Architecture
+
+`NetshowApp` owns the theme, command palette, and screen stack. `ConnectionsScreen`
+owns a complete immutable snapshot plus filter/sort state. One collection worker runs
+at a time; refresh requests coalesce. Suspending the screen invalidates in-flight
+results, and resuming triggers a fresh collection. Collection errors retain the last
+successful snapshot and show its stale status.
+
+Collectors normalize psutil and NUL-delimited lsof output into `Connection` records.
+Each refresh reuses process metadata for repeated PIDs. Docker discovery is bounded
+and cached for 30 seconds. A non-root collector may see only part of the system;
+netshow states this explicitly. lsof and Docker commands have timeouts.
+
+`ConnectionTable` maps row keys to records. Formatting never becomes the source of
+process identity or addresses. Filtering/sorting operate locally; table updates preserve
+selection by identity and update only changed cells. TCSS uses Textual theme variables.
+
+`BandwidthSampler` owns a separate counter baseline and 60-sample history. A single
+worker samples every half-second while the connection screen is active. Rendering and
+resizing never sample counters. RX/TX are host/interface totals, not process throughput.
+
+`ProcessInspector` retains its CPU baseline and reports unavailable fields individually.
+Termination uses PID plus creation time, revalidated before every signal. The confirmation
+screen submits at most one request at a time. A timeout offers a new explicit force-kill
+confirmation with Cancel focused. Process trees and privilege escalation are unsupported.
+
+Tests use deterministic collection fixtures and Textual Pilot. Only the explicit child
+integration tests signal real processes, and those processes are created by the tests.
+`scripts/smoke_install.py` verifies metadata, packaged TCSS, and startup from built artifacts.