Quick Start [WHIFF documentation]

Home
Info
- Demos
- Tutorials
- Quick start
- Syntax quickref
- MVC/wiki
- AJAX/calculator
- authentication
- Chat
- Charts
Concepts
Reference

WHIFF DOCUMENTION

Quick Start

How to install and start working with WHIFF (for the impatient).

Contents:

Download and unpack the tarball
...Or clone the mercurial repository
Install WHIFF
Create a whiff "server root" directory
Add some files/applications to the directory
Run the directory in test mode and try it out
Install the directory as a CGI script and try it out
Where to next?

This "quick start" explains how to install the whiff package and how to start building WHIFF applications. The explanation proceeds by running console commands and creating files using text editors. The presentation assumes you have Python 2.5 or better installed on your computer. ‡

×
For the sake of simplicity the discussion uses Unix-style command lines. Readers who have some knowledge of Unix, Python, and basic web technologies will find this discussion easier to understand than will those who do not.

For reference, the directory containing the files described in this quick start is provided in the WHIFF distribution at INSTALL/doc/whiffTest.

If you would like to experiment with WHIFF without installing it please read the Test Drive Tutorial.

Download and unpack the tarball

Before you use WHIFF you must get it and install it. One way to get it is to download a release tarball package. The canonical location for all information about WHIFF including download links is the whiff.sourceforge.net source forge project page. Follow the instructions at the project page to download the latest *.tar.gz tarball.

After you download the tarball, unpack it like this (or similar)

~$ gunzip ~/downloads/whiff.tar.gz
~$ tar -xvf whiff.tar
... creates directory ~/whiff

...Or clone the mercurial repository

Another way to get the very latest version of WHIFF is to pull the mercurial repository. Mercurial is a version control system available from selenic.com.

~$ hg clone https://whiff.googlecode.com/hg/ whiff

‡

×
The command above lists the location of the archive at this writing -- if the clone doesn't work the archive may have moved: check the project page for the new archive location.

This hg clone will get a development version of the package which may include experimental enhancements.

Install WHIFF

After you download or clone WHIFF you must install the package to make the WHIFF Python modules and scripts available for use.

Use the setup.py setup script to install the whiff package (you may need superuser priviledges to execute this command).

~$ cd whiff
~/whiff$ python setup.py install

This script will install the whiff package as well as related scripts in the standard locations for your Python location.

Create a whiff "server root" directory

Now that whiff is installed, try it out by configuring a directory that whiff can use to serve applications.

Make the directory whiffTest for your whiff application and cd into it so we can create some files in the new directory.

...$ cd ~
~$ mkdir whiffTest
~$ cd whiffTest

Make an __init__.py initializer file which identifies this directory as a directory for serving wsgi applications and also publishes all templates in the directory and files with all recognized mime extensions (for example *.jpg, *.html etcetera).

# contents of whiffTest/__init__.py
from whiff import resolver

# deliver wsgi application found in this directory!
__wsgi_directory__ = True

# publish templates and recognized mime extensions found in this directory!
resolver.publish_templates(__path__[0], globals(), mime_extensions=True, 
      directory_middleware=True)

Now that the __init__.py file tells WHIFF what to do with this directory we can put some content here for WHIFF to serve up.

Add some files/applications to the directory

Lets add a static readme.txt file in this directory so we can remember what the directory is for.

This is the content of readme.txt in the whiffTest directory: 
    just trying out WHIFF!

When WHIFF serves the whiffTest directory the server will automatically recognize the readme.txt file and serve the contents of the file to browsers as a plain text.

Create a tiny application: `theTime.py`

Now lets add a tiny WSGI application to the directory.

Create a Python file theTime.py which sends a human readable time string for the current time from the server as HTML to a client browser.

# contents of whiffTest/theTime.py
"""
Deliver the current time string as HTML.
"""

import time

def timeApplication(env, start_response):
    result = time.ctime()
    start_response("200 OK", [('Content-Type', 'text/html')])
    return [result]

# identify timeApplication as the wsgi application for this module
__wsgi__ = timeApplication

### testing stuff...

