Metadata-Version: 2.4
Name: xping
Version: 1.0.2
Summary: Beautiful CLI network diagnostics — ping, traceroute, and DNS lookup
Author-email: Meh Askari <mehdiaskari@outlook.com>
License: MIT with Mandatory Attribution
Project-URL: Homepage, https://github.com/mehaskari/xping
Project-URL: Repository, https://github.com/mehaskari/xping
Project-URL: Issues, https://github.com/mehaskari/xping/issues
Keywords: ping,traceroute,dns,network,cli,diagnostics
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: System Administrators
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Networking
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# xping 🏓

**Beautiful CLI network diagnostics — ping, traceroute, and DNS lookup.**

Zero external dependencies. Pure Python stdlib. Works on Linux and macOS.

```
  ██╗  ██╗██████╗ ██╗███╗   ██╗ ██████╗ 
  ╚██╗██╔╝██╔══██╗██║████╗  ██║██╔════╝ 
   ╚███╔╝ ██████╔╝██║██╔██╗ ██║██║  ███╗
   ██╔██╗ ██╔═══╝ ██║██║╚██╗██║██║   ██║
  ██╔╝ ██╗██║     ██║██║ ╚████║╚██████╔╝
  ╚═╝  ╚═╝╚═╝     ╚═╝╚═╝  ╚═══╝ ╚═════╝ 
  network diagnostics  ·  beautiful by default
```

---

## Features

- **Ping** — ICMP echo with live latency bars, sparkline chart, and statistics
- **Traceroute** — Hop-by-hop path with RTT coloring and summary
- **DNS Lookup** — A, AAAA, MX, NS, TXT (SPF/DMARC/DKIM) records
- **All-in-one** — Run all three in one command
- **Zero dependencies** — stdlib only (Python ≥ 3.10)
- **Beautiful output** — True-colour ANSI, tables, sparklines, badges

---

## Installation

### From PyPI

```bash
pip install xping
```

### From source

```bash
git clone https://github.com/mehaskari/xping
cd xping
pip install .
```

### On Arch Linux (AUR)

```bash
yay -S python-xping
```

### On Debian / Ubuntu (manual .deb)

```bash
# Build the wheel first, then install with pipx for clean isolation
pipx install xping
```

---

## Usage

```
xping <command> <host> [options]
```

### Ping

```bash
xping ping google.com
xping ping 1.1.1.1 -c 10          # 10 packets
xping ping example.com -i 0.2     # 200ms interval
xping ping host.local -t 5        # 5s timeout
```

### Traceroute

```bash
xping trace google.com
xping trace 8.8.8.8 --max-hops 15
xping trace example.com --probes 5
```

### DNS Lookup

```bash
xping lookup github.com
xping lookup github.com --full    # includes TXT / SPF / DMARC / DKIM
```

### All at once

```bash
xping all cloudflare.com
```

---

## Permissions

ICMP raw sockets require either:
- Running as **root** (`sudo xping ping …`)
- The `cap_net_raw` capability: `sudo setcap cap_net_raw+ep $(which xping)`

Without these, xping automatically falls back to the system `ping` / `traceroute`
binaries, so it always works.

---

## Output samples

### Ping
```
 ◉  PING  google.com
  Target              google.com
  IP address          142.250.185.78
  Packets             5

  [  1]  ✔  142.250.185.78  ████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░  42.11 ms
  [  2]  ✔  142.250.185.78  ████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░  40.87 ms
  ...

  ┌──────────────────┬──────────────────┐
  │ Metric           │ Value            │
  ├──────────────────┼──────────────────┤
  │ Packets sent     │ 5                │
  │ Packets recv     │ 5                │
  │ Packet loss      │ 0.0%             │
  │ Min RTT          │ 38.22 ms         │
  │ Avg RTT          │ 41.05 ms         │
  │ Max RTT          │ 44.91 ms         │
  │ Jitter           │ 1.83 ms          │
  └──────────────────┴──────────────────┘

  Latency sparkline:
  ▅▄▅▅▅
```

### DNS Lookup
```
 ◑  DNS LOOKUP  github.com

  ╔═ IPv4 (A records) ────────────────────────────
  ┌────────────────┬───────────────────────┬──────┐
  │ IPv4 Address   │ Reverse DNS           │ TTL  │
  ├────────────────┼───────────────────────┼──────┤
  │ 140.82.121.4   │ lb-140-82-121-4.g...  │ 60s  │
  └────────────────┴───────────────────────┴──────┘
```

---

## Environment variables

| Variable          | Effect                              |
|-------------------|-------------------------------------|
| `NO_COLOR`        | Disable all ANSI colour output      |
| `XPING_DEBUG`  | Print full tracebacks on errors     |

---

## Contributing

1. Fork and clone the repo
2. `pip install -e ".[dev]"`
3. Make your changes
4. Run `python -m pytest tests/`
5. Open a pull request

---

## License

MIT — see [LICENSE](LICENSE)
