The Twisted FAQ

What is Twisted?

Please see Twisted

Why should I use Twisted?

See The Twisted Advantage

I have a problem getting Twisted.

Did you check the HOWTO collection? There are so many documents there that they might overwhelm you... try starting from the index, reading through the overviews and seeing if there seems to be a chapter which explains what you need to. You can try reading the PostScript or PDF formatted books, inside the distribution. And, remember, the source will be with you... always.

Why is Twisted so big?

Twisted is a lot of things, rolled into one big package. We're not sure if it'll stay this way, yet, but for now, if you have only specific needs, we recommend grabbing the big Twisted tarball, and if you want, you can run the 'setup.py' script with a modified config file to generate a package with only certain Twisted sub-packages. Twisted as a whole makes it into many operating system distributions (FreeBSD, Debian and Gentoo, at least) so size shouldn't be an issue for the end developer or user. In addition, packaging Twisted as a whole makes sure the end users do not have to worry about versioning parts of Twisted and inter-version compatibility.

If you are distributing Twisted to end-users, you can base your distribution on the Nodocs packages, which are signficantly smaller.

But won't Twisted bloat my program, since it's so big?

No. You only need to import the sub-packages which you want to use, meaning only those will be loaded into memory. So if you write a low-level network protocol, you'd only import twisted.internet, leaving out extraneous things like twisted.web, etc. Twisted itself is very careful with internal dependancies, so importing one subpackage is not likely to import the whole twisted package.

Does the 1.0 release mean that all of Twisted's APIs are stable?

No, only specific parts of Twisted are stable, i.e. we only promise backwards compatibility for some parts of Twisted. While these APIs may be extended, they will not change in ways that break existing code that uses them.

While other parts of Twisted are not stable, we will however do our best to make sure that there is backwards compatibility for these parts as well. In general, the more the module or package are used, and the closer they are to being feature complete, the more we will concentrate on providing backwards compatibility when API changes take place.

Which parts of Twisted 1.0 are stable?

Only modules explictily marked as such can be considered stable. Semi-stable modules may change, but not in a large way and some sort of backwards-compatibily will probably be provided. If no comment about API stability is present, assume the module is unstable.

In Twisted 1.0, most of twisted.internet is completely stable, other than:

1. UDP support
2. twisted.internet.win32eventreactor - will be replaced with win32support in future.

How can I access self.factory from my Protocol's __init__?

You can't. A Protocol doesn't have a Factory when it is created. Instead, you should probably be doing that in your Protocol's connectionMade method.

Similarly you shouldn't be doing real work, like connecting to databases, in a Factory's __init__ either. Instead, do that in startFactory.

See Writing Servers and Writing Clients for more details.

Is the Twisted web server a toy?

No. It is a production grade server. It is running continously on several sites and has been proven quite stable. The server can take loads of up to 3000 users at a time and still keep churning several million requests a day, even on low end hardware. It can serve static files or dynamically rendered pages.

But can Twisted Web do PHP?

Yes. It works out-of-the-box, so long as you've got the standalone php interpreter installed. You might also want to take a look at Woven, Twisted's native web templating system.

And can Twisted Web do virtual hosting?

Can it ever!

You can decide to go with one big process for all of them, a front server and a seperate server for each virtual host (for example, for permission reasons), and you can even mix-and-match between Apache and Twisted (for example, put Apache in the front and have Twisted handle some subset of the virtual host).

Where can I find out how to write Twisted servers?

Try Writing Servers.

Twisted is cool, but I need to add more functionality.

Great! Read our the docs, and if you're feeling generous, contribute patches.

I have a patch. How do I maximize the chances the Twisted developers will include it?

Use unified diff. Either use cvs diff -u or, better yet, make a clean checkout and use diff -urN between them. Make sure your patch applies cleanly. Then, send it to the mailing list inlined and without any word wrapping.

Twisted really needs documentation for X, Y or Z - how come it's not documented?.

We are doing the best we can, and there is documentation in progress for many parts of Twisted. There is a limit to how much we can do in our free time. See also the answer to the next question.

My company would love to use Twisted, but it's missing feature X, can you implement it?

You have 3 options:

• Pay one of the Twisted developers to implement the feature.
• Implement the feature yourself.
• Add a feature request to our bug tracker. We will try to implement the feature, but there are no guarantees when and if this will happen.

Help!

Ask for help where the Twisted team hangs out

I have this cool patch. To whom do I send it?

To the mailing list. If no one picks it up after a days, it's recommended that you add it to the bug tracker so that it doesn't get lost.

There's a bug in Twisted. Where do I report it?

Unless it is a show-stopper bug, we usually won't fix it if it's already fixed in CVS, so you would do well to look there. Then send any pertinent information about the bug (hopefully as much information needed to reproduce it: OS, CVS versions of any important files, Python version, code you wrote or things you did to trigger the bug, etc.) to the mailing list. If no one answers immediately, you should add it to the bug tracker.

How do I use twisted.web to do complex things?

See the Twisted.Web Howto.

I've been using Woven since before it was called Woven. I just upgraded and now I'm getting a confusing traceback talking about INodeMutator. What gives?

You probably have code that's survived the upgrade from PyXML's minidom to Twisted's microdom. Try deleting any .pxp files that you have lying around and the error will probably go away.

When I try to install my reactor, I get errors about a reactor already being installed. What gives?

Here's the rule - installing a reactor should always be the first thing you do, and I do mean first. Importing other stuff before you install the reactor can break your code.

Tkinter and wxPython support, as they do not install a new reactor, can be done at any point, IIRC.

Wow the Twisted documentation is nice! I want my docs to look like that too!

Now you can, with twisted.lore. See the manual pages for generatelore and html2latex. For source format documentation, see the documentation standard description.

twistd won't load my .tap file!

When the pickled application state cannot be loaded for some reason, it is common to get a rather opaque error like so:

% twistd -f test2.tap 

Failed to load application: global name 'initRun' is not defined

The rest of the error will try to explain how to solve this problem, but a short comment first: this error is indeed terse -- but there is probably more data available elsewhere -- namely, the twistd.log file. Open it up to see the full exception.

To load a .tap file, as with any unpickling operation, all the classes used by all the objects inside it must be accessible at the time of the reload. This may require the PYTHONPATH variable to have the same directories as were available when the application was first pickled.

A common problem occurs in single-file programs which define a few classes, then create instances of those classes for use in a server of some sort. If the class is used directly, the name of the class will be recorded in the .tap file as something like __main__.MyProtocol. When the application is reloaded, it will look for the class definition in __main__, which probably won't have it. The unpickling routines need to know the module name, and therefore the source file, from which the class definition can be loaded.

The way to fix this is to import the class from the same source file that defines it: if your source file is called myprogram.py and defines a class called MyProtocol, you will need to do a from myprogram import MyProtocol before (and in the same namespace as) the code that references the MyProtocol class. This makes it important to write the module cleanly: doing an import myprogram should only define classes, and should not cause any other subroutines to get run. All the code that builds the Application and saves it out to a .tap file must be inside an if __name__ == '__main__' clause to make sure it is not run twice (or more).

When you import the class from the module using an external name, that name will be recorded in the pickled .tap file. When the .tap is reloaded by twistd, it will look for myprogram.py to provide the definition of MyProtocol.

Here is a short example of this technique: