0
# Twisted
1

2
An asynchronous networking framework written in Python that enables developers to build scalable network applications, servers, and clients. Twisted provides a rich ecosystem of protocols and services including HTTP clients/servers with WSGI support, SSH/Telnet clients/servers, IRC/XMPP messaging protocols, IMAP/POP3/SMTP mail services, DNS tools, GPS communication utilities, and a specialized unit testing framework (twisted.trial).
3

4
## Package Information
5

6
- **Package Name**: Twisted
7
- **Language**: Python
8
- **Installation**: `pip install Twisted`
9

10
## Core Imports
11

12
```python
13
import twisted
14
```
15

16
Common imports for basic functionality:
17

18
```python
19
from twisted.internet import reactor, defer, protocol, endpoints
20
from twisted.web import server, resource
21
from twisted.application import service
22
```
23

24
## Basic Usage
25

26
```python
27
from twisted.internet import reactor, protocol
28
from twisted.internet.endpoints import TCP4ServerEndpoint
29

30
class EchoProtocol(protocol.Protocol):
31
    def dataReceived(self, data):
32
        self.transport.write(data)
33

34
class EchoFactory(protocol.Factory):
35
    def buildProtocol(self, addr):
36
        return EchoProtocol()
37

38
# Create server endpoint and listen
39
endpoint = TCP4ServerEndpoint(reactor, 8080)
40
endpoint.listen(EchoFactory())
41

42
# Start the reactor event loop
43
reactor.run()
44
```
45

46
## Architecture
47

48
Twisted is built around several key architectural patterns:
49

50
- **Reactor Pattern**: Central event loop handling I/O operations asynchronously
51
- **Deferred Objects**: Promise-like objects for managing asynchronous operations
52
- **Protocol/Factory**: Network protocol implementations with factory pattern for connection handling
53
- **Service Framework**: Hierarchical service management for application components
54
- **Plugin System**: Extensible architecture for adding functionality
55

56
The framework supports all major system event loops (select, poll, epoll, kqueue, IOCP) and GUI event loops (GTK, Qt, wxWidgets), making it highly portable and suitable for integration into diverse environments.
57

58
## Capabilities
59

60
### Asynchronous I/O and Reactors
61

62
Core event loop and asynchronous programming primitives including Deferreds, protocols, factories, and endpoints. The reactor provides the foundation for all network operations in Twisted.
63

64
```python { .api }
65
# Key functions and classes from twisted.internet
66
def defer.succeed(result): ...
67
def defer.fail(failure): ...
68
def defer.inlineCallbacks(func): ...
69

70
class defer.Deferred: ...
71
class protocol.Protocol: ...
72
class protocol.Factory: ...
73
class endpoints.TCP4ServerEndpoint: ...
74
```
75

76
[Asynchronous I/O](./async-io.md)
77

78
### HTTP Client and Server
79

80
Complete HTTP implementation with client agents, server resources, and web application framework. Includes support for WSGI applications, static file serving, and advanced HTTP features.
81

82
```python { .api }
83
# Key classes from twisted.web
84
class server.Site: ...
85
class resource.Resource: ...
86
class client.Agent: ...
87
class client.Response: ...
88
```
89

90
[HTTP Implementation](./http.md)
91

92
### SSH and Terminal Protocols
93

94
SSH version 2 protocol implementation with client, server, SFTP support, and terminal handling capabilities. Includes key management, authentication, and channel forwarding.
95

96
```python { .api }
97
# Key classes from twisted.conch.ssh
98
class transport.SSHClientTransport: ...
99
class transport.SSHServerTransport: ...
100
class keys.Key: ...
101
class filetransfer.FileTransferClient: ...
102
```
103

104
[SSH and Terminal](./ssh.md)
105

106
### Testing Framework
107

108
Comprehensive unit testing framework with asynchronous test support, specialized test runners, and integration with Python's unittest module.
109

110
```python { .api }
111
# Key classes from twisted.trial
112
class unittest.TestCase: ...
113
class runner.TrialRunner: ...
114
class reporter.TreeReporter: ...
115
```
116

117
[Testing Framework](./testing.md)
118

119
### Application Framework
120

