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 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,8 @@
1
+ """Allow ``python -m speedtest`` execution."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from .cli import main
6
+
7
+ if __name__ == "__main__":
8
+ main()
@@ -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