Metadata-Version: 2.4
Name: ifpretty
Version: 0.9.0
Summary: Prettify and enrich ifconfig output: aligned tables, IP/MAC/scope annotations, OUI vendor lookup, live DNS/DHCP/route, and a 1h bandwidth graph.
Author-email: iklo <tiktachack@gmail.com>
License: MIT
Keywords: ifconfig,network,networking,cli,terminal,rich,macos
Classifier: Environment :: Console
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: System :: Networking
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rich>=13
Dynamic: license-file

# ifpretty

Prettify and **enrich** `ifconfig` output — aligned tables, color, decoded flags,
IP/MAC/scope annotations, OUI vendor lookup, live DNS/DHCP/route, a 1‑hour
bandwidth graph, and run‑to‑run diffing. Built on
[rich](https://github.com/Textualize/rich).

```
ifpretty
```

The default is an **essentials view**: identity, routable IPs (with scope),
gateway and throughput, with down / address‑less interfaces collapsed to one
line. Pass `-v` for every field.

## Install

```sh
pip install ifpretty
```

Requires Python ≥ 3.9. The only dependency is `rich`.

## Usage

```sh
ifpretty                       # essentials view; runs `ifconfig` for you
ifpretty -v                    # verbose: every field + expand collapsed interfaces
ifpretty en0 en6               # limit to one or more interfaces
ifconfig | ifpretty            # or pipe ifconfig in yourself

ifpretty -r                    # --records : compact label/value record layout
ifpretty -t                    # --table   : single wide table, all fields (<=240 cols)

ifpretty -l                    # --live    : route, traffic, friendly names, DNS, DHCP (macOS)
ifpretty -c                    # --check   : ping the default gateway for latency (macOS)
ifpretty -w                    # --wan     : public IP / ASN / geo (opt-in; sends IP to ipapi.co)
ifpretty -d                    # --diff    : show what changed since the previous run
ifpretty -x                    # --explain : append a legend for the flags/options seen
ifpretty --map                 # open an interactive browser map of your network
ifpretty --map 8.8.8.8         # …tracing the route to a specific target

ifpretty --record              # sample byte counters (run via cron to feed the 1h graph)
ifpretty --update-oui          # refresh the IEEE vendor database into the cache
```

Run it bare and it runs `ifconfig` for you; or pipe `ifconfig` in to control
which interfaces to show. Flags compose (e.g. `ifpretty -l -d -w`).

## What it adds

**Always on (offline, deterministic):**

- Per‑interface **role** (loopback / Ethernet·Wi‑Fi / VPN·tunnel / bridge / …).
- **IP scope** for every address — loopback / link‑local / ULA / private / global —
  plus IPv4 network + usable‑host count.
- **MAC** kind (universal vs locally‑administered), **OUI vendor** (bundled IEEE
  registry, no network), shared‑MAC notes (e.g. bridge members), and EUI‑64 detection.
- **Media** speed/duplex with a half‑duplex ⚠ warning; jumbo / sub‑1280 MTU notes.
- Decoded flag/option/nd6 bitfields; IPv6 attributes aligned into columns.
- A one‑line **overview** above the layout (interface count, default route, totals).

**`--live` (macOS, cross‑references the system):**

- Default route + gateway, friendly hardware‑port names, per‑interface DNS and
  search domains, DHCP server + lease, traffic counters (bytes + packets) and
  error/collision counts.

**`--check`:** pings the default gateway and reports latency / unreachable.

**`--wan` (external, opt‑in):** looks up your public IP plus ASN/ISP/geo via
`ipapi.co` and shows it in the overview. It sends your public IP to a third
party, so it is strictly opt‑in; the result is cached ~1 h, times out fast, and
degrades silently offline. `--update-oui` refreshes the vendor database from the
IEEE registry into the cache (overrides the bundled copy).

**`--diff`:** every run records a snapshot of the *stable* interface state
(up/down, addresses, MAC, mtu, media, gateway — **not** volatile counters) to
`snapshot.json`. With `--diff`, ifpretty prints what changed since the previous
run — interfaces added/removed, status flips, added/removed IPv4/IPv6 addresses —
before the normal view.

**1‑hour bandwidth graph:** schedule the recorder, then per‑interface Unicode
sparklines (and a link‑utilization gauge) appear automatically:

```sh
# once, e.g. in `crontab -e` — use the absolute path:
* * * * * $(command -v ifpretty) --record
```

```
1h in    ▁▁▁▂▄█▅▂▁▁▁▁   peak 10.0 Mbps
1h out   ▁▂▂▄▆█▄▂▂▁▁▁   peak 533.3 Kbps
link use ████░░░░░░     40% of 1000 Mbps
```

**`--map` (browser visualization):** opens an interactive graph of your network —
this host and its interfaces, the LAN devices/peripherals each interface talks to
(from the ARP table, labelled by OUI vendor), the default gateway, and the
**traceroute path out to the internet** (default target `1.1.1.1`, or pass one).
Rendered with [vis-network](https://visjs.github.io/vis-network/) (loaded from a
CDN) into a self-contained HTML file that opens automatically in your browser.

## Environment

- `NO_COLOR=1` disables color; `CLICOLOR_FORCE=1` forces it when piped.
- `IFPRETTY_HISTORY` — bandwidth‑samples file (default `~/.cache/ifpretty/samples.csv`).
- `IFPRETTY_CACHE` — cache directory for the WAN lookup, refreshed OUI DB, and
  the diff snapshot (default `~/.cache/ifpretty/`).

`--live` / `--check` / `--record` use macOS tools (`route`, `netstat`,
`networksetup`, `scutil`, `ipconfig`, `ping`) and no‑op (or degrade) elsewhere;
the parsing, formatting and offline enrichment work wherever you can pipe
`ifconfig` output in.

## Architecture

The package is split into focused modules (one responsibility each):

| Module | Responsibility |
|---|---|
| `model` | dataclasses `Inet` / `Inet6` / `Interface` |
| `parse` | raw `ifconfig` text → interface model |
| `enrich` | derivations, OUI, system (`--live`/`--check`), history, `--wan`, snapshot/diff |
| `formatting` | model values → styled (rich‑markup) strings; layout field rows |
| `render` | render strategies (boxed / records / table) + overview / legend / diff |
| `topology` | `--map`: traceroute + ARP → vis-network HTML graph in the browser |
| `cli` | acquire input → parse → enrich → render |

Dependency direction: `model ← parse, enrich ← formatting ← render ← cli` (no cycles).

## Development

```sh
python3 -m unittest discover -s tests   # 67 tests (snapshot + unit)
ruff check src tests && mypy src
```

Layout snapshots are pinned to golden files; regenerate intentionally with
`REGEN=1 python3 tests/test_ifpretty.py`.

## License

MIT