121
Service-oriented application architecture with hierarchical service management, plugin system, and daemon utilities for building long-running applications.
122

123
```python { .api }
124
# Key interfaces and classes from twisted.application
125
class service.IService: ...
126
class service.Service: ...
127
class service.MultiService: ...
128
class service.Application: ...
129
```
130

131
[Application Framework](./application.md)
132

133
### Authentication and Authorization
134

135
Pluggable authentication and authorization system with support for various credential types, checkers, and realms for securing network services.
136

137
```python { .api }
138
# Key classes from twisted.cred
139
class portal.Portal: ...
140
class credentials.UsernamePassword: ...
141
class checkers.ICredentialsChecker: ...
142
```
143

144
[Authentication](./auth.md)
145

146
### Email Protocols
147

148
Complete email protocol implementations including SMTP, POP3, and IMAP4 with support for both client and server operations.
149

150
```python { .api }
151
# Key classes from twisted.mail
152
class smtp.SMTP: ...
153
class pop3.POP3: ...
154
class imap4.IMAP4Server: ...
155
```
156

157
[Email Protocols](./email.md)
158

159
### DNS Client and Server
160

161
DNS protocol implementation with client resolvers, server functionality, and caching capabilities for domain name resolution.
162

163
```python { .api }
164
# Key classes from twisted.names
165
class client.Resolver: ...
166
class dns.Message: ...
167
class dns.Record_A: ...
168
```
169

170
[DNS Implementation](./dns.md)
171

172
### Network Protocols
173

174
Implementations of various network protocols including FTP, IRC, XMPP, AMP (Asynchronous Messaging Protocol), and utilities for building custom protocols.
175

176
```python { .api }
177
# Key classes from twisted.protocols
178
class basic.LineReceiver: ...
179
class amp.AMP: ...
180
class ftp.FTPClient: ...
181
```
182

183
[Network Protocols](./protocols.md)
184

185
### Logging System
186

187
Modern structured logging system with event-based architecture, filtering, and multiple output formats for comprehensive application logging.
188

189
```python { .api }
190
# Key classes from twisted.logger
191
class Logger: ...
192
class LogPublisher: ...
193
class FileLogObserver: ...
194
```
195

196
[Logging System](./logging.md)
197

198
### Distributed Objects
199

200
Perspective Broker (PB) system for distributed object communication and remote method calls across network boundaries.
201

202
```python { .api }
203
# Key classes from twisted.spread.pb
204
class Referenceable: ...
205
class Root: ...
206
class PBClientFactory: ...
207
```
208

209
[Distributed Objects](./distributed.md)
210

211
## Common Error Handling
212

213
Twisted uses several key exception types for error handling:
214

215
```python { .api }
216
# Common exceptions from twisted.internet.error
217
class ConnectionDone(Exception): ...
218
class ConnectionLost(Exception): ...
219
class TimeoutError(Exception): ...
220
class ConnectionRefusedError(Exception): ...
221
```
222

223
Most Twisted APIs use Deferred objects for error propagation:
224

225
```python
226
from twisted.internet import defer
227

228
def handleError(failure):
229
    # Handle the error
230
    print(f"Error occurred: {failure.value}")
231

232
def handleSuccess(result):
233
    # Handle successful result
234
    print(f"Success: {result}")
235

236
d = someAsyncOperation()
237
d.addCallback(handleSuccess)
238
d.addErrback(handleError)
239
```
240

241
## Installation and Dependencies
242

243
```bash
244
# Basic installation
245
pip install Twisted
246

247
# With specific optional dependencies
248
pip install Twisted[tls,http2,conch]
249

250
# Development installation
251
pip install Twisted[dev]
252
```
253

254
**Core Dependencies**:
255
- zope.interface >= 5
256
- constantly >= 15.1  
257
- incremental >= 24.7.0
258
- Automat >= 24.8.0
259
- hyperlink >= 17.1.1
260
- attrs >= 22.2.0
261
- typing_extensions >= 4.2.0
262

263
**Optional Dependencies**:
264
- pyOpenSSL (for TLS/SSL support)
265
- service_identity (for TLS certificate verification)
266
- pycrypto (for SSH support)
267
- pyasn1 (for SSH key formats)