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:
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 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 Unit TestsSee 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 ServersThere 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 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 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 Running ServersIn 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 ServersOnce 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" WebserverThe 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 SupportAlthough 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 Twisted is made available under version 2.1 of the GNU Lesser General Public License. The included LICENSE file describes this in detail. WarrantyTHIS 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. |