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 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())