Metadata-Version: 2.4
Name: NetPing
Version: 1.1.0
Summary: Ping diagnostics and network optimization suggestions for Python and the command line.
Author: ApinaAppu
License: MIT
License-File: LICENSE
Keywords: cli,diagnostics,latency,network,optimization,ping
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet
Classifier: Topic :: System :: Networking
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: build>=1.2.2; extra == 'dev'
Requires-Dist: pytest>=8.3.0; extra == 'dev'
Requires-Dist: twine>=6.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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

```bash
pip install NetPing
```

For local development:

```bash
python -m pip install -e .[dev]
```

## Quick Start

Run a simple diagnostic:

```bash
netping diagnose 1.1.1.1
```

Run more samples and print JSON:

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

Run a batch check against common websites:

```bash
netping websites --profile general --workers 4
```

Run a custom list of sites:

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

Probe the path MTU in addition to standard diagnostics:

```bash
netping diagnose 8.8.8.8 --probe-mtu
```

Initialize the local config after installation:

```bash
netping init
```

List built-in profiles and inspect the active config:

```bash
netping profiles
netping config
```

Use it from Python:

```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:

```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

```text
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:

```bash
python -m pip install build
python -m build
```

Upload them:

```bash
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.