def test():
    from whiff.middleware import misc
    env = {}
    out = timeApplication(env, misc.ignore)
    txt = "".join(list(out))
    print repr(txt)

if __name__=="__main__":
    test()

This is a standard trivial WSGI application. The very top of the theTime.py Python module source file has a "doc string" saying what the module is for. The next part of the file defines the logic of the application and the last part provides a simple-minded self test (which just makes sure the module runs and produces some output).

The assignment

__wsgi__ = timeApplication

has special meaning for the WHIFF interpretation of the module -- it says that the function timeApplication should handle all web requests delegated to the theTime.py module.

Try `theTime.py` on the command line

Make sure the theTime module runs by executing the test interpretation.

~/whiffTest$ python theTime.py
'Fri Mar 27 16:15:32 2009'

If there were any errors in the Python code we could try to fix them at this point. However, since there are no problems we proceed...

Create a simple configuration template `hello.whiff`

Now lets add a hello application which uses theTime as an application fragment. The hello application will be defined using a WHIFF configuration template instead of using a Python module.

Add a simple whiff configuration template hello.whiff which displays some information about a web request and shows the time.

{{comment:
   This is the content of whiffTest/hello.whiff.

   The following directive tells the server to deliver 
   the interpretation of this file as text/html. 
/}}
{{env whiff.content_type: "text/html"/}}

<html>
<head>
<title>Hello there!</title>
</head>
<body>
This is your REMOTE_ADDRESS: {{get-env REMOTE_ADDR}}(UNKNOWN){{/get-env}}
<br>
The time is now: {{include "theTime"/}}
</body>
</html>

This template uses several WHIFF template directives:

{{comment.. /}} is a whiff directive containing configuration file comments which are ignored by the configuration interpreter and stripped from the configuration output.
{{env whiff.content_type: "text/html"/}} is a configuration directive which modifies the application environment, telling the WHIFF interpreter to serve the hello application as HTML.
{{get-env REMOTE_ADDR}}(UNKNOWN){{/get-env}} is a configuration directive which evaluates to the value of the REMOTE_ADDR from the web application environment. ‡
×
The WSGI specification specifies that the REMOTE_ADDR entry in the environment will provide the numeric internet protocol address for the web client program.
If the REMOTE_ADDR is absent from the environment the directive will evaluate to (UNKNOWN).
{{include TheTime/}} is a configuration directive which evaluates to the result of the theTime application defined by Python code above.

Note that the relative locator for the application module theTime.py is theTime with the .py extension stripped off.

Make sure `hello.whiff` parses

Make sure the hello.whiff template contains no syntax errors using the whiff_parse.py script that was installed when you installed the package in the set up.

~/whiffTest$ whiff_parse.py hello.whiff
parse succeeded

If the whiff_parse.py script found a syntax error in the template hello.whiff it would have been reported in the output.

Execute `hello.whiff` from the command line

Since hello.whiff is a simple application which requires no special environment entries we can run the template in "stand-alone" mode from the command line using the whiff_expand.py script installed with the package. Because the hello template resides in the whiffTest directory the testing script must run from the parent of whiffTest. Also note that the locator for hello.whiff is hello with the .whiff extension stripped off.

~/whiffTest$ cd ..
~$ whiff_expand.py whiffTest hello

The output of the script produces the HTML text

<html>
<head>
<title>Hello there!</title>
</head>
<body>
This is your REMOTE_ADDRESS: 127.0.0.1
<br>
The time is now: Fri Mar 27 16:50:50 2009
</body>
</html>

If the configuration hello.whiff as interpreted in the directory whiffTest caused run time errors ‡

×
For example by referring to a file which doesn't exist.

they would have been reported as error output from the whiff_expand.py script.

Now we are ready to take a look at the contents of the whiffTest directory in a browser.

Run the directory in test mode and try it out

It is a good idea to test a WHIFF directory using a simple stand alone web server before installing the directory in a general purpose web server. WHIFF provides a script for starting a simple server for a WHIFF directory which must be run from the parent of the WHIFF directory. In the case of the directory ~/whiffTest we start the script from the parent directory ~/ as follows:

