fastdotcom-ng 1.0.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- fastdotcom/__init__.py +158 -0
- fastdotcom/cli.py +163 -0
- fastdotcom/client.py +794 -0
- fastdotcom/const.py +38 -0
- fastdotcom/exceptions.py +19 -0
- fastdotcom/models.py +59 -0
- fastdotcom/py.typed +0 -0
- fastdotcom_ng-1.0.0.dist-info/METADATA +134 -0
- fastdotcom_ng-1.0.0.dist-info/RECORD +12 -0
- fastdotcom_ng-1.0.0.dist-info/WHEEL +4 -0
- fastdotcom_ng-1.0.0.dist-info/entry_points.txt +2 -0
- fastdotcom_ng-1.0.0.dist-info/licenses/LICENSE +21 -0
fastdotcom/__init__.py
ADDED
|
@@ -0,0 +1,158 @@
|
|
|
1
|
+
"""Public API and Home Assistant drop-in facade for fastdotcom-ng."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import asyncio
|
|
6
|
+
import logging
|
|
7
|
+
from concurrent.futures import ThreadPoolExecutor
|
|
8
|
+
from typing import TYPE_CHECKING
|
|
9
|
+
|
|
10
|
+
from .client import FastDotComClient, decode_json_bytes, to_range_url
|
|
11
|
+
from .const import (
|
|
12
|
+
DEFAULT_CONNECTIONS_MAX,
|
|
13
|
+
DEFAULT_CONNECTIONS_MIN,
|
|
14
|
+
DEFAULT_MAX_TIME,
|
|
15
|
+
DEFAULT_MIN_TIME,
|
|
16
|
+
DEFAULT_PING_COUNT,
|
|
17
|
+
DEFAULT_PING_INTERVAL,
|
|
18
|
+
DEFAULT_TIMEOUT,
|
|
19
|
+
DEFAULT_UPLOAD_PAYLOAD_SIZE,
|
|
20
|
+
DEFAULT_URL_COUNT,
|
|
21
|
+
FAST_API_V2_URL,
|
|
22
|
+
FAST_COM_URL,
|
|
23
|
+
)
|
|
24
|
+
from .exceptions import (
|
|
25
|
+
FastDotComConnectionError,
|
|
26
|
+
FastDotComError,
|
|
27
|
+
FastDotComTimeoutError,
|
|
28
|
+
FastDotComTokenError,
|
|
29
|
+
)
|
|
30
|
+
from .models import (
|
|
31
|
+
FastClientInfo,
|
|
32
|
+
FastLocation,
|
|
33
|
+
FastSpeedtestResult,
|
|
34
|
+
FastTarget,
|
|
35
|
+
)
|
|
36
|
+
|
|
37
|
+
if TYPE_CHECKING:
|
|
38
|
+
import aiohttp
|
|
39
|
+
|
|
40
|
+
__version__ = "1.0.0"
|
|
41
|
+
|
|
42
|
+
__all__ = [
|
|
43
|
+
"FastClientInfo",
|
|
44
|
+
"FastDotComClient",
|
|
45
|
+
"FastDotComConnectionError",
|
|
46
|
+
"FastDotComError",
|
|
47
|
+
"FastDotComTimeoutError",
|
|
48
|
+
"FastDotComTokenError",
|
|
49
|
+
"FastLocation",
|
|
50
|
+
"FastSpeedtestResult",
|
|
51
|
+
"FastTarget",
|
|
52
|
+
"__version__",
|
|
53
|
+
"async_fast_com",
|
|
54
|
+
"decode_json_bytes",
|
|
55
|
+
"fast_com",
|
|
56
|
+
"to_range_url",
|
|
57
|
+
]
|
|
58
|
+
|
|
59
|
+
_LOGGER = logging.getLogger(__name__)
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
async def async_fast_com(
|
|
63
|
+
*,
|
|
64
|
+
session: aiohttp.ClientSession | None = None,
|
|
65
|
+
min_time: float = DEFAULT_MIN_TIME,
|
|
66
|
+
max_time: float = DEFAULT_MAX_TIME,
|
|
67
|
+
ping_count: int = DEFAULT_PING_COUNT,
|
|
68
|
+
ping_interval: float = DEFAULT_PING_INTERVAL,
|
|
69
|
+
url_count: int = DEFAULT_URL_COUNT,
|
|
70
|
+
connections_min: int = DEFAULT_CONNECTIONS_MIN,
|
|
71
|
+
connections_max: int = DEFAULT_CONNECTIONS_MAX,
|
|
72
|
+
upload_payload_size: int = DEFAULT_UPLOAD_PAYLOAD_SIZE,
|
|
73
|
+
measure_download: bool = True,
|
|
74
|
+
measure_upload: bool = True,
|
|
75
|
+
measure_latency: bool = True,
|
|
76
|
+
force_ipv4: bool = False,
|
|
77
|
+
force_ipv6: bool = False,
|
|
78
|
+
request_timeout: float = DEFAULT_TIMEOUT,
|
|
79
|
+
fast_com_url: str | None = None,
|
|
80
|
+
api_url: str | None = None,
|
|
81
|
+
) -> FastSpeedtestResult:
|
|
82
|
+
"""Measure Internet speed asynchronously using Fast.com API v2."""
|
|
83
|
+
async with FastDotComClient(
|
|
84
|
+
session=session,
|
|
85
|
+
timeout=request_timeout,
|
|
86
|
+
force_ipv4=force_ipv4,
|
|
87
|
+
force_ipv6=force_ipv6,
|
|
88
|
+
fast_com_url=FAST_COM_URL if fast_com_url is None else fast_com_url,
|
|
89
|
+
api_url=FAST_API_V2_URL if api_url is None else api_url,
|
|
90
|
+
) as client:
|
|
91
|
+
return await client.run_speedtest(
|
|
92
|
+
min_time=min_time,
|
|
93
|
+
max_time=max_time,
|
|
94
|
+
ping_count=ping_count,
|
|
95
|
+
ping_interval=ping_interval,
|
|
96
|
+
url_count=url_count,
|
|
97
|
+
connections_min=connections_min,
|
|
98
|
+
connections_max=connections_max,
|
|
99
|
+
upload_payload_size=upload_payload_size,
|
|
100
|
+
measure_download=measure_download,
|
|
101
|
+
measure_upload=measure_upload,
|
|
102
|
+
measure_latency=measure_latency,
|
|
103
|
+
)
|
|
104
|
+
|
|
105
|
+
|
|
106
|
+
def fast_com(
|
|
107
|
+
verbose: bool = False,
|
|
108
|
+
max_time: float = DEFAULT_MAX_TIME,
|
|
109
|
+
ping_count: int = DEFAULT_PING_COUNT,
|
|
110
|
+
force_ipv4: bool = False,
|
|
111
|
+
force_ipv6: bool = False,
|
|
112
|
+
payload_size: int | None = None,
|
|
113
|
+
max_payload_size: int | None = None,
|
|
114
|
+
) -> dict[str, float]:
|
|
115
|
+
"""Synchronous drop-in compatible speedtest entrypoint for Home Assistant."""
|
|
116
|
+
if payload_size is not None and payload_size <= 0:
|
|
117
|
+
raise ValueError("payload_size must be positive")
|
|
118
|
+
if max_payload_size is not None and max_payload_size <= 0:
|
|
119
|
+
raise ValueError("max_payload_size must be positive")
|
|
120
|
+
|
|
121
|
+
effective_min_time = min(DEFAULT_MIN_TIME, max_time)
|
|
122
|
+
effective_payload_size = DEFAULT_UPLOAD_PAYLOAD_SIZE
|
|
123
|
+
if payload_size is not None and max_payload_size is not None:
|
|
124
|
+
effective_payload_size = min(payload_size, max_payload_size)
|
|
125
|
+
elif payload_size is not None:
|
|
126
|
+
effective_payload_size = payload_size
|
|
127
|
+
elif max_payload_size is not None:
|
|
128
|
+
effective_payload_size = max_payload_size
|
|
129
|
+
|
|
130
|
+
async def _run() -> FastSpeedtestResult:
|
|
131
|
+
return await async_fast_com(
|
|
132
|
+
min_time=effective_min_time,
|
|
133
|
+
max_time=max_time,
|
|
134
|
+
ping_count=ping_count,
|
|
135
|
+
force_ipv4=force_ipv4,
|
|
136
|
+
force_ipv6=force_ipv6,
|
|
137
|
+
upload_payload_size=effective_payload_size,
|
|
138
|
+
)
|
|
139
|
+
|
|
140
|
+
try:
|
|
141
|
+
asyncio.get_running_loop()
|
|
142
|
+
except RuntimeError:
|
|
143
|
+
result = asyncio.run(_run())
|
|
144
|
+
else:
|
|
145
|
+
with ThreadPoolExecutor(max_workers=1) as pool:
|
|
146
|
+
result = pool.submit(asyncio.run, _run()).result()
|
|
147
|
+
|
|
148
|
+
if verbose:
|
|
149
|
+
_LOGGER.info(
|
|
150
|
+
"Fast.com speedtest complete: download=%.2f Mbps, upload=%.2f Mbps, "
|
|
151
|
+
"unloaded_ping=%.2f ms, loaded_ping=%.2f ms",
|
|
152
|
+
result.download_speed,
|
|
153
|
+
result.upload_speed,
|
|
154
|
+
result.unloaded_ping,
|
|
155
|
+
result.loaded_ping,
|
|
156
|
+
)
|
|
157
|
+
|
|
158
|
+
return result.to_dict()
|
fastdotcom/cli.py
ADDED
|
@@ -0,0 +1,163 @@
|
|
|
1
|
+
"""Command-line interface for fastdotcom-ng."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import argparse
|
|
6
|
+
import asyncio
|
|
7
|
+
import json
|
|
8
|
+
import logging
|
|
9
|
+
import sys
|
|
10
|
+
from dataclasses import asdict
|
|
11
|
+
from typing import TYPE_CHECKING
|
|
12
|
+
|
|
13
|
+
from . import __version__, async_fast_com
|
|
14
|
+
from .const import DEFAULT_MAX_TIME, DEFAULT_MIN_TIME, DEFAULT_PING_COUNT
|
|
15
|
+
from .exceptions import FastDotComError
|
|
16
|
+
|
|
17
|
+
if TYPE_CHECKING:
|
|
18
|
+
from collections.abc import Sequence
|
|
19
|
+
|
|
20
|
+
from .models import FastSpeedtestResult
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
def build_parser() -> argparse.ArgumentParser:
|
|
24
|
+
"""Create the CLI argument parser."""
|
|
25
|
+
parser = argparse.ArgumentParser(
|
|
26
|
+
prog="fastdotcom",
|
|
27
|
+
description="Measure Internet speed using Netflix's Fast.com API v2.",
|
|
28
|
+
)
|
|
29
|
+
parser.add_argument(
|
|
30
|
+
"--version",
|
|
31
|
+
action="version",
|
|
32
|
+
version=f"%(prog)s {__version__}",
|
|
33
|
+
)
|
|
34
|
+
parser.add_argument(
|
|
35
|
+
"--max-time",
|
|
36
|
+
type=float,
|
|
37
|
+
default=DEFAULT_MAX_TIME,
|
|
38
|
+
help="Maximum duration in seconds for download/upload phases.",
|
|
39
|
+
)
|
|
40
|
+
parser.add_argument(
|
|
41
|
+
"--min-time",
|
|
42
|
+
type=float,
|
|
43
|
+
default=None,
|
|
44
|
+
help="Minimum duration in seconds before early stability stop.",
|
|
45
|
+
)
|
|
46
|
+
parser.add_argument(
|
|
47
|
+
"--ping-count",
|
|
48
|
+
type=int,
|
|
49
|
+
default=DEFAULT_PING_COUNT,
|
|
50
|
+
help="Number of HTTP latency probes to measure.",
|
|
51
|
+
)
|
|
52
|
+
parser.add_argument(
|
|
53
|
+
"--no-download",
|
|
54
|
+
action="store_true",
|
|
55
|
+
help="Skip the download speed test.",
|
|
56
|
+
)
|
|
57
|
+
parser.add_argument(
|
|
58
|
+
"--no-upload",
|
|
59
|
+
action="store_true",
|
|
60
|
+
help="Skip the upload speed test.",
|
|
61
|
+
)
|
|
62
|
+
parser.add_argument(
|
|
63
|
+
"--no-latency",
|
|
64
|
+
action="store_true",
|
|
65
|
+
help="Skip unloaded and loaded HTTP latency measurements.",
|
|
66
|
+
)
|
|
67
|
+
parser.add_argument(
|
|
68
|
+
"--ipv4",
|
|
69
|
+
action="store_true",
|
|
70
|
+
help="Force IPv4 connections.",
|
|
71
|
+
)
|
|
72
|
+
parser.add_argument(
|
|
73
|
+
"--ipv6",
|
|
74
|
+
action="store_true",
|
|
75
|
+
help="Force IPv6 connections.",
|
|
76
|
+
)
|
|
77
|
+
parser.add_argument(
|
|
78
|
+
"--json",
|
|
79
|
+
action="store_true",
|
|
80
|
+
dest="json_output",
|
|
81
|
+
help="Output results as JSON.",
|
|
82
|
+
)
|
|
83
|
+
parser.add_argument(
|
|
84
|
+
"-v",
|
|
85
|
+
"--verbose",
|
|
86
|
+
action="store_true",
|
|
87
|
+
help="Enable verbose debug logging.",
|
|
88
|
+
)
|
|
89
|
+
return parser
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
def format_result(result: FastSpeedtestResult) -> str:
|
|
93
|
+
"""Format a FastSpeedtestResult for human-readable terminal display."""
|
|
94
|
+
lines = [
|
|
95
|
+
f"Download: {result.download_speed:.2f} Mbps",
|
|
96
|
+
f"Upload: {result.upload_speed:.2f} Mbps",
|
|
97
|
+
f"Unloaded Ping: {result.unloaded_ping:.2f} ms",
|
|
98
|
+
f"Loaded Ping: {result.loaded_ping:.2f} ms",
|
|
99
|
+
f"Elapsed: {result.elapsed_seconds:.2f} s",
|
|
100
|
+
]
|
|
101
|
+
if result.client is not None:
|
|
102
|
+
loc_parts = []
|
|
103
|
+
if result.client.location is not None:
|
|
104
|
+
if result.client.location.city:
|
|
105
|
+
loc_parts.append(result.client.location.city)
|
|
106
|
+
if result.client.location.country:
|
|
107
|
+
loc_parts.append(result.client.location.country)
|
|
108
|
+
loc_str = ", ".join(loc_parts)
|
|
109
|
+
client_bits = [bit for bit in (result.client.isp, loc_str) if bit]
|
|
110
|
+
if client_bits:
|
|
111
|
+
lines.append(f"Client: {' — '.join(client_bits)}")
|
|
112
|
+
return "\n".join(lines)
|
|
113
|
+
|
|
114
|
+
|
|
115
|
+
def result_to_json(result: FastSpeedtestResult) -> str:
|
|
116
|
+
"""Serialize a FastSpeedtestResult as formatted JSON."""
|
|
117
|
+
payload = asdict(result)
|
|
118
|
+
return json.dumps(payload, indent=2)
|
|
119
|
+
|
|
120
|
+
|
|
121
|
+
def main(argv: Sequence[str] | None = None) -> int:
|
|
122
|
+
"""CLI entrypoint returning an exit status code."""
|
|
123
|
+
parser = build_parser()
|
|
124
|
+
args = parser.parse_args(list(argv) if argv is not None else None)
|
|
125
|
+
|
|
126
|
+
if args.verbose:
|
|
127
|
+
logging.basicConfig(
|
|
128
|
+
level=logging.DEBUG,
|
|
129
|
+
format="%(levelname)s %(name)s: %(message)s",
|
|
130
|
+
)
|
|
131
|
+
|
|
132
|
+
effective_min_time = (
|
|
133
|
+
args.min_time
|
|
134
|
+
if args.min_time is not None
|
|
135
|
+
else min(DEFAULT_MIN_TIME, args.max_time)
|
|
136
|
+
)
|
|
137
|
+
|
|
138
|
+
try:
|
|
139
|
+
result = asyncio.run(
|
|
140
|
+
async_fast_com(
|
|
141
|
+
min_time=effective_min_time,
|
|
142
|
+
max_time=args.max_time,
|
|
143
|
+
ping_count=args.ping_count,
|
|
144
|
+
measure_download=not args.no_download,
|
|
145
|
+
measure_upload=not args.no_upload,
|
|
146
|
+
measure_latency=not args.no_latency,
|
|
147
|
+
force_ipv4=args.ipv4,
|
|
148
|
+
force_ipv6=args.ipv6,
|
|
149
|
+
)
|
|
150
|
+
)
|
|
151
|
+
except (FastDotComError, ValueError) as exc:
|
|
152
|
+
print(f"Error: {exc}", file=sys.stderr)
|
|
153
|
+
return 1
|
|
154
|
+
|
|
155
|
+
if args.json_output:
|
|
156
|
+
print(result_to_json(result))
|
|
157
|
+
else:
|
|
158
|
+
print(format_result(result))
|
|
159
|
+
return 0
|
|
160
|
+
|
|
161
|
+
|
|
162
|
+
if __name__ == "__main__":
|
|
163
|
+
raise SystemExit(main())
|