0
# speedtest-cli
1

2
Command line interface for testing internet bandwidth using speedtest.net. Provides both CLI functionality and a Python API for programmatic access to speed testing capabilities including download/upload speed measurements, latency testing, and server selection.
3

4
## Package Information
5

6
- **Package Name**: speedtest-cli
7
- **Package Type**: pypi  
8
- **Language**: Python
9
- **Installation**: `pip install speedtest-cli`
10

11
## Core Imports
12

13
```python
14
import speedtest
15
```
16

17
## Basic Usage
18

19
```python
20
import speedtest
21

22
# Create speedtest instance
23
s = speedtest.Speedtest()
24

25
# Get best server and run tests
26
s.get_best_server()
27
s.download()
28
s.upload()
29

30
# Access results
31
results = s.results
32
print(f"Download: {results.download / 1000000:.2f} Mbps")
33
print(f"Upload: {results.upload / 1000000:.2f} Mbps") 
34
print(f"Ping: {results.ping:.2f} ms")
35

36
# Export results
37
print(results.json(pretty=True))
38
```
39

40
## Architecture
41

42
speedtest-cli uses a class-based architecture centered around two main classes:
43

44
- **Speedtest**: Primary interface for performing speed tests, managing configuration, server selection, and test execution
45
- **SpeedtestResults**: Container for test results with export capabilities (JSON, CSV, sharing)
46

47
The package provides extensive exception handling through a hierarchy of specialized exception classes, and includes threading classes for concurrent download/upload testing to maximize bandwidth utilization.
48

49
## Capabilities
50

51
### Core Speed Testing
52

53
Primary speed testing functionality including server selection, download/upload tests, and configuration management. The main Speedtest class provides the complete API for performing bandwidth measurements.
54

55
```python { .api }
56
class Speedtest:
57
    def __init__(self, config=None, source_address=None, timeout=10, secure=False, shutdown_event=None): ...
58
    def get_config(self): ...
59
    def get_servers(self, servers=None, exclude=None): ...
60
    def set_mini_server(self, server): ...
61
    def get_closest_servers(self, limit=5): ...
62
    def get_best_server(self, servers=None): ...
63
    def download(self, callback=None, threads=None): ...
64
    def upload(self, callback=None, pre_allocate=True, threads=None): ...
65
```
66

67
[Speed Testing](./speed-testing.md)
68

69
### Results Management
70

71
Comprehensive results handling with multiple export formats and sharing capabilities. The SpeedtestResults class provides structured access to test data and various output options.
72

73
```python { .api }
74
class SpeedtestResults:
75
    def __init__(self, download=0, upload=0, ping=0, server=None, client=None, opener=None, secure=False): ...
76
    def share(self): ...
77
    def dict(self): ...
78
    def json(self, pretty=False): ...
79
    def csv(self, delimiter=','): ...
80
```
81

82
[Results Management](./results-management.md)
83

84
### Exception Handling
85

86
Comprehensive exception hierarchy for handling various error conditions during speed testing operations. All exceptions inherit from SpeedtestException base class.
87

88
```python { .api }
89
class SpeedtestException(Exception): ...
90
class SpeedtestCLIError(SpeedtestException): ...
91
class SpeedtestHTTPError(SpeedtestException): ...
92
class SpeedtestConfigError(SpeedtestException): ...
93
class ConfigRetrievalError(SpeedtestHTTPError): ...
94
class SpeedtestServersError(SpeedtestException): ...
95
class ServersRetrievalError(SpeedtestHTTPError): ...
96
class InvalidServerIDType(SpeedtestException): ...
97
class NoMatchedServers(SpeedtestException): ...
98
class SpeedtestMiniConnectFailure(SpeedtestException): ...
99
class InvalidSpeedtestMiniServer(SpeedtestException): ...
100
class ShareResultsConnectFailure(SpeedtestException): ...
101
class ShareResultsSubmitFailure(SpeedtestException): ...
102
class SpeedtestUploadTimeout(SpeedtestException): ...
103
class SpeedtestBestServerFailure(SpeedtestException): ...
104
class SpeedtestMissingBestServer(SpeedtestException): ...
105
```
106

107
[Exception Handling](./exception-handling.md)
108

109
### CLI Interface
110

111
Command-line interface providing direct access to speed testing functionality with extensive options for output formatting, server selection, and test configuration.
112

113
```python { .api }
114
def main(): ...
115
def shell(): ...
116
def parse_args(): ...
117
```
118

119
[CLI Interface](./cli-interface.md)
120

121
### Utility Functions
122

123
Module-level utility functions for distance calculation, HTTP operations, and user agent building.
124

125
```python { .api }
126
def distance(origin, destination): ...
127
def build_user_agent(): ...
128
def build_request(url, data=None, headers=None, bump='0', secure=False): ...
129
def catch_request(request, opener=None): ...
130
```
131

132
## Constants
133

134
```python { .api }
135
__version__: str  # Current version string
136
DEBUG: bool      # Debug flag (default: False)
137
```
138

139
## Classes
140

141
```python { .api }
142
class FakeShutdownEvent:
143
    @staticmethod
144
    def isSet() -> bool: ...
145
```
146

147
## Types
148

149
```python { .api }
150
# Configuration dictionary structure
151
ConfigDict = dict[str, Any]  # Contains client info, server list URLs, timing settings
152

153
# Server dictionary structure  
154
ServerDict = dict[str, Any]  # Contains id, host, port, name, country, sponsor, lat, lon, distance
155

156
# Client dictionary structure
157
ClientDict = dict[str, Any]  # Contains ip, lat, lon, isp, isprating, rating, ispdlavg, ispulavg
158

159
# Callback function signature for progress monitoring
160
CallbackFunction = Callable[[int, int], None]  # (bytes_received, total_bytes) -> None
161
```