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.
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.
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.
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.
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.
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.
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.
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.
If you’ll be using Twisted’s SSL or SSH features, you’ll need pyOpenSSL and PyCrypto, respectively. OS X ships with pyOpenSSL.
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.
Twisted has two required dependencies.
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.
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.
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.
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.
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.
To verify that the installation worked and that you have the desired version of Twisted installed, import the twisted module from a Python prompt:
$pythonPython 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.
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!
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.
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.
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:
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.
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.
When you installed Twisted, you also installed manpages for the Twisted utilities. This Twisted page has HTML versions of these manpages.
If you get stuck or want advice on a project, there are many excellent Twisted community resources you can look to for help.
Twisted has two main mailing lists:
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.
This is a list for discussion of web technologies related to Twisted.
You can join this list or read the archives.
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.
The Stack Overflow programming Q & A site has built up a large body of Twisted questions and answers.
Twisted developers post sprint reports and release announcements to the Twisted blog.
The personal blogs of Twisted developers are aggregated on Planet Twisted.