twisted documentation

Download Twisted Documentation

Post on 02-Jan-2017

225 views

Category:

Documents

5 download

Embed Size (px)

TRANSCRIPT

  • Twisted DocumentationRelease 17.9.1dev0

    Twisted Matrix Labs

    Jan 09, 2018

  • Contents

    1 Installing Twisted 31.1 Installing Optional Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

    2 Twisted Core 52.1 Developer Guides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3132.3 Specifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3152.4 Development of Twisted . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318

    3 Twisted Conch (SSH and Telnet) 3613.1 Developer Guides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3613.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369

    4 Twisted Mail (SMTP, POP, and IMAP) 3714.1 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3714.2 Developer Guides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3714.3 Twisted Mail Tutorial: Building an SMTP Client from Scratch . . . . . . . . . . . . . . . . . . . . . 374

    5 Twisted Names (DNS) 3855.1 Developer Guides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3855.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395

    6 Twisted Pair 3976.1 Developer Guides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3976.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399

    7 Twisted Web 4017.1 Developer Guides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4017.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 472

    8 Twisted Words (IRC and XMPP) 4758.1 Developer Guides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4758.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480

    9 Historical Documents 4819.1 2003 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4819.2 Previously . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 482

    i

  • ii

  • Twisted Documentation, Release 17.9.1dev0

    Contents:

    Contents 1

  • Twisted Documentation, Release 17.9.1dev0

    2 Contents

  • CHAPTER 1

    Installing Twisted

    1.1 Installing Optional Dependencies

    This document describes the optional dependencies that Twisted supports. The dependencies are python packages thatTwisteds developers have found useful either for developing Twisted itself or for developing Twisted applications.

    The intended audience of this document is someone who is familiar with installing optional dependencies using pip.

    If you are unfamiliar with the installation of optional dependencies, the python packaging tutorial can show you how.For a deeper explanation of what optional dependencies are and how they are declared, please see the setuptoolsdocumentation.

    The following optional dependencies are supported:

    dev - packages that aid in the development of Twisted itself.

    pyflakes

    twisted-dev-tools

    python-subunit

    Sphinx

    TwistedChecker, only available on python2

    pydoctor, only available on python2

    tls - packages that are needed to work with TLS.

    pyOpenSSL

    service_identity

    idna

    conch - packages for working with conch/SSH.

    pyasn1

    cryptography

    3

    https://pip.pypa.io/en/latest/quickstart.htmlhttps://packaging.python.org/en/latest/installing.html#exampleshttps://pythonhosted.org/setuptools/setuptools.html#declaring-extras-optional-features-with-their-own-dependencieshttps://pythonhosted.org/setuptools/setuptools.html#declaring-extras-optional-features-with-their-own-dependencieshttps://pypi.python.org/pypi/pyflakeshttps://pypi.python.org/pypi/twisted-dev-toolshttps://pypi.python.org/pypi/python-subunithttps://pypi.python.org/pypi/Sphinx/1.3b1https://pypi.python.org/pypi/TwistedCheckerhttps://pypi.python.org/pypi/pydoctorhttps://pypi.python.org/pypi/pyOpenSSLhttps://pypi.python.org/pypi/service_identityhttps://pypi.python.org/pypi/idnahttps://pypi.python.org/pypi/pyasn1https://pypi.python.org/pypi/cryptography

  • Twisted Documentation, Release 17.9.1dev0

    soap - the SOAPpy package to work with SOAP.

    serial - the pyserial package to work with serial data.

    all_non_platform - installs tls, conch, soap, and serial options.

    macos_platform - all_non_platform options and pyobjc to work with Objective-C apis.

    windows_platform - all_non_platform options and pypiwin32 to work with Windowss apis.

    http2 - packages needed for http2 support.

    h2

    priority

    Installing Optional Dependencies: documentation on how to install Twisteds optional dependencies.

    4 Chapter 1. Installing Twisted

    https://pypi.python.org/pypi/SOAPpyhttps://pypi.python.org/pypi/pyserialhttps://pypi.python.org/pypi/pyobjchttps://pypi.python.org/pypi/pypiwin32https://pypi.python.org/pypi/h2https://pypi.python.org/pypi/priority

  • CHAPTER 2

    Twisted Core

    2.1 Developer Guides

    2.1.1 The Vision For Twisted

    Many other documents in this repository are dedicated to defining what Twisted is. Here, I will attempt to explain notwhat Twisted is, but what it should be, once Ive met my goals with it.

    First, Twisted should be fun. It began as a game, it is being used commercially in games, and it will be, I hope, aninteractive and entertaining experience for the end-user.

    Twisted is a platform for developing internet applications. While Python by itself is a very powerful language, thereare many facilities it lacks which other languages have spent great attention to adding. It can do this now; Twisted isa good (if somewhat idiosyncratic) pure-python framework or library, depending on how you treat it, and it continuesto improve.

    As a platform, Twisted should be focused on integration. Ideally, all functionality will be accessible through all proto-cols. Failing that, all functionality should be configurable through at least one protocol, with a seamless and consistentuser-interface. The next phase of development will be focusing strongly on a configuration system which will unifymany disparate pieces of the current infrastructure, and allow them to be tacked together by a non-programmer.

    2.1.2 Writing Servers

    Overview

    This document explains how you can use Twisted to implement network protocol parsing and handling for TCP servers(the same code can be reused for SSL and Unix socket servers). There is a separate document covering UDP.

    Your protocol handling class will usually subclass twisted.internet.protocol.Protocol. Most protocol handlers inheriteither from this class or from one of its convenience children. An instance of the protocol class is instantiated per-connection, on demand, and will go away when the connection is finished. This means that persistent configuration isnot saved in the Protocol.

    5

    https://twistedmatrix.com/documents/17.9.1dev0/api/twisted.internet.protocol.Protocol.html

  • Twisted Documentation, Release 17.9.1dev0

    The persistent configuration is kept in a Factory class, which usually inherits from twisted.internet.protocol.Factory.The buildProtocol method of the Factory is used to create a Protocol for each new connection.

    It is usually useful to be able to offer the same service on multiple ports or network addresses. This is why theFactory does not listen to connections, and in fact does not know anything about the network. See the endpointsdocumentation for more information, or IReactorTCP.listenTCP and the other IReactor*.listen* APIs for thelower level APIs that endpoints are based on.

    This document will explain each step of the way.

    Protocols

    As mentioned above, this, along with auxiliary classes and functions, is where most of the code is. A Twisted protocolhandles data in an asynchronous manner. The protocol responds to events as they arrive from the network and theevents arrive as calls to methods on the protocol.

    Here is a simple example:

    from twisted.internet.protocol import Protocol

    class Echo(Protocol):

    def dataReceived(self, data):self.transport.write(data)

    This is one of the simplest protocols. It simply writes back whatever is written to it, and does not respond to all events.Here is an example of a Protocol responding to another event:

    from twisted.internet.protocol import Protocol

    class QOTD(Protocol):

    def connectionMade(self):self.transport.write("An apple a day keeps the doctor away\r\n")self.transport.loseConnection()

    This protocol responds to the initial connection with a well known quote, and then terminates the connection.

    The connectionMade event is usually where setup of the connection object happens, as well as any initial greetings(as in the QOTD protocol above, which is actually based on RFC 865). The connectionLost event is wheretearing down of any connection-specific objects is done. Here is an example:

    from twisted.internet.protocol import Protocol

    class Echo(Protocol):

    def __init__(self, factory):self.factory = factory

    def connectionMade(self):self.factory.numProtocols = self.facto