Metadata-Version: 2.4
Name: xping
Version: 1.2.5
Summary: Beautiful CLI network diagnostics — ping, traceroute, network scanning, port scanning, TCP checks, 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,tcp,portscan,ipscan,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: Operating System :: Microsoft :: Windows
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
Requires-Dist: certifi
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Dynamic: license-file

# xping

**Beautiful CLI network diagnostics — ping, traceroute, network scanning, port scanning, TCP checks, and DNS lookup.**

Zero external Python dependencies. Pure stdlib. Linux, macOS & Windows.

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

Created by **[Meh Askari](https://github.com/mehaskari)** — see [LICENSE](LICENSE) for attribution terms.

---

## Features

- **Ping** — Live per-packet latency bars, animated spinner, sparkline chart, full statistics
- **Traceroute** — Real-time hop-by-hop path with RTT colour coding and summary
- **DNS Lookup** — A, AAAA, MX, NS, TXT (SPF / DMARC / DKIM) with reverse DNS
- **TCP Connect** — Live TCP port checks with connect timing, success rate, and timeline
- **Port Scanner** — Concurrent TCP port scans with service names and open-port summary
- **IP Scan** — Discover live hosts across CIDR blocks or IP ranges using ICMP echo probes
- **IP Sweep** — Scan CIDR blocks or IP ranges for hosts with open TCP services
- **All-in-one** — Run lookup, ping, trace, and TCP checks in a single command
- **Dependency checker** — `xping deps` detects missing tools and shows the correct install command for your distro
- **Zero Python deps** — stdlib only (Python ≥ 3.10)
- **True-colour output** — ANSI 24-bit colour, animated spinners, live sparklines
- **man page included** — `man xping` works after installation
- **Machine-readable export** — `--json`, `--csv`, and `--markdown` on every diagnostic command

---

## Windows

XPing is a first-class citizen on Windows. TCP, port scan, sweep, and DNS fallback work out of the box with Python 3.10+.

For ICMP ping and traceroute, install the built-in optional tools or let xping use subprocess fallbacks:

```powershell
pipx install xping
xping ping 1.1.1.1
xping trace cloudflare.com
xping deps
```

`xping deps` prints install hints for missing `ping`, `tracert`, and `dig` when available through winget or chocolatey.

## Installation

### Ubuntu / Debian / Linux Mint / Pop!\_OS — PPA (recommended)

```bash
sudo add-apt-repository ppa:mehdiaskari/xping
sudo apt update
sudo apt install python3-xping
```

Supported: Ubuntu 22.04 LTS, 24.04 LTS, Linux Mint 21+, Pop!\_OS 22.04+

### PyPI (all platforms)

```bash
pipx install xping
```

### From source

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

### Arch Linux (AUR)

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

### Manual page (source installs)

```bash
sudo cp man/xping.1 /usr/share/man/man1/
sudo gzip /usr/share/man/man1/xping.1
sudo mandb
man 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     # 200 ms interval
xping ping host.local -t 5        # 5 s 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
```

### TCP Connectivity

```bash
xping tcp example.com 443
xping tcp db.internal 5432 -c 5   # 5 connection attempts
xping tcp api.example.com 8443 -t 3 -i 1
```

### Port Scan

```bash
xping portscan example.com
xping portscan example.com --ports 22,80,443
xping portscan 10.0.0.5 --ports 1-1024 -t 0.3 -w 200
```

### IP Scan

```bash
xping ipscan 192.168.1.0/24
xping ipscan 10.0.0.10-10.0.0.50 -t 0.5 -w 128
xping ipscan 172.16.0.0/24 --limit 512
```

### IP Sweep

```bash
xping sweep 192.168.1.0/24
xping sweep 10.0.0.10-10.0.0.50 --ports 22,80,443
xping sweep 172.16.0.0/24 --ports 3389,5985 --limit 512
```

### All at once

```bash
xping all cloudflare.com
xping all example.com --json
```

Runs full DNS lookup, 4-packet ping, traceroute, and TCP checks on ports 443 and 80.

### Export formats

Every diagnostic command accepts structured output flags (interactive rendering is suppressed):

```bash
xping ping 1.1.1.1 --json
xping trace example.com --csv
xping lookup github.com --full --markdown
xping all cloudflare.com --json
```

### Dependency check

```bash
xping deps
```

---

## Permissions

ICMP raw sockets require root or `cap_net_raw`. Without them xping
automatically falls back to the system `ping` / `traceroute` binaries.

Grant capability without running as root:

```bash
sudo setcap cap_net_raw+ep $(which xping)
```

---

## Environment variables

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

---

## Contributing

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

---

## License

MIT with Mandatory Attribution — see [LICENSE](LICENSE).

Any fork, derivative work, or redistribution must visibly credit
**Meh Askari \<mehdiaskari@outlook.com\>**.
