Twisted Network Programming Essentials, 2nd Edition

Chapter 1. Getting Started

Before you can start developing applications using Twisted, you’ll need to download and install Twisted and its dependencies. This chapter walks you through the installation process on various operating systems. It also shows you how to add the Twisted utilities to your path, familiarize yourself with the Twisted documentation, and get answers to your questions from the Twisted community.

These instructions assume that you are familiar with Python and, in the case of source installations, comfortable navigating and installing packages from the command line.

Twisted requires Python 2.6 or 2.7. Support for Python 3.0 is in progress at the time of this writing.

Installing Twisted

First things first: you need to get Twisted installed on your computer. Downloads and instructions for installing Twisted on various operating systems can be found on the Twisted home page, with additional instructions and links to older releases at this Twisted page. To enable additional functionality in Twisted, you’ll have to install a couple of optional packages as well.

You can find everything you need on the Twisted website, but if you’d like you can also browse this page on PyPI for the source, Windows installers, and download statistics.

Installation on Linux

All of the popular Linux distributions maintain a python-twisted package as well as packaged versions of Twisted’s dependencies. To install Twisted on a dpkg-based system, run:

    apt-get install python-twisted

On an rpm-based system, run:

    yum install python-twisted

That’s it! You now have a functional Twisted installation. If you want to use some of Twisted’s extra features or learn about installing from source on Linux, read on. Otherwise, you can skip to Testing Your Installation.

More package options and optional dependencies

Twisted also maintains an Ubuntu PPA at the “Twisted-dev” team Launchpad page with packages for the latest Twisted version on all active Ubuntu releases.

If you’ll be using Twisted’s SSL or SSH features, you can find the pyOpenSSL and PyCrypto packages as python-openssl and python-crypto, respectively.

If Twisted isn’t packaged for your platform, or you want a newer version that hasn’t been packaged for your distribution release yet, please refer to the instructions below in Installing from Source.

Installation on Windows

Twisted prepares 32-bit and 64-bit MSI and EXE installers for Windows. If you’re not sure which version you need, the 32-bit MSI will always work.

Download and run both the Twisted installer and the zope.interface installer from the sidebar on the Twisted home page.

That’s it! You now have a functional Twisted installation. If you want to use some of Twisted’s extra features or learn about installing from source on Windows, read on. Otherwise, take a look at the section below on adding Twisted utilities to your PATH, then skip ahead to Testing Your Installation.

Optional dependencies

If you’ll be using Twisted’s SSL or SSH features, please also install pyOpenSSL and PyCrypto. You can find Windows installers for these packages at this Twisted download page.

Adding Twisted utilities to your PATH

Twisted includes a number of utilities that you’ll use to run and test your code. On Windows, the location of these utilities is not automatically added to your PATH, so to run them you have to supply the full path to the program. To make life easier, add these utilities to your PATH so that you can run them by name instead.

Twisted’s utilities will be installed in the Python Scripts directory, typically in a location such as C:\Python27\Scripts. Edit your PATH to include the path to the Scripts directory.

After adding the Scripts directory to your PATH, you should be able to run the Twisted utilities by name. Test your changes by running:

    trial.py

at a new command prompt. The usage message for Twisted’s Trial unit testing framework should be displayed.

To avoid typing the .py extension for these utilities, add '.py' to your PATHEXT environment variable. After doing that, at a new command prompt you should be able to run:

    trial

by itself.

Installation on OS X

OS X versions 10.5 and later ship with a version of Twisted. If you are running an older version of OS X, or you want a newer version of Twisted, please refer to the instructions in the next section on installing from source. Otherwise, that’s it—you have a functional Twisted installation! If you want to use some of Twisted’s extra features or learn about installing from source on OS X, read on. Otherwise, you can skip to Testing Your Installation.

Optional dependencies

If you’ll be using Twisted’s SSL or SSH features, you’ll need pyOpenSSL and PyCrypto, respectively. OS X ships with pyOpenSSL.

Installing from Source

If you’re on an operating system for which no Twisted binary packages are available or you want to run a newer version of Twisted than has been packaged for your system, you’ll need to install from source.

Required Dependencies

Twisted has two required dependencies.

Installing a C compiler

Since installing Twisted from source involves compiling C code, on OS X or Windows you’ll need to install a C compiler before you can install Twisted.

Installing zope.interface

When installing from source, before you can use Twisted, you’ll also need to install zope.interface, which you can download from the sidebar on theTwisted home page.

Installing Twisted from a Release Tarball

To install the latest Twisted release from source, first download the release tarball from this Twisted download page.

After downloading the tarball, uncompress and unpack it with a command like:

    tar xvfj Twisted-12.0.0.tar.bz2

Then cd into the resulting directory and run:

    python setup.py install

with administrative privileges. This will install the Twisted library and utilities.

Installing Twisted from a Source Checkout

If you’d like to use the development version of Twisted, you can check out the Twisted Subversion (SVN) repository.

