Table of Contents

Twisted Documentation |
--- | ---

Twisted 0.17.4

Quote of the Release:

<gt3> i had a dream guido really did get hit by a bus <jafo> :-( <jafo> He's a nice guy. <gt3> then somehow twisted came standard with it after dash took over <gt3> he seems nice <gt3> but nice doesn't stop a bus

For information on what's new in Twisted 0.17.4, see the ChangeLog file that comes with the distribution, or http://twistedmatrix.com/ChangeLog.txt.

### What is this?

Twisted is an event-based framework for internet applications. It includes a web server, a telnet server, a multiplayer RPG engine, a generic client and server for remote object access, and APIs for creating new protocols and services. Twisted supports integration of the Tk, GTK+, Qt or wxPython event loop with its main event loop. The Win32 event loop is also supported, as is basic support for running servers on top of Jython.

Twisted currently supports the following protocols, all implemented in pure python, most of them as both servers and clients:

- FTP - HTTP - SOCKSv4 - SMTP - IRC - telnet - POP3 - AOL's instant messaging TOC - OSCAR, used by AOL-IM as well as ICQ (client only) - DNS - LDAP (client only) - finger - Echo, discard, chargen and friends - Twisted Perspective Broker

For more information, visit http://www.twistedmatrix.com, or join the list at http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

### What can I do with it?

To install Twisted, just make sure the Twisted-$VERSION/twisted directory is in the "PYTHONPATH" environment variable. For example, if you extracted Twisted-0.17.4.tar.gz to /home/bob/, then you would have something like:

export PYTHONPATH=$PYTHONPATH:/home/bob/Twisted-0.17.4/

in your ~/.bash_profile, ~/.zshrc, ~/.cshrc, etc. If you use Windows NT, 2k, or XP, then set your environment variables by right-clicking on My Computer and selecting Properties. If you use some other version of windows, you'll need to set the variable at a command prompt, or in autoexec.bat, with the `set` command.

Although there is a lot of infrastructure support in Twisted, the immediately useful applications for the end-user are Twisted Web and Instance Messenger. Twisted Web is a webserver, written entirely in python, which is designed to be "zero maintenance". We run the twistedmatrix.com website from it, and I can testify that it has met its goals at least for me! The server can comfortably handle 50 dynamic-content requests per second on fairly old hardware (I have a Pentium II/333); however, since Twisted is entirely in Python, it's quite easy to script the webserver to do whatever you like!

Instance Messenger is a multi-protocol chat client; it's easy to use: just run `t-im` for the GTK+ version, or `im` for the Tkinter version, and an "account manager" window will pop up. You can create and modify accounts with it, and connect to/disconnect from them. Currently it can support Twisted's own chat service, Twisted Words, Internet Relay Chat (IRC), and AOL Instant Messenger (with the TOC protocol).

### Unit Tests

See our unit tests run in a lovely Tkinter GUI, proving that the software is BugFree(TM):

       % admin/runtests

If you're feeling more brave, you can try the new "acceptance tests". These require some setup and are mainly for the developers to decide if it's OK to release, but:

% admin/accepttests

### Basic Servers

There are various servers you can build and run in the main distribution, although they won't be covered here. Twisted servers do not have configuration files; instead, you instantiate a server and put it into a Pickle file; your servers and all of their component objects are saved in that file, and can be loaded with the Twisted Daemon.

Note that the following examples only create the .tap files with the servers inside of them: to actually run the servers, see "Running Servers" below.

The normal type of server to create is a webserver. You can run this command:

        % mktap web --path static

which will make a path-based webserver (one that reads from the filesystem) and serve pages from the provided `static` directory. This will automatically execute CGIs, epys, rpys, and php files. This creates a file named `web.tap`. By default, this server will run on port 8080, but you can change it with the --port option.

You can also create a telnet server:

        % mktap telnet -p 8023 -u username -w password

which will create a python-console telnet server listening on port 8023, which you can log into with the username "username" and the password "password". This creates a file called `telnet.tap`

A generic chat server:

        % mktap words

This creates a chat server application, with 2 different interfaces and a web administration port. Web administration can be conducted on port 8080, the IRC server on 6667, and a PB service on port 8787.

You'll need to create an account with the web tool before you can log in, even using IRC (a "bot" will ask you for your password upon connection).

So far the IRC gateway has only been tested with mIRC, XChat, and ircII; I believe that these are relatively diverse clients, but YMMV.

The "Instance Messenger" client is a TKinter front-end to the various chat services that Twisted can interface with, which are IRC, AIM, and, twisted.words. You can invoke it like this:

        % im

There is also a GTK+ based client:

        % t-im

A AOL Instant Messenger TOC Server is also available:

        % mktap toc -p 5190

which creates the TOC server, running on port 5190. To create a user, simply log in with the username and password you want. If the name is not already taken on the server, it is created. This creates a file called `toc.tap`

### Running Servers

In order to run any of these servers, run this command:

        % twistd -f [application name].tap

You can stop the server at any time by going back to the directory you started it in and running the command:

        % kill `cat twistd.pid`

### Configuring Servers

Once you've created a tap file, you can use a browser based interface to configure it. Run this command:

        % coil [application name].tap

And then point your browser to http://localhost:9080 to see the config interface. Once you've finished configuring the server, hit Ctrl-C in the terminal where you run coil in order to shutdown the web server and save your changes.

### "Spreadable" Webserver

The web server can also host a telnet server as well as other services; mkwebserver --help can detail some of those options. One of the most interesting applications, however, is the distributed webserver; multiple servers can all answer requests on the same port, using the twisted.spread package for "spreadable" computing. In two different directories, run the commands:

        % mktap web --user
        % mktap web --personal [other options, if you desire]

Both of these create a 'web.tap'; you need to run both at the same time. Once you have, go to http://localhost:8080/your_username.twistd/ -- you will see the front page from the server you created with the --personal option. What's happening here is that the request you've sent is being relayed from the central (User) server to your own (Personal) server, over a PB connection. This technique can be highly useful for small "community" sites; using the code that makes this demo work, you can connect one HTTP port to multiple resources running with different permissions on the same machine, on different local machines, or even over the internet to a remote site.

### Documentation and Support

Although this is far from enough, some examples on how to use basic Twisted APIs are located in doc/examples; this might ease the learning curve a little bit, since all these files are kept as short as possible.

As of this release, I realize that Twisted's documentation is rather sparse. I encourage you to read the source code and docstrings, but if you're curious as to what Twisted can do, please feel free to join the mailing list:

http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

or to join #python on irc.openprojects.net for some live help.

Part of the problem with documentation on a project like this is that everything seems obvious to me :-). If you have trouble with a particular aspect of the Twisted system, I'd like to hear about what was confusing and why. The process of your learning may be the material I build a tutorial from, so don't hesitate to ask!

### Copyright

Most of the code in this distribution is (C) Matthew William Lefkowitz, AKA "Glyph". There is 1 exception to this: the `pyunit` directory is a derivative work of PyUnit, which can be found at http://pyunit.sourceforge.net.

Twisted is made available under version 2.1 of the GNU Lesser General Public License. The included LICENSE file describes this in detail.

### Warranty

THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE USE OF THIS SOFTWARE IS WITH YOU.

IN NO EVENT WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE LIBRARY, BE LIABLE TO YOU FOR ANY DAMAGES, EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

Again, see the included LICENSE file for specific legal details.

Table of Contents

This document was automatically generated on Sat Apr 20 01:30:44 2002 by HappyDoc version 2.0