Ignore changes in the amount of whitespace
Differences between version dated 2003-07-11 20:12:17 and 2007-03-26 18:24:48
(spanning 12 versions)
Deletions are marked like this.
Additions are marked like this.
== Introduction ==
This is a first cut at combining the [http://peak.telecommunity.com PEAK] and [http://twistedmatrix.com/ Twisted] frameworks. We've taken the echoserver example from the doc/examples directory in the Twisted distribution, and "PEAK-ified" the Echo protocol to be a PEAK component. This example also shows a trivial use of the PEAK executable ZConfig and .ini machinery.
#format rst
== Prerequisites ==
This example requires that you have the [http://peak.telecommunity.com PEAK] and [http://twistedmatrix.com/ Twisted] frameworks available on your system. More specifically, I am using PEAK from cvs as of July 10th, 2003, and the 1.0.5 release of Twisted. Please make sure you have these on your system and working before proceeding. Additionally, this example was done on a Linux system. The shell scripts probably won't work unless you have [http://www.cygwin.com/ Cygwin] installed. If someone wants to contribute some .bat files, that would be great. Once you've done this, you may need to edit one file: '''setup-path'''. This is used if you've installed Twisted or some other library in some non-standard path, and you need to add it to your '''PYTHONPATH'''. This file is commented and should be self explanitory.
Getting Started
---------------
== The Example Files ==
Download the Echo Server example files '''Here''': attachment:echoserver-example.tar.gz
PEAK and Twisted work very well together thanks to the the
peak.commands.EventDriven class, a top level container for
reactor-based applications. The following shows an XML-RPC server
based on Twisted's XML-RPC HOWTO__::
from peak.api import binding, commands, running
from twisted.web import xmlrpc, server
class Example(xmlrpc.XMLRPC):
"""An example object to be published."""
def xmlrpc_echo(self, x):
"""Return all passed args."""
return x
def xmlrpc_add(self, a, b):
"""Return sum of arguments."""
return a + b
class App(commands.EventDriven):
example = binding.Make(Example)
server = binding.Make(lambda self: server.Site(self.example))
port = binding.Make(lambda: 7080)
reactor = binding.Obtain(running.ITwistedReactor)
__onStart = binding.Make(
lambda self: self.reactor.listenTCP(self.port, self.server),
uponAssembly=True
)
__ http://twistedmatrix.com/projects/web/documentation/howto/xmlrpc.html
The Example class is lifted verbatim from the HOWTO. Note how the
Twisted reactor is obtained in the App class, and how the __onStart
method tells the reactor to listen with the given server object and
port number.
If saved in a file called ``twistedpeak.py``, this code can be run as
follows (on Unix/Linux systems)::
PYTHONPATH=. peak import:twistedpeak.App
The example client code from the HOWTO works exactly the same::
>>> import xmlrpclib
>>> s = xmlrpclib.Server('http://localhost:7080/')
>>> s.echo("lala")
'lala'
>>> s.add(1, 2)
3
This code can be used as a starting point for any kind of Twisted
application.
Configuration and Binding
-------------------------
The code above is slightly longer than the example shown in the HOWTO,
but because of PEAK's component-oriented features, especially its
configuration and binding facilities, it is much more flexible. Since
``commands.EventDriven`` is a descendent of PEAK's base component
class, the ``App`` class is also a component class. This primarily
means two things:
- instances of it can be located in a hierarchy of other components;
components can find each other in various ways without needing to
know anything about the structure of the application as a
whole. This promotes loose coupling, which can lead to more flexible
applications and more reusable code. Components can optionally
"offer" their properties for use by other components in the system.
- component objects are easily configurable by various means,
including external configuration files (.ini-style, ZConfig),
internally via "property names", and through keyword parameters when
directly instantiated.
A component hierarchy always has a "root" object. In our example the
root object is created by the ``peak`` script, which is installed to
an executable directory by PEAK's ``setup.py`` installer script. The
``peak`` script is a simple launcher which takes a URL-like recipe for
finding a "runnable" object to load and run.
...
Notes
-----
This page is a replacement for the one originally created by Joel
Boehland in July 2003. Unfortunately his code examples were included
in a separate tar archive which has since been lost. Without the
code, config files, and shell scripts, the page was no longer usable.
== Running The Example ==
In ascending order of complexity, you can run the following scripts in the root directory:
1. '''run-tp''' This script will call the peak script (installed when you installed the peak distribution), and it in turn will call the twistedpeak.echoserver:EchoRunner class. This will start an EchoServer listening on port 8090 which will just echo back what you send it. Once you've started this script, test it by running: {{{
telnet localhost 8090
}}}
2. '''run-tp2''' This script will call the peak script (installed when you installed the peak distribution), and it in turn will call the twistedpeak.echoserver2:Echo2Runner class. This will start an EchoServer listening on port 8091 which will just echo back what you send it, prepended with: ''you said: '' This example is slightly more complicated, as it uses PEAK's logging system to log what the client sends to it. Once you've started this script, test it by running: {{{
telnet localhost 8091
}}}
3. '''run-tp-schema''' This script kicks off quite a lot. First of all it will utilize the PEAK's ZConfig and .ini machinery. See files '''tp.zcfg''', and '''tp.ini''' for more details. Essentially, the '''tp.ini''' defines the logging that the Echo2 server uses. By default, it will log all client connections to the file '''logs/echoserver.log'''. You can change it to log to stderr by editing the file (there are comments how to do this in the file). The '''tp.zcfg''' file is more complicated. You may want to familiarize yourself with the ZConfig machinery first. Here's a good [http://www.zope.org/Members/mcdonc/Presentations/ZConfigPaper Start]. If you go to the file '''tp.zcfg''', you will see sections for EchoRunner and EchoRunner2. For EchoRunner, you can configure the port it listens on, and for EchoRunner2 you can configure the port it listens on, and the text it prepends to replies. You will also want to examine to files '''src/twistedpeak/EchoSchema.xml''', and '''src/twistedpeak/component.xml'''. These files define the configuration schema used in '''tp.zcfg'''. Don't worry if you find this confusing! I did too. Just read the ZConfig tutorial, read, and re-read the '''tp.zcfg''' and schema files until you see their connections. If you're still stuck, post to the list. Once you've started this script, test it by running: {{{
telnet localhost 8080
}}}
and: {{{
telnet localhost 8081
}}}
== Thanks ==
Thanks to all the folks on the PEAK maillist and irc channel who helped me get up to speed on this. I hope some people find this useful.
--Joel Boehland
-- John Landahl, March 2005.
{{{