You may first need to install a Subversion client. On a dpkg-based system you can use:

    apt-get install subversion

and on an rpm-based system you can use:

    yum install subversion

On Windows, one popular GUI SVN client is TortoiseSVN, which you can download from the Tigris.org page on TortoiseSVN. Recent versions of OS X come with Subversion installed.

Once you have a Subversion client installed, check out the Twisted repository with:

    svn checkout svn://svn.twistedmatrix.com/svn/Twisted/trunk TwistedTrunk

Then cd into the resulting TwistedTrunk directory and run:

    python setup.py install

with administrative privileges. This will install the Twisted library and utilities.

Installing Optional Dependencies from Source

If pyOpenSSL or PyCrypto binaries are not available for your operating system, you can download and compile the source packages from the pyOpenSSL Launchpad page and the Dlitz.net PyCrypto page, respectively.

Testing Your Installation

To verify that the installation worked and that you have the desired version of Twisted installed, import the twisted module from a Python prompt:

    $ python
    Python 2.6.6 (r266:84292, Dec 26 2010, 22:31:48)
    [GCC 4.4.5] on linux2
    Type "help", "copyright", "credits" or "license" for more information.
    >>> import twisted
    >>> twisted.__version__
    '12.0.0'
    >>>

If the import twisted statement runs with no errors, you have a working Twisted installation.

If you’ve installed pyOpenSSL to use Twisted’s SSL features, you can test that that installation worked with:

    >>> import OpenSSL
    >>> import twisted.internet.ssl
    >>> twisted.internet.ssl.SSL

If you don’t see any errors, you’ve successfully added SSL support to your Twisted installation.

If you’ve installed PyCrypto to use Twisted’s SSH features, you can test that that installation worked with:

    >>> import Crypto
    >>> import twisted.conch.ssh.transport
    >>> twisted.conch.ssh.transport.md5

If you don’t see any errors, you’ve successfully added SSH support to your Twisted installation.

Tip

If you have more than one version of Python installed, keep in mind that Twisted will be installed for only the version of Python you’re using when you run setup.py. To check your Python version, run python -V.

Congratulations—you now have a working Twisted installation and the tools you need to start developing applications using Twisted!

Using the Twisted Documentation

Twisted includes several types of documentation: extensive API documentation, HOWTOs, tutorials, examples, and manpages. It’s a good idea to familiarize yourself with this documentation now so that you’ll be able to refer to it during the development process.

API Documentation

A complete API reference can be found on the Twisted website. The pages in the API documentation are automatically generated from the source code using lore, a custom documentation tool developed as part of Twisted.

API references are also maintained for all prior releases. To view the documentation for an older version of Twisted, just replace “current” in the above URL with the appropriate version number, as in this Twisted webpage.

Subproject Documentation

Twisted is developed as a set of subprojects, and each subproject has additional documentation in its section of the Twisted site. For example, you can access documentation on the Twisted Core networking libraries, and documentation on Twisted Web. You can also check out links to the full list of projects and documentation.

Within each subproject’s documentation, you’ll find the following types of information:

HOWTOs

These documents describe specific features of Twisted and how to use them. The HOWTOs don’t cover every part of Twisted, but they can provide a helpful starting point for certain tasks. Included in the HOWTOs is a tutorial called “Twisted from Scratch” that walks through building an extensible, configurable, robustly deployable service in Twisted from scratch.

Examples

These are examples of short and specific Twisted programs. Like the HOWTOs, these aren’t comprehensive but can be an excellent resource when you need a working example of a certain feature. The Twisted Core documentation includes examples of basic TCP, UDP, and SSL servers and clients.

Manual pages

When you installed Twisted, you also installed manpages for the Twisted utilities. This Twisted page has HTML versions of these manpages.

Finding Answers to Your Questions

If you get stuck or want advice on a project, there are many excellent Twisted community resources you can look to for help.

Mailing Lists

Twisted has two main mailing lists:

twisted-python

This is a general discussion list for Twisted. It’s the main mailing list for asking development questions. It is also the place where Twisted releases and releases for projects that use Twisted are announced. Folks also use this list to organize sprints, discuss tickets, ask for design feedback, and talk about maintaining the Twisted website, Buildbots, and the rest of the project infrastructure.

You can join this list or read the archives.

twisted-web

This is a list for discussion of web technologies related to Twisted.

You can join this list or read the archives.

IRC Channels

Twisted users and developers ask questions and get help in the #twisted and #twisted.web IRC channels on the Freenode network. These are very active channels, but if you don’t get an immediate answer on IRC, try sending a message to the appropriate mailing list.

In #twisted, you’ll find a helpful bot named kenaan that sends messages when tickets are opened, put up for review, or resolved, and it can be told to monitor Buildbot builds.

Stack Overflow

The Stack Overflow programming Q & A site has built up a large body of Twisted questions and answers.

Twisted Blogs

Twisted developers post sprint reports and release announcements to the Twisted blog.

The personal blogs of Twisted developers are aggregated on Planet Twisted.