~$ whiff_serve.py  whiffTest/
serving whiff root <module 'whiffTest' from './whiffTest/__init__.pyc'>
as http on host localhost port 8888
_

This server script will repeatedly wait for web requests at port 8888 of the localhost until the program is terminated in the terminal window using a [CONTROL]-C. Until the server terminates the terminal window will print brief log entries describing the pages served.

View the directory listing for `whiffTest`

Now point a browser at the URL http://localhost:8888/ to get a web directory listing for whiffTest whiffTest directory listing

The directory listing is available because the whiffTest initialization file __init__.py included the declaration

# publish templates and recognized mime extensions found in this directory!
resolver.publish_templates(__path__[0], globals(), mime_extensions=True,
      directory_middleware=True)

and the parameter directory_middleware=True enabled the default directory listing for the directory. ‡

×
In a "real" deployed application it may not be a good idea to allow directory listings, in which case we can use directory_middleware=False instead.

The __init__ files are listed in the directory but the WHIFF server will refuse to interpret these Python code files because they do not contain a __wsgi__ entry indicating the application to use to handle web requests. The server will interpret and serve content for the other files.

View the time application

If we now select theTime.py from the directory listing we see the result of evaluating the theTime application in the web browser. theTime.py application evaluation content

theTime.py application evaluation content

View the `hello` application

If we now use the "back button" to return to the directory listing in the browser and then select the hello.whiff link we see the result of evaluating the hello configuration template in the browser window. hello.whiff configuration template evaluation content

hello.whiff configuration template evaluation content

Furthermore, the readme.txt link from the directory listing will show the contents of the readme file as plain text.

Terminate the testing server

The testing server will continue to service requests until it is forcefully terminated at the command line using a CONTROL-C or similar methods. On Windows you may need to do a CONTROL-C and then send another request to the server (by reloading the browser window) before the server will terminate.

Install the directory as a CGI script and try it out

Now that we have determined that our directory works in test mode we are ready to deploy it to a fully functional web server. A WHIFF application directory can be deployed under any web server software which supports the WSGI standard. In this case we deploy whiffTest under an Apache server installation as a simple CGI script.

Create the CGI script using the standard WSGI handler

We create the following Python CGI script in the standard location for Apache CGI scripts: /usr/local/apache2/cgi-bin/whiffTest.cgi

#!/python_install_location_path/python

import sys
import wsgiref.handlers
import whiff.resolver

sys.path.append("/whiffTest_parent_directory_path/")
import whiffTest

# create a WSGI application to serve the whiffTest directory
application = whiff.resolver.moduleRootApplication("/cgi-bin/whiffTest.cgi", 
                                          whiffTest)

# serve a CGI request using the directory
wsgiref.handlers.CGIHandler().run(application)

The first line of this script tells the Apache server where to find the Python interpreter to run the script, and the remainder of the script uses the standard method for serving a WSGI application using the web server's CGI interface.

The application is defined by the assignment

application = whiff.resolver.moduleRootApplication("/cgi-bin/whiffTest.cgi", 
                                           whiffTest)

Which sets up the whiffTest Python module as a web directory to respond to requests that start with the URL /cgi-bin/whiffTest.cgi.

As with all CGI scripts, the script source file must be marked executable before it will run.

/usr/local/apache2/cgi-bin$ chmod a+x whiffTest.cgi

View the directory under Apache

To view the directory contents as served by Apache we navigate a browser to the appropriate URL for the server location, in my case http://aaron.oirt.rutgers.edu/cgi-bin/whiffTest.cgi/ (note the final slash -- it is required).

The initial page show the default directory listing as before

directory listing served by Apache via the CGI interface

The links from the directory listing page work as described earlier for the testing server.

Where to next?

Now that you have tried out WHIFF and want to understand it more deeply you probably should read the Concepts document, or you may want to look at more example applications with discussions as provided in the Tutorial.

<previous<
Whiff Documentation Index

^up^
Whiff Documentation Index

>next>
Concepts

0 comments.

Care to comment?

name: (required)
- email (not published):
comment: (required)

<< security number? >>