NetPing

NetPing

NetPing is a Python package and CLI for advanced ping diagnostics, website reachability analysis, and practical network optimization suggestions.

It focuses on four things:

• Measuring latency, jitter, and packet loss with the system ping tool
• Timing DNS resolution and collecting address metadata
• Checking TCP reachability for application-facing ports such as 443
• Generating actionable recommendations and a weighted network health score

Features

• Cross-platform ping execution through the operating system ping utility
• Summary statistics for latency, jitter, packet loss, percentile tail latency, deviation, and stability
• DNS lookup timing, forward resolution, and reverse DNS lookups
• TCP connectivity timing for arbitrary ports
• Optional path MTU probing where the local platform supports "do not fragment" pings
• Parallel website batch diagnostics with profile-based target groups
• Config-backed CLI defaults via netping init
• Text and JSON CLI output
• Reusable Python API

Installation

pip install NetPing

For local development:

python -m pip install -e .[dev]

Quick Start

Run a simple diagnostic:

netping diagnose 1.1.1.1

Run more samples and print JSON:

netping diagnose example.com --count 8 --tcp-port 443 --tcp-port 8443 --json

Run a batch check against common websites:

netping websites --profile general --workers 4

Run a custom list of sites:

netping websites --target github.com --target python.org --sort-by latency --json

Probe the path MTU in addition to standard diagnostics:

netping diagnose 8.8.8.8 --probe-mtu

Initialize the local config after installation:

netping init

List built-in profiles and inspect the active config:

netping profiles
netping config

Use it from Python:

from netping import diagnose_target

report = diagnose_target(
    "1.1.1.1",
    count=5,
    timeout_ms=1000,
    probe_mtu=True,
    tcp_ports=[443, 853],
)
print(report.network_score, report.health_label)
print(report.summary.average_latency_ms, report.summary.percentile_95_latency_ms)
for recommendation in report.recommendations:
    print("-", recommendation.title)

Batch diagnostics from Python:

from netping import diagnose_websites

batch = diagnose_websites(profile="developer", count=3, tcp_ports=[443], workers=4)
print(batch.aggregate.best_target, batch.aggregate.average_score)
for item in batch.results:
    print(item.rank, item.name, item.report.network_score)

Example Output

Target: 1.1.1.1
Score: 91/100 (excellent)
Quality grade: excellent
Samples: 5
Packet loss: 0.00% (success 100.00%)
Latency min/avg/max: 11.20 / 13.08 / 17.80 ms
Latency median/p95/stddev: 12.90 / 17.10 / 2.24 ms
Latency spread: 6.60 ms | Stability score: 93/100
Jitter: 2.14 ms
DNS lookup: 6.84 ms
Resolved addresses: 1.1.1.1
TCP checks:
- Port 443: reachable in 17.20 ms

Recommendations
- [info] Overall network health is excellent: Computed network score: 91/100 with ping quality graded as excellent.
- [info] TCP connectivity checks succeeded: The requested TCP services accepted connections.

Publishing

Build the distribution files:

python -m pip install build
python -m build

Upload them:

python -m pip install twine
python -m twine upload dist/*

If the package name is already taken on PyPI, update the name field in pyproject.toml before publishing.

You should also add your own repository URL and author metadata before publishing a public release.

NetPing does not execute arbitrary commands during pip install. Use netping init for explicit first-run setup instead.