<?xml version="1.0"?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml" lang="en"><head><title>Twisted Documentation: The Twisted FAQ</title><link href="../howto/stylesheet.css" type="text/css" rel="stylesheet" /></head><body bgcolor="white"><h1 class="title">The Twisted FAQ</h1><div class="toc"><ol><li><a href="#auto0">General</a></li><ul><li><a href="#auto1">What is Twisted?</a></li><li><a href="#auto2">Why should I use Twisted?</a></li><li><a href="#auto3">I have a problem getting Twisted.</a></li><li><a href="#auto4">Why are there so many parts and subprojects? Isn't Twisted just
Twisted?</a></li></ul><li><a href="#auto5">Stability</a></li><ul><li><a href="#auto6">Does the 1.0 release mean that all of Twisted's APIs are stable?</a></li><li><a href="#auto7">Which parts of Twisted are stable?</a></li></ul><li><a href="#auto8">Installation</a></li><ul><li><a href="#auto9">I run mktap (from site-packages/twisted/scripts/mktap.py)
and nothing happens!</a></li><li><a href="#auto10">Why do the Debian packages for Alphas and Release Candidates have weird versions containing old version numbers?</a></li></ul><li><a href="#auto11">Core Twisted</a></li><ul><li><a href="#auto12">How can I access self.factory from my Protocol's __init__?</a></li><li><a href="#auto13">Where can I find out how to write Twisted servers?</a></li><li><a href="#auto14">When I try to install my reactor, I get errors about a reactor
already being installed. What gives?</a></li><li><a href="#auto15">twistd won't load my .tap file! What's this
Ephemeral nonsense?</a></li><li><a href="#auto16">I get Interrupted system call errors when I use os.popen2. How do I read results from a sub-process in
Twisted?</a></li><li><a href="#auto17">Why don't my spawnProcess programs see my environment variables?</a></li><li><a href="#auto18">My Deferred or DeferredList never fires, so my program just mysteriously
hangs! What's wrong?</a></li><li><a href="#auto19">My exceptions and tracebacks aren't getting printed!</a></li><li><a href="#auto20">How do I use Deferreds to make my blocking code
non-blocking?</a></li><li><a href="#auto21">I get exceptions.ValueError: signal only works in main thread when I
try to run my Twisted program! What's wrong?</a></li><li><a href="#auto22">I'm trying to stop my program with sys.exit(), but Twisted
seems to catch it! How do I exit my program?</a></li><li><a href="#auto23">How do I find out the IP address of the other end of my connection?</a></li><li><a href="#auto24">Why don't Twisted's network methods support Unicode objects as well as
strings?</a></li></ul><li><a href="#auto25">Requests and Contributing</a></li><ul><li><a href="#auto26">Twisted is cool, but I need to add more functionality.</a></li><li><a href="#auto27">I have a patch. How do I maximize the chances the Twisted developers
will include it?</a></li><li><a href="#auto28">And to whom do I send it?</a></li><li><a href="#auto29">My company would love to use Twisted, but it's missing feature X, can you implement it?</a></li></ul><li><a href="#auto30">Documentation</a></li><ul><li><a href="#auto31">Twisted really needs documentation for X, Y or Z - how come it's not documented?.</a></li><li><a href="#auto32">Wow the Twisted documentation is nice! I want my docs to look like that
too!</a></li></ul><li><a href="#auto33">Communicating with us</a></li><ul><li><a href="#auto34">There's a bug in Twisted. Where do I report it?</a></li><li><a href="#auto35">Where do I go for help?</a></li><li><a href="#auto36">How do I e-mail a Twisted developer?</a></li></ul></ol></div><div class="content"><span></span><h2>General<a name="auto0"></a></h2><h3>What is <q>Twisted</q>?<a name="auto1"></a></h3><p>Please see
<a href="http://twistedmatrix.com/products/twisted">Twisted</a></p><h3>Why should I use Twisted?<a name="auto2"></a></h3><p>See <a href="http://twistedmatrix.com/services/twisted-advantage">The
Twisted Advantage</a></p><h3>I have a problem <q>getting</q> Twisted.<a name="auto3"></a></h3><p>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.</p><h3>Why are there so many parts and subprojects? Isn't Twisted just
Twisted?<a name="auto4"></a></h3><p>
As of version 2.0, Twisted was split up into many subprojects, because
it was getting too much to handle in a monolithic release, and we
believe breaking the project into smaller chunks will help people
understand the things they need to understand (There used to be a FAQ
entry here asking <q>Why is Twisted so big?</q>). More information is
available in
the <a href="http://twistedmatrix.com/products/splitfaq">Split
FAQ</a>.
</p><h2>Stability<a name="auto5"></a></h2><h3>Does the 1.0 release mean that all of Twisted's APIs are stable?<a name="auto6"></a></h3><p>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. </p><p>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.</p><h3>Which parts of Twisted are stable?<a name="auto7"></a></h3><p>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.</p><p>In Twisted 1.1, <em>most of twisted.internet, .cred and
.application are completely stable</em> (excepting of course code
marked as deprecated).</p><p>But as always, the only accurate way of knowing a module's stability is reading
the module's docstrings.</p><h2>Installation<a name="auto8"></a></h2><h3>I run mktap (from site-packages/twisted/scripts/mktap.py)
and nothing happens!<a name="auto9"></a></h3><p>Don't run scripts out of <code>site-packages</code>. The Windows
installer should install executable scripts to someplace like
<code>C:\Python22\scripts\</code>, *nix installers put them in
<code>$PREFIX/bin</code>, which should be in your $PATH.</p><h3>Why do the Debian packages for Alphas and Release Candidates have weird versions containing old version numbers?<a name="auto10"></a></h3><p>
An example: 1.0.6+1.0.7rc1-1
</p><p>
In Debian versioning, 1.0.7rc1 is <em>greater than</em> 1.0.7. This
means that if you install a package with Version: 1.0.7rc1, and then
that package gets a new version 1.0.7, apt will not upgrade it for
you, because 1.0.7 looks like an older version. So, we prefix the
previous version to the actual version. 1.0.6+1.0.7rc1 is <em>less
than</em> 1.0.7.
</p><h2>Core Twisted<a name="auto11"></a></h2><h3>How can I access self.factory from my Protocol's __init__?<a name="auto12"></a></h3><p>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
<code>connectionMade</code> method.</p><p>Similarly you shouldn't be doing <q>real</q> work, like connecting to
databases, in a Factory's <code>__init__</code> either. Instead, do that in
<code>startFactory</code>.</p><p>See <a href="servers.html">Writing Servers</a> and
<a href="clients.html">Writing Clients</a> for more details.</p><h3>Where can I find out how to write Twisted servers?<a name="auto13"></a></h3><p>Try <a href="servers.html">Writing Servers</a>.</p><h3>When I try to install my reactor, I get errors about a reactor
already being installed. What gives?<a name="auto14"></a></h3><p>Here's the rule - installing a reactor should always be the
<strong>first</strong> thing you do, and I do mean first. Importing other stuff
before you install the reactor can break your code.</p><p>Tkinter and wxPython support, as they do not install a new reactor, can be
done at any point, IIRC.</p><h3><code>twistd</code> won't load my <code>.tap</code> file! What's this
Ephemeral nonsense?<a name="auto15"></a></h3><p>When the pickled application state cannot be loaded for some reason, it
is common to get a rather opaque error like so:</p><pre class="shell">
% twistd -f test2.tap
Failed to load application: global name 'initRun' is not defined
</pre><p>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 <code>twistd.log</code>
file. Open it up to see the full exception.</p><p>The error might also look like this:</p><pre class="shell">
Failed to load application: <twisted.persisted.styles.Ephemeral instance at
0x82450a4> is not safe for unpickling
</pre><p>To load a <code>.tap</code> 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.</p><p>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 <code>.tap</code> file as something like
<code>__main__.MyProtocol</code>. When the application is reloaded, it will
look for the class definition in <code>__main__</code>, 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.</p><p>The way to fix this is to import the class from the same source file that
defines it: if your source file is called <code>myprogram.py</code> and
defines a class called <code>MyProtocol</code>, you will need to do a
<code>from myprogram import MyProtocol</code> 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 <code>import
myprogram</code> 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 <code>.tap</code> file must be inside an <code>if __name__ ==
'__main__'</code> clause to make sure it is not run twice (or more).</p><p>When you import the class from the module using an <q>external</q> name,
that name will be recorded in the pickled <code>.tap</code> file. When the
<code>.tap</code> is reloaded by <code>twistd</code>, it will look for
<code>myprogram.py</code> to provide the definition of
<code>MyProtocol</code>.</p><p>Here is a short example of this technique:</p><pre class="python">
<span class="py-src-comment"># file dummy.py
</span><span class="py-src-keyword">from</span> <span class="py-src-variable">twisted</span>.<span class="py-src-variable">internet</span> <span class="py-src-keyword">import</span> <span class="py-src-variable">protocol</span>
<span class="py-src-keyword">class</span> <span class="py-src-identifier">Dummy</span>(<span class="py-src-parameter">protocol</span>.<span class="py-src-parameter">Protocol</span>): <span class="py-src-keyword">pass</span>
<span class="py-src-keyword">if</span> <span class="py-src-variable">__name__</span> == <span class="py-src-string">'__main__'</span>:
<span class="py-src-keyword">from</span> <span class="py-src-variable">twisted</span>.<span class="py-src-variable">application</span> <span class="py-src-keyword">import</span> <span class="py-src-variable">service</span>, <span class="py-src-variable">internet</span>
<span class="py-src-variable">a</span> = <span class="py-src-variable">service</span>.<span class="py-src-variable">Application</span>(<span class="py-src-string">"dummy"</span>)
<span class="py-src-keyword">import</span> <span class="py-src-variable">dummy</span>
<span class="py-src-variable">f</span> = <span class="py-src-variable">protocol</span>.<span class="py-src-variable">Factory</span>()
<span class="py-src-variable">f</span>.<span class="py-src-variable">protocol</span> = <span class="py-src-variable">dummy</span>.<span class="py-src-variable">Dummy</span> <span class="py-src-comment"># Note! Not "Dummy"</span>
<span class="py-src-variable">internet</span>.<span class="py-src-variable">TCPServer</span>(<span class="py-src-number">2000</span>, <span class="py-src-variable">f</span>).<span class="py-src-variable">setServiceParent</span>(<span class="py-src-variable">a</span>)
<span class="py-src-variable">a</span>.<span class="py-src-variable">save</span>()
</pre><h3>I get <q>Interrupted system call</q> errors when I use <code class="python">os.popen2</code>. How do I read results from a sub-process in
Twisted?<a name="auto16"></a></h3><p>You should be using <code class="python">reactor.spawnProcess</code> (see
<code base="twisted.internet" class="API">interfaces.IReactorProcess.spawnProcess</code>).
There's also a convenience function, <code base="twisted.internet.utils" class="API">getProcessOutput</code>, in <code class="API">twisted.internet.utils</code>.</p><h3>Why don't my spawnProcess programs see my environment variables?<a name="auto17"></a></h3><p><code base="twisted.internet.interfaces.IReactorProcess" class="API">spawnProcess</code>
defaults to clearing the environment of child processes as a security
feature. You can either provide a dictionary with exactly the name-value
pairs you want the child to use, or you can simply pass in
<code>os.environ</code> to inherit the complete environment. </p><h3>My Deferred or DeferredList never fires, so my program just mysteriously
hangs! What's wrong?<a name="auto18"></a></h3><p>It really depends on what your program is doing, but the most common cause
is this: it <em>is</em> firing -- but it's an error, not a success, and you
have forgotten to add an <a href="glossary.html#errback">errback</a>, so
nothing happens. Always add errbacks!</p><p>The reason Deferred can't automatically show your errors is because
a Deferred can still have callbacks and errbacks added to it even
after a result is available -- so we have no reasonable place to put a
logging call that wouldn't result in spurious tracebacks
that <em>are</em> handled later on. There is a facility for printing
tracebacks when the Deferreds are garbage collected -- call
defer.setDebugging(True) to enable it.</p><h3>My exceptions and tracebacks aren't getting printed!<a name="auto19"></a></h3><p>See previous question.</p><h3>How do I use Deferreds to make my blocking code
non-blocking?<a name="auto20"></a></h3><a name="deferreds-aren't-magic"></a><p>You don't. Deferreds don't magically turn a blocking function call into a
non-blocking one. A Deferred is just a simple object that represents a
<em>deferred result</em>, with methods to allow convenient adding of
callbacks. (This is a common misunderstanding; suggestions on how to make this
clearer in the <a href="defer.html">Deferred Execution</a> howto are
welcome!)</p><p>If you have blocking code that you want to use non-blockingly in Twisted,
either rewrite it to be non-blocking, or run it in a thread. There is a
convenience function, <code base="twisted.internet.threads" class="API">deferToThread</code>, to help you with the
threaded approach -- but be sure to read <a href="threading.html">Using
Threads in Twisted</a>.</p><h3>I get <q>exceptions.ValueError: signal only works in main thread</q> when I
try to run my Twisted program! What's wrong?<a name="auto21"></a></h3><p>The default reactor, by default, will install signal handlers to
catch events like Ctrl-C, SIGTERM, and so on. However, you can't
install signal handlers from non-main threads in Python, which means
that <code>reactor.run()</code> will cause an error. Pass the
<code>installSignalHandlers=0</code> keyword argument to
<code>reactor.run</code> to work around this.</p><h3>I'm trying to stop my program with <code>sys.exit()</code>, but Twisted
seems to catch it! How do I exit my program?<a name="auto22"></a></h3><p>Use <code>reactor.stop()</code> instead. This will cleanly shutdown the
reactor.</p><h3>How do I find out the IP address of the other end of my connection?<a name="auto23"></a></h3><p>The <code>.transport</code> object (which implements the <code base="twisted.internet.interfaces" class="API">ITransport</code> interface) offers a pair
of methods named <code base="twisted.internet.interfaces.ITransport" class="API">getPeer</code> and <code base="twisted.internet.interfaces.ITransport" class="API">getHost</code>.
<code>getPeer</code> will give you a tuple that describes the address of the
system at the other end of the connection. For example:</p><pre class="python">
<span class="py-src-keyword">class</span> <span class="py-src-identifier">MyProtocol</span>(<span class="py-src-parameter">protocol</span>.<span class="py-src-parameter">Protocol</span>):
<span class="py-src-keyword">def</span> <span class="py-src-identifier">connectionMade</span>(<span class="py-src-parameter">self</span>):
<span class="py-src-keyword">print</span> <span class="py-src-string">"connection from"</span>, <span class="py-src-variable">self</span>.<span class="py-src-variable">transport</span>.<span class="py-src-variable">getPeer</span>()
</pre><h3>Why don't Twisted's network methods support Unicode objects as well as
strings?<a name="auto24"></a></h3><p>In general, such methods (eg <code base="twisted.internet.abstract" class="API">FileDescriptor</code>'s <code>write</code>)
are designed to send bytes over the network. These methods use non-Unicode
string objects as a container for the bytes that they send and receive.</p><p>Unicode objects are not byte-based and are an abstraction used for
representing strings of human readable text. In order to send Unicode strings
using these methods, you should explicitly specify a byte-based encoding for
them, for example: <code>s.encode("utf-8")</code> and explicitly decode them
at the receiving end.</p><p>Twisted cannot choose an encoding for you at this level: your encoding
choice will be protocol specific and may need to be specified in the message
you send (for example, HTTP headers include a encoding specification).</p><p>For a more complete discussion of the distinction between Unicode strings
and specific encodings of Unicode strings, see the following articles:</p><ul><li>Dan Sugalski's <a href="http://www.sidhe.org/~dan/blog/archives/000255.html">What the heck is: A
string</a>; and</li><li>Joel Spolsky's <a href="http://www.joelonsoftware.com/articles/Unicode.html">The Absolute
Minimum Every Software Developer Absolutely, Positively Must Know
About Unicode and Character Sets (No Excuses!)</a>.</li></ul><h2>Requests and Contributing<a name="auto25"></a></h2><h3>Twisted is cool, but I need to add more functionality.<a name="auto26"></a></h3><p>Great! Read our the docs, and if you're feeling generous, contribute
patches.</p><h3>I have a patch. How do I maximize the chances the Twisted developers
will include it?<a name="auto27"></a></h3><p>Use unified diff. Either use <code class="shell">svn diff</code>
or, better yet, make a clean checkout and use <code class="shell">diff
-urN</code> between them. Make sure your patch applies cleanly. In
your post to the mailing list, make sure it is inlined and without any
word wrapping.</p><h3>And to whom do I send it?<a name="auto28"></a></h3><p>Add it to the <a href="http://twistedmatrix.com/bugs/">bug tracker</a>, and if it's an urgent or important issue you may want to tell the <a href="http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python">mailing list</a>. about the issue you added</p><h3>My company would love to use Twisted, but it's missing feature X, can you implement it?<a name="auto29"></a></h3><p>You have 3 options:</p><ul><li>Pay one of the Twisted developers to implement the feature.</li><li>Implement the feature yourself.</li><li>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.</li></ul><h2>Documentation<a name="auto30"></a></h2><h3>Twisted really needs documentation for X, Y or Z - how come it's not documented?.<a name="auto31"></a></h3><p>Twisted's documentation is a work in progress, and one that we would
appreciate assistance with. If you notice a gap or flaw in the documentation,
please file a bug in <a href="http://twistedmatrix.com/bugs/">the Twisted bug
tracker</a> and mark it as having topic 'documentation'. Patches
appreciated.</p><h3>Wow the Twisted documentation is nice! I want my docs to look like that
too!<a name="auto32"></a></h3><p>Now you can, with <a href="http://twistedmatrix.com/projects/lore">Lore</a>. </p><h2>Communicating with us<a name="auto33"></a></h2><h3>There's a bug in Twisted. Where do I report it?<a name="auto34"></a></h3><p>Unless it is a show-stopper bug, we usually won't fix it if it's already
fixed in <a href="http://twistedmatrix.com/developers/cvs">Subversion</a>, so
check if it is fixed there. If it is not fixed in Subversion, you should add
it to the <a href="http://twistedmatrix.com/bugs/">bug tracker</a>, including
pertinent information about the bug (hopefully as much information needed to
reproduce it: OS, Subversion versions of any important files, Python version,
code you wrote or things you did to trigger the bug, etc. If the bug appears
to be severe, you should also raise it on the <a href="http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python">mailing
list</a>, with a pointer to the issue already filed in the bug tracker.</p><h3>Where do I go for help?<a name="auto35"></a></h3><p>Ask for help <a href="http://twistedmatrix.com/services/online-help">where
the Twisted team hangs out</a></p><h3>How do I e-mail a Twisted developer?<a name="auto36"></a></h3><p>First, note that in many cases this is the wrong thing to do: if
you have a question about a part of Twisted, it's usually better to
e-mail the mailing list. However, the preferred e-mail addresses for
all Twisted developers are listed in the file <q>CREDITS</q> in the
Subversion repository.</p></div><p><a href="../howto/index.html">Index</a></p><span class="version">Version: 2.5.0</span></body></html>
distrib
>
Mandriva
>
2008.1
>
x86_64
>
media
>
main-release
>
by-pkgid
>
db93d7191b12a3d5ce887da46fc79bf1
>
files
>
109
