On Wed, Jan 07, 2004 at 02:03:16PM -0800, Dave Kuhlman wrote:

[snip]
> It would be useful to add a bit of additional documentation in
> doc/web-server.html including a sample start-up script. The qxdemo
> already has a sample script (qxdemo-0.1/scripts/links-server.py).
> If the documentation included "three steps for running Quixote with
> Medusa", wouldn't that satisfy the requirement for "A Medusa-like
> out-of-the-box server included with Quixote".  After all, Medusa is
> very Medusa-like.
>
> Even if one of the "three steps" were to down-load Medusa
> separately and unroll it, that does not seem to be much of a burden
> to me, especially if Medusa was available at the Quixote site.
>
> I was able to set up and use Quixote with Medusa.  That's about as
> good a test of ease-of-use as you can get.

Not to try to talk anyone out of using Pierre Quentel's Python
Cookbook server, if that seems best, however, in an attempt to
explore an alternative ...

I took up my own challenge to produce documentation that specifies
"three steps for running Quixote with Medusa".  So far I've written
the following.  We could skip the first step, if Medusa is bundled
with and installed by Quixote.

=======================================================================

Using the Medusa Web Server
===========================

Medusa is a 'server platform' -- it provides a framework for
implementing asynchronous socket-based servers (TCP/IP and on
Unix, Unix domain, sockets).

For our purposes, Medusa provides an HTTP 1.1 Web server.

This section explains how to use Medusa in support of Quixote.


Install Medusa
--------------

Down-load Medusa from http://www.amk.ca/python/code/medusa.html.

Unroll it with something like::

    tar xvzf medusa-0.5.4.tar.gz

Install Medusa with the following::

    cd medusa-0.5.4
    python setup.py install


Create a driver script
----------------------

Here is a sample, taken from ``qxdemo``, the Quixote demo
application::

    #!/usr/bin/env python

    try:
        from medusa import http_server, xmlrpc_handler
    except ImportError:
        print '\n' + '='*50
        print 'medusa/ package not found; fetch it from '
        print '  http://www.amk.ca/files/python/'
        print 'and install it.'
        print '='*50
        raise

    import asyncore
    from quixote.publish import Publisher
    from quixote.server import medusa_http

    from quixote import enable_ptl
    enable_ptl()

    # Server that exposes the links demo program on port 8080
    PORT = 8080    # [1]

    print 'Now serving the qxdemo.links demo on port %i' % PORT
    server = http_server.http_server('', PORT)
    publisher = Publisher('qxdemo.ui.links')    # [2]
    publisher.config.debug_log = "/tmp/debug"    # [3]
    publisher.config.error_log = "/tmp/error"
    publisher.setup_logs()
    dh = medusa_http.QuixoteHandler(publisher, 'qxdemo/links server', server)
# [4]
    server.install_handler(dh)
    asyncore.loop()

Notes and customization:

1. Change the port that you want to receive requests on.

2. Change the Python path to your application.  If the root of
   your application is in a ``__init__.py`` file, specify the path
   to the directory (package) that contains it, for example::

       publisher = Publisher('qxdemo.ui')

   If the root of your application is in a plain Python source
   file such as ``links.py``, specify the path to that
   module, for example::

       publisher = Publisher('qxdemo.ui.links')

3. You can also specify log files (and a lot more) in a Quixote
   configuration file.  In order to do so:

       1. Copy the default configuration script ``config.py`` from
          the Quixote distribution to a location of your choice.

       2. Replace the lines containing ``publisher.config. ...``
          with the following line containing the path to your
          configuration script::

              publisher.read_config('myconfig.py')

4. Change the server name string.  In our sample script above, the
   value of the ``SERVER_SOFTWARE`` environment variable will be
   "qxdemo/links server".


Start Your Server
-----------------

In order to start your server, run your driver script.  For
example, if the name of your driver script is `server-medusa.py`,
the following will start your server::

    python server-medusa.py

=======================================================================

Dave

--
Dave Kuhlman
dkuhlman@rexx.com
http://www.rexx.com/~dkuhlman