Twisted

Twisted is a mature, event-driven networking framework for Python built around the reactor pattern, offering asynchronous implementations of a wide range of network protocols out of the box — HTTP, SSH, IMAP, POP3, SMTP, DNS, IRC, XMPP, and more — along with the Deferred abstraction for composing chains of asynchronous callbacks, a pattern that predates async/await in the language and still interoperates with it today.

Beyond protocol implementations, Twisted ships an application framework (twisted.application, twistd) for structuring and running long-lived network services, a plugin system for extending its tooling, and Trial, a unit-testing framework tailored to asynchronous, Deferred-based code. It has powered production networking infrastructure for over two decades and remains actively maintained with a strong focus on backward compatibility and type safety.

What You Get

• A production-grade asynchronous reactor implementing select/poll/epoll/kqueue/IOCP event loops, plus support for third-party reactors
• Ready-made protocol implementations for HTTP, SSH, Telnet, SMTP, IMAP, POP3, DNS, IRC, and XMPP
• The Deferred API for chaining asynchronous callbacks and error handlers, with Deferred.fromCoroutine/ensureDeferred bridging to native async/await
• twisted.application and twistd for structuring and daemonizing long-running network services
• Trial, an async-aware unit-testing framework, plus twisted.plugin for pluggable tooling discovery

Common Use Cases

• Building custom asynchronous TCP/UDP/TLS servers and clients from scratch
• Implementing SSH servers and clients via twisted.conch (used by projects like Buildbot)
• Running lightweight custom DNS servers or resolvers with twisted.names
• Writing IRC/XMPP bots and chat infrastructure with twisted.words
• Serving WSGI applications or building HTTP proxies and clients with twisted.web

Under The Hood

Architecture Twisted’s design centers on the reactor pattern (twisted.internet.base.ReactorBase and platform-specific implementations such as the select, epoll, and kqueue reactors), which multiplexes file-descriptor readiness, timed calls, and thread-pool results into a single event loop. Protocols are implemented via Protocol/Factory pairs that plug into the reactor through formal zope.interface contracts (dozens of IReactor* interfaces defined in twisted/internet/interfaces.py), giving clean separation between transport, protocol logic, and application code. Asynchronous results flow through Deferred (twisted/internet/defer.py), which chains callback/errback pairs and interoperates with native coroutines via fromCoroutine/ensureDeferred. The application layer (twisted.application.service, twisted.application.internet) composes these into long-running services launched by twistd, with twisted.plugin providing a cache-backed plugin discovery mechanism. Because nearly everything is written against the IReactor* interfaces rather than concrete implementations, third-party reactors can be swapped in without touching protocol code.

Tech Stack Twisted targets Python 3.10+, builds via hatchling with hatch-fancy-pypi-readme and incremental for versioning, and its core runtime dependencies are zope.interface, constantly, incremental, automat (state machines), hyperlink (URL parsing), attrs, and typing_extensions. Optional extras layer in pyopenssl/service_identity/idna for TLS, cryptography/appdirs/bcrypt for SSH support in conch, and pyserial for serial-port protocols. Development tooling includes pyflakes/flake8 and mypy for linting and type checking, pre-commit hooks, a tox-driven test matrix across reactor backends, and towncrier for changelog management. Twisted itself is a library embedded into arbitrary long-running Python processes rather than a hosted service, with twistd acting as the process supervisor.

Code Quality The repository has dozens of dedicated test subpackages, one per subsystem (internet/test, web/test, conch/test, mail/test, and more), run through Trial, Twisted’s own Deferred-aware test framework, with tox environments for coverage and for exercising multiple reactor backends via the TWISTED_REACTOR environment variable. CI enforces pyflakes/flake8 linting and mypy static type checking through pre-commit, and the codebase carries extensive PEP 484 type annotations along with a py.typed marker. Error handling favors explicit Failure objects wrapping tracebacks, propagated through Deferred errbacks rather than swallowed silently. Naming and structure follow a long-documented, lint-enforced coding standard. Overall: comprehensive test coverage, typed, linted, and CI-gated.

API Design Twisted’s public API centers on subclassing Protocol/Factory and returning or chaining Deferred objects — an explicit, highly composable pattern that predates asyncio. Ergonomics have improved via Deferred.fromCoroutine and ensureDeferred, letting new code use async/await while still interoperating with the long-standing Deferred-based ecosystem, though the dual-API surface (Deferred callbacks vs async/await) adds a real learning curve for newcomers. Documentation is extensive — a hosted Read the Docs site, a pydoctor-generated API reference, and per-subsystem example scripts — and naming stays consistent across subsystems (Protocol/Factory/Transport per protocol family), but the sheer surface area across web, conch, mail, names, words, and positioning means getting productive in any one subsystem still requires reading real docs rather than guessing from the API alone.