speedtest-ng 3.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.
- speedtest/__init__.py +70 -0
- speedtest/__main__.py +8 -0
- speedtest/async_client.py +387 -0
- speedtest/cli.py +391 -0
- speedtest/client.py +188 -0
- speedtest/exceptions.py +76 -0
- speedtest/metrics.py +113 -0
- speedtest/models.py +209 -0
- speedtest/py.typed +0 -0
- speedtest/transport/__init__.py +35 -0
- speedtest/transport/http.py +784 -0
- speedtest/transport/tcp.py +491 -0
- speedtest_ng-3.0.0.dist-info/METADATA +130 -0
- speedtest_ng-3.0.0.dist-info/RECORD +17 -0
- speedtest_ng-3.0.0.dist-info/WHEEL +4 -0
- speedtest_ng-3.0.0.dist-info/entry_points.txt +3 -0
- speedtest_ng-3.0.0.dist-info/licenses/LICENSE +202 -0
speedtest/__init__.py
ADDED
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
"""Modern async & raw-TCP speedtest.net library and CLI (speedtest-ng)."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from .async_client import AsyncSpeedtest
|
|
6
|
+
from .cli import main, shell
|
|
7
|
+
from .client import Speedtest
|
|
8
|
+
from .exceptions import (
|
|
9
|
+
ConfigRetrievalError,
|
|
10
|
+
InvalidServerIDType,
|
|
11
|
+
InvalidSpeedtestMiniServer,
|
|
12
|
+
NoMatchedServers,
|
|
13
|
+
ServersRetrievalError,
|
|
14
|
+
ShareResultsConnectFailure,
|
|
15
|
+
ShareResultsSubmitFailure,
|
|
16
|
+
SpeedtestBestServerFailure,
|
|
17
|
+
SpeedtestCLIError,
|
|
18
|
+
SpeedtestConfigError,
|
|
19
|
+
SpeedtestException,
|
|
20
|
+
SpeedtestHTTPError,
|
|
21
|
+
SpeedtestMiniConnectFailure,
|
|
22
|
+
SpeedtestMissingBestServer,
|
|
23
|
+
SpeedtestServersError,
|
|
24
|
+
SpeedtestTransferError,
|
|
25
|
+
SpeedtestUploadTimeout,
|
|
26
|
+
)
|
|
27
|
+
from .models import (
|
|
28
|
+
ActiveProtocol,
|
|
29
|
+
FakeShutdownEvent,
|
|
30
|
+
ProtocolName,
|
|
31
|
+
ServerDict,
|
|
32
|
+
SpeedtestResults,
|
|
33
|
+
__version__,
|
|
34
|
+
build_user_agent,
|
|
35
|
+
distance,
|
|
36
|
+
do_nothing,
|
|
37
|
+
)
|
|
38
|
+
|
|
39
|
+
__all__ = [
|
|
40
|
+
"ActiveProtocol",
|
|
41
|
+
"AsyncSpeedtest",
|
|
42
|
+
"ConfigRetrievalError",
|
|
43
|
+
"FakeShutdownEvent",
|
|
44
|
+
"InvalidServerIDType",
|
|
45
|
+
"InvalidSpeedtestMiniServer",
|
|
46
|
+
"NoMatchedServers",
|
|
47
|
+
"ProtocolName",
|
|
48
|
+
"ServerDict",
|
|
49
|
+
"ServersRetrievalError",
|
|
50
|
+
"ShareResultsConnectFailure",
|
|
51
|
+
"ShareResultsSubmitFailure",
|
|
52
|
+
"Speedtest",
|
|
53
|
+
"SpeedtestBestServerFailure",
|
|
54
|
+
"SpeedtestCLIError",
|
|
55
|
+
"SpeedtestConfigError",
|
|
56
|
+
"SpeedtestException",
|
|
57
|
+
"SpeedtestHTTPError",
|
|
58
|
+
"SpeedtestMiniConnectFailure",
|
|
59
|
+
"SpeedtestMissingBestServer",
|
|
60
|
+
"SpeedtestResults",
|
|
61
|
+
"SpeedtestServersError",
|
|
62
|
+
"SpeedtestTransferError",
|
|
63
|
+
"SpeedtestUploadTimeout",
|
|
64
|
+
"__version__",
|
|
65
|
+
"build_user_agent",
|
|
66
|
+
"distance",
|
|
67
|
+
"do_nothing",
|
|
68
|
+
"main",
|
|
69
|
+
"shell",
|
|
70
|
+
]
|
speedtest/__main__.py
ADDED
|
@@ -0,0 +1,387 @@
|
|
|
1
|
+
"""Native asyncio Speedtest.net client engine."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import asyncio
|
|
6
|
+
import logging
|
|
7
|
+
from typing import TYPE_CHECKING, Any, Literal
|
|
8
|
+
|
|
9
|
+
from .exceptions import (
|
|
10
|
+
SpeedtestBestServerFailure,
|
|
11
|
+
SpeedtestTransferError,
|
|
12
|
+
)
|
|
13
|
+
from .models import (
|
|
14
|
+
ProtocolName,
|
|
15
|
+
SpeedtestResults,
|
|
16
|
+
build_user_agent,
|
|
17
|
+
do_nothing,
|
|
18
|
+
)
|
|
19
|
+
from .transport.http import (
|
|
20
|
+
create_session,
|
|
21
|
+
fetch_config,
|
|
22
|
+
fetch_servers,
|
|
23
|
+
measure_http_latency,
|
|
24
|
+
resolve_mini_server,
|
|
25
|
+
run_http_transfer,
|
|
26
|
+
share_results,
|
|
27
|
+
)
|
|
28
|
+
from .transport.tcp import measure_tcp_latency, run_tcp_transfer
|
|
29
|
+
|
|
30
|
+
if TYPE_CHECKING:
|
|
31
|
+
from collections.abc import Callable, Sequence
|
|
32
|
+
|
|
33
|
+
import aiohttp
|
|
34
|
+
|
|
35
|
+
from .metrics import TransferResult
|
|
36
|
+
|
|
37
|
+
_LOGGER = logging.getLogger("speedtest")
|
|
38
|
+
_VALID_PROTOCOLS: tuple[ProtocolName, ...] = ("auto", "tcp", "http")
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
class AsyncSpeedtest:
|
|
42
|
+
"""Asynchronous Speedtest.net client supporting TCP (:8080) and HTTP."""
|
|
43
|
+
|
|
44
|
+
def __init__(
|
|
45
|
+
self,
|
|
46
|
+
*,
|
|
47
|
+
config: dict[str, Any] | None = None,
|
|
48
|
+
source_address: str | None = None,
|
|
49
|
+
timeout: float = 10.0,
|
|
50
|
+
secure: bool = True,
|
|
51
|
+
session: aiohttp.ClientSession | None = None,
|
|
52
|
+
protocol: ProtocolName = "auto",
|
|
53
|
+
shutdown_check: Callable[[], bool] | None = None,
|
|
54
|
+
) -> None:
|
|
55
|
+
if protocol not in _VALID_PROTOCOLS:
|
|
56
|
+
raise ValueError(
|
|
57
|
+
f"Unsupported protocol {protocol!r}; expected 'auto', 'tcp', or 'http'"
|
|
58
|
+
)
|
|
59
|
+
|
|
60
|
+
self._config_overrides: dict[str, Any] | None = (
|
|
61
|
+
dict(config) if config is not None else None
|
|
62
|
+
)
|
|
63
|
+
self._source_address = source_address
|
|
64
|
+
self._timeout = float(timeout)
|
|
65
|
+
self._secure = bool(secure)
|
|
66
|
+
self._session: aiohttp.ClientSession | None = session
|
|
67
|
+
self._external_session = session is not None
|
|
68
|
+
self._protocol: ProtocolName = protocol
|
|
69
|
+
self._shutdown_check: Callable[[], bool] = shutdown_check or (lambda: False)
|
|
70
|
+
|
|
71
|
+
self.config: dict[str, Any] = {}
|
|
72
|
+
self.lat_lon: tuple[float, float] = (0.0, 0.0)
|
|
73
|
+
self.servers: dict[float, list[dict[str, Any]]] = {}
|
|
74
|
+
self.closest: list[dict[str, Any]] = []
|
|
75
|
+
self._best: dict[str, Any] = {}
|
|
76
|
+
self.results = SpeedtestResults(secure=self._secure)
|
|
77
|
+
|
|
78
|
+
async def __aenter__(self) -> AsyncSpeedtest:
|
|
79
|
+
return self
|
|
80
|
+
|
|
81
|
+
async def __aexit__(self, *_: object) -> None:
|
|
82
|
+
await self.aclose()
|
|
83
|
+
|
|
84
|
+
def _get_session(self) -> aiohttp.ClientSession:
|
|
85
|
+
if self._session is None or self._session.closed:
|
|
86
|
+
self._session = create_session(
|
|
87
|
+
timeout=self._timeout,
|
|
88
|
+
source_address=self._source_address,
|
|
89
|
+
user_agent=build_user_agent(),
|
|
90
|
+
)
|
|
91
|
+
self._external_session = False
|
|
92
|
+
return self._session
|
|
93
|
+
|
|
94
|
+
async def aclose(self) -> None:
|
|
95
|
+
"""Close the internally managed ``aiohttp.ClientSession`` if owned."""
|
|
96
|
+
if not self._external_session and self._session is not None:
|
|
97
|
+
if not self._session.closed:
|
|
98
|
+
await self._session.close()
|
|
99
|
+
self._session = None
|
|
100
|
+
|
|
101
|
+
@property
|
|
102
|
+
def best(self) -> dict[str, Any]:
|
|
103
|
+
"""Return currently selected best server (call ``get_best_server`` first)."""
|
|
104
|
+
return self._best
|
|
105
|
+
|
|
106
|
+
async def get_config(self) -> dict[str, Any]:
|
|
107
|
+
"""Fetch Speedtest.net configuration XML and merge any user overrides."""
|
|
108
|
+
session = self._get_session()
|
|
109
|
+
config, lat_lon = await fetch_config(
|
|
110
|
+
session, secure=self._secure, request_timeout=self._timeout
|
|
111
|
+
)
|
|
112
|
+
if self._config_overrides is not None:
|
|
113
|
+
config.update(self._config_overrides)
|
|
114
|
+
self.config = config
|
|
115
|
+
self.lat_lon = lat_lon
|
|
116
|
+
self.results.client = dict(config.get("client", {}))
|
|
117
|
+
self.results.touch_timestamp()
|
|
118
|
+
_LOGGER.debug(
|
|
119
|
+
"Loaded speedtest.net config for ISP %s",
|
|
120
|
+
self.results.client.get("isp"),
|
|
121
|
+
)
|
|
122
|
+
return self.config
|
|
123
|
+
|
|
124
|
+
async def get_servers(
|
|
125
|
+
self,
|
|
126
|
+
servers: Sequence[int | str] | None = None,
|
|
127
|
+
exclude: Sequence[int | str] | None = None,
|
|
128
|
+
) -> dict[float, list[dict[str, Any]]]:
|
|
129
|
+
"""Retrieve and optionally filter Speedtest.net servers."""
|
|
130
|
+
if not self.config:
|
|
131
|
+
await self.get_config()
|
|
132
|
+
|
|
133
|
+
session = self._get_session()
|
|
134
|
+
self.servers.clear()
|
|
135
|
+
fetched = await fetch_servers(
|
|
136
|
+
session,
|
|
137
|
+
config=self.config,
|
|
138
|
+
lat_lon=self.lat_lon,
|
|
139
|
+
secure=self._secure,
|
|
140
|
+
request_timeout=self._timeout,
|
|
141
|
+
servers=servers,
|
|
142
|
+
exclude=exclude,
|
|
143
|
+
)
|
|
144
|
+
self.servers.update(fetched)
|
|
145
|
+
return self.servers
|
|
146
|
+
|
|
147
|
+
async def set_mini_server(self, server: str) -> list[dict[str, Any]]:
|
|
148
|
+
"""Configure a self-hosted Speedtest Mini server."""
|
|
149
|
+
session = self._get_session()
|
|
150
|
+
mini_servers = await resolve_mini_server(
|
|
151
|
+
session, server, request_timeout=self._timeout
|
|
152
|
+
)
|
|
153
|
+
self.servers = {0.0: mini_servers}
|
|
154
|
+
self.closest = list(mini_servers)
|
|
155
|
+
return mini_servers
|
|
156
|
+
|
|
157
|
+
async def get_closest_servers(self, limit: int = 5) -> list[dict[str, Any]]:
|
|
158
|
+
"""Select up to ``limit`` geographically closest servers."""
|
|
159
|
+
if not self.servers:
|
|
160
|
+
await self.get_servers()
|
|
161
|
+
|
|
162
|
+
self.closest.clear()
|
|
163
|
+
for dist in sorted(self.servers.keys()):
|
|
164
|
+
for srv in self.servers[dist]:
|
|
165
|
+
self.closest.append(srv)
|
|
166
|
+
if len(self.closest) >= limit:
|
|
167
|
+
_LOGGER.debug("Closest servers: %r", self.closest)
|
|
168
|
+
return self.closest
|
|
169
|
+
|
|
170
|
+
_LOGGER.debug("Closest servers: %r", self.closest)
|
|
171
|
+
return self.closest
|
|
172
|
+
|
|
173
|
+
async def _probe_server_latency(
|
|
174
|
+
self,
|
|
175
|
+
server: dict[str, Any],
|
|
176
|
+
) -> (
|
|
177
|
+
tuple[float, float, float, float, Literal["tcp", "http"], dict[str, Any]] | None
|
|
178
|
+
):
|
|
179
|
+
tcp_result: tuple[float, float, float] | None = None
|
|
180
|
+
used_proto: Literal["tcp", "http"] = "http"
|
|
181
|
+
|
|
182
|
+
if self._protocol in ("auto", "tcp"):
|
|
183
|
+
tcp_result = await measure_tcp_latency(
|
|
184
|
+
server,
|
|
185
|
+
probe_timeout=self._timeout,
|
|
186
|
+
source_address=self._source_address,
|
|
187
|
+
)
|
|
188
|
+
if tcp_result is not None:
|
|
189
|
+
used_proto = "tcp"
|
|
190
|
+
elif self._protocol == "tcp":
|
|
191
|
+
return None
|
|
192
|
+
|
|
193
|
+
if tcp_result is None:
|
|
194
|
+
session = self._get_session()
|
|
195
|
+
http_result = await measure_http_latency(
|
|
196
|
+
session,
|
|
197
|
+
server,
|
|
198
|
+
secure=self._secure,
|
|
199
|
+
request_timeout=self._timeout,
|
|
200
|
+
)
|
|
201
|
+
if http_result is None:
|
|
202
|
+
return None
|
|
203
|
+
avg_ms, jitter_ms, packet_loss = http_result
|
|
204
|
+
used_proto = "http"
|
|
205
|
+
else:
|
|
206
|
+
avg_ms, jitter_ms, packet_loss = tcp_result
|
|
207
|
+
|
|
208
|
+
dist_km = float(server.get("d", 0.0))
|
|
209
|
+
return avg_ms, dist_km, jitter_ms, packet_loss, used_proto, server
|
|
210
|
+
|
|
211
|
+
async def get_best_server(
|
|
212
|
+
self,
|
|
213
|
+
servers: Sequence[dict[str, Any]] | None = None,
|
|
214
|
+
) -> dict[str, Any]:
|
|
215
|
+
"""Measure latency to candidate servers and select the fastest server."""
|
|
216
|
+
if not servers:
|
|
217
|
+
if not self.closest:
|
|
218
|
+
await self.get_closest_servers()
|
|
219
|
+
candidates: Sequence[dict[str, Any]] = self.closest
|
|
220
|
+
else:
|
|
221
|
+
candidates = servers
|
|
222
|
+
|
|
223
|
+
if not candidates:
|
|
224
|
+
raise SpeedtestBestServerFailure(
|
|
225
|
+
"Unable to connect to servers to test latency."
|
|
226
|
+
)
|
|
227
|
+
|
|
228
|
+
sem = asyncio.Semaphore(5)
|
|
229
|
+
|
|
230
|
+
async def _bounded_probe(
|
|
231
|
+
srv: dict[str, Any],
|
|
232
|
+
) -> (
|
|
233
|
+
tuple[float, float, float, float, Literal["tcp", "http"], dict[str, Any]]
|
|
234
|
+
| None
|
|
235
|
+
):
|
|
236
|
+
async with sem:
|
|
237
|
+
return await self._probe_server_latency(srv)
|
|
238
|
+
|
|
239
|
+
probe_results = await asyncio.gather(
|
|
240
|
+
*(_bounded_probe(srv) for srv in candidates)
|
|
241
|
+
)
|
|
242
|
+
valid = [item for item in probe_results if item is not None]
|
|
243
|
+
if not valid:
|
|
244
|
+
raise SpeedtestBestServerFailure(
|
|
245
|
+
"Unable to connect to servers to test latency."
|
|
246
|
+
)
|
|
247
|
+
|
|
248
|
+
valid.sort(key=lambda item: (item[0], item[1]))
|
|
249
|
+
latency_ms, _, jitter_ms, packet_loss, used_proto, winner = valid[0]
|
|
250
|
+
winner["latency"] = latency_ms
|
|
251
|
+
|
|
252
|
+
self.results.ping = latency_ms
|
|
253
|
+
self.results.jitter = jitter_ms
|
|
254
|
+
self.results.packet_loss = packet_loss
|
|
255
|
+
self.results.server = winner
|
|
256
|
+
self.results.protocol = used_proto
|
|
257
|
+
self.results.touch_timestamp()
|
|
258
|
+
|
|
259
|
+
self._best = winner
|
|
260
|
+
_LOGGER.debug("Best server (%s): %r", used_proto, winner)
|
|
261
|
+
return winner
|
|
262
|
+
|
|
263
|
+
async def _run_transfer(
|
|
264
|
+
self,
|
|
265
|
+
*,
|
|
266
|
+
direction: Literal["download", "upload"],
|
|
267
|
+
callback: Callable[..., Any],
|
|
268
|
+
threads: int | None,
|
|
269
|
+
) -> float:
|
|
270
|
+
if not self._best:
|
|
271
|
+
await self.get_best_server()
|
|
272
|
+
if not self.config:
|
|
273
|
+
await self.get_config()
|
|
274
|
+
|
|
275
|
+
self.results.touch_timestamp()
|
|
276
|
+
duration = float(self.config.get("length", {}).get(direction, 10.0))
|
|
277
|
+
|
|
278
|
+
result: TransferResult
|
|
279
|
+
use_tcp = self._protocol == "tcp" or (
|
|
280
|
+
self._protocol == "auto" and self.results.protocol != "http"
|
|
281
|
+
)
|
|
282
|
+
if use_tcp:
|
|
283
|
+
try:
|
|
284
|
+
result = await run_tcp_transfer(
|
|
285
|
+
self._best,
|
|
286
|
+
direction=direction,
|
|
287
|
+
duration=duration,
|
|
288
|
+
io_timeout=self._timeout,
|
|
289
|
+
threads=threads,
|
|
290
|
+
source_address=self._source_address,
|
|
291
|
+
is_cancelled=self._shutdown_check,
|
|
292
|
+
callback=callback,
|
|
293
|
+
)
|
|
294
|
+
except (OSError, TimeoutError, SpeedtestTransferError, ValueError) as err:
|
|
295
|
+
if self._protocol == "tcp":
|
|
296
|
+
if isinstance(err, SpeedtestTransferError):
|
|
297
|
+
raise
|
|
298
|
+
raise SpeedtestTransferError(str(err)) from err
|
|
299
|
+
_LOGGER.debug(
|
|
300
|
+
"TCP %s failed (%s); falling back to async HTTP", direction, err
|
|
301
|
+
)
|
|
302
|
+
result = await self._run_http_transfer(
|
|
303
|
+
direction=direction,
|
|
304
|
+
duration=duration,
|
|
305
|
+
callback=callback,
|
|
306
|
+
threads=threads,
|
|
307
|
+
)
|
|
308
|
+
else:
|
|
309
|
+
result = await self._run_http_transfer(
|
|
310
|
+
direction=direction,
|
|
311
|
+
duration=duration,
|
|
312
|
+
callback=callback,
|
|
313
|
+
threads=threads,
|
|
314
|
+
)
|
|
315
|
+
|
|
316
|
+
if direction == "download":
|
|
317
|
+
self.results.bytes_received = result.total_bytes
|
|
318
|
+
self.results.download = result.bps
|
|
319
|
+
self.results.loaded_ping_download = result.loaded_ping_ms
|
|
320
|
+
else:
|
|
321
|
+
self.results.bytes_sent = result.total_bytes
|
|
322
|
+
self.results.upload = result.bps
|
|
323
|
+
self.results.loaded_ping_upload = result.loaded_ping_ms
|
|
324
|
+
self.results.protocol = result.protocol
|
|
325
|
+
return result.bps
|
|
326
|
+
|
|
327
|
+
async def _run_http_transfer(
|
|
328
|
+
self,
|
|
329
|
+
*,
|
|
330
|
+
direction: Literal["download", "upload"],
|
|
331
|
+
duration: float,
|
|
332
|
+
callback: Callable[..., Any],
|
|
333
|
+
threads: int | None,
|
|
334
|
+
) -> TransferResult:
|
|
335
|
+
session = self._get_session()
|
|
336
|
+
return await run_http_transfer(
|
|
337
|
+
session,
|
|
338
|
+
self._best,
|
|
339
|
+
direction=direction,
|
|
340
|
+
config=self.config,
|
|
341
|
+
secure=self._secure,
|
|
342
|
+
duration=duration,
|
|
343
|
+
request_timeout=self._timeout,
|
|
344
|
+
threads=threads,
|
|
345
|
+
is_cancelled=self._shutdown_check,
|
|
346
|
+
callback=callback,
|
|
347
|
+
)
|
|
348
|
+
|
|
349
|
+
async def download(
|
|
350
|
+
self,
|
|
351
|
+
callback: Callable[..., Any] = do_nothing,
|
|
352
|
+
threads: int | None = None,
|
|
353
|
+
) -> float:
|
|
354
|
+
"""Run download throughput test and return speed in bits/sec."""
|
|
355
|
+
return await self._run_transfer(
|
|
356
|
+
direction="download",
|
|
357
|
+
callback=callback,
|
|
358
|
+
threads=threads,
|
|
359
|
+
)
|
|
360
|
+
|
|
361
|
+
async def upload(
|
|
362
|
+
self,
|
|
363
|
+
callback: Callable[..., Any] = do_nothing,
|
|
364
|
+
pre_allocate: bool = True,
|
|
365
|
+
threads: int | None = None,
|
|
366
|
+
) -> float:
|
|
367
|
+
"""Run upload throughput test and return speed in bits/sec."""
|
|
368
|
+
_ = pre_allocate # Shared zero-copy memoryview buffer never per-allocates
|
|
369
|
+
return await self._run_transfer(
|
|
370
|
+
direction="upload",
|
|
371
|
+
callback=callback,
|
|
372
|
+
threads=threads,
|
|
373
|
+
)
|
|
374
|
+
|
|
375
|
+
async def share(self) -> str:
|
|
376
|
+
"""Submit results to speedtest.net API and return the share image URL."""
|
|
377
|
+
if self.results._share:
|
|
378
|
+
return self.results._share
|
|
379
|
+
session = self._get_session()
|
|
380
|
+
url = await share_results(
|
|
381
|
+
session,
|
|
382
|
+
self.results,
|
|
383
|
+
secure=self._secure,
|
|
384
|
+
request_timeout=self._timeout,
|
|
385
|
+
)
|
|
386
|
+
self.results._share = url
|
|
387
|
+
return url
|