Installation

Getting libev

To start using FAPWS you need to install libev. Libev is an event loop library that is used to develop event-based applications, like FAPWS.

Installation for Linux/BSD/*nix

$ wget http://dist.schmorp.de/libev/Attic/libev-3.9.tar.gz
$ tar xzf libev-3.9.tar.gz
$ cd libev-3.9
$ ./configure --prefix=/usr
$ make
$ sudo make install

Mac users

You have to install the latest version of MacPorts.

$ sudo port install libev

Installing FAPWS

As FAPWS is available via easy_install, we can simply run the following command (for Linux/BSD/*nix and Mac OS X)

$ sudo easy_install fapws3

Alternatively, you can grab it from github:

$ wget --no-check-certificate http://github.com/william-os4y/fapws3/tarball/master -O fapws3.tgz
$ tar xzf fapws3.tgz
$ cd william-os4y-fapws3*
$ python setup.py build
$ sudo python setup.py install

First steps

Documentation by using the obligatory "Hello World" example

#!/usr/bin/env python

import fapws._evwsgi as evwsgi
from fapws import base

def start():
	evwsgi.start('0.0.0.0', '8080') 
	evwsgi.set_base_module(base)

	def hello(environ, start_response):
		start_response('200 OK', [('Content-Type','text/html')])
		return ['hello world!!']

	evwsgi.wsgi_cb(('/hello', hello))

	evwsgi.set_debug(0)	   
	evwsgi.run()
 
if __name__ == '__main__':
	start()

Explanation of the example above

• evwsgi.start('0.0.0.0', '8080') - Here you can define the interface and port, FAPWS should listen on.
• evwsgi.set_base_module(base) - This says to Fapws with which 'base' elements it will work. Except very special cases (advanced users), you should not change this.
• def hello(environ, start_response) - Create a simple callback function that is triggered when a request hits the server.
• start_response('200 OK', [('Content-Type','text/html')]) - Now we're defining the HTTP headers, that are send back to the client.
• return ['hello world!!'] - This is the payload/body FAPWS will send to the client. Remember that you always have to return a list of strings, a file object or yielded strings.
• evwsgi.wsgi_cb(('/hello', hello)) - Here we're going to attach the callback function to our URI route /hello.
• evwsgi.debug(0) - Set it to 1 if you want to debug Fapws. This will not debug your python wsgi application.
• evwsgi.run() - Last but not least we're starting FAPWS to serve forever.

Some additional considerations about your URIs

• Think carefully about your different URIs and put the most used in the begining. For example, put the static files at the top of your URI's definitions, this will avoid Fapws to loop around every defined URIs before finding the correct one.
• Avoid to declare the a generic URI before a specific one. For example, if you plan to have URIs like: /names and /names/bill, don't to this:

  evwsgi.wsgi_cb(('/names', allnames))
  evwsgi.wsgi_cb(('/names/', specificname))
  

  With this rules, you will get:

  Requested URL	WSGI call back	WSGI parameters
  /names	allnames	'SCRIPT_NAME':'/names', 'PATH_INFO':''
  /names/bill	allnames	'SCRIPT_NAME':'/names', 'PATH_INFO':'/bill'

  Thus Fapws will never trigger the 'specificname' method. Instead you must do:

  evwsgi.wsgi_cb(('/names/', specificname)) 
  evwsgi.wsgi_cb(('/names', allnames))      
  

  With this second set of rules, you will get:

  Requested URL	WSGI call back	WSGI parameters
  /names	allnames	'SCRIPT_NAME':'/names', 'PATH_INFO':''
  /names/bill	specifiname	'SCRIPT_NAME':'/names/', 'PATH_INFO':'bill'

Advanced features

Serve static files

from fapws.contrib import views

staticfile = views.Staticfile('static', maxage=2629000)
evwsgi.wsgi_cb(('/static', staticfile))

Every request that goes to /static, e.g. /static/img/logo.png is handled by the staticfile function. This means, that if you have the image logo.png on your filesystem in the following directory static/img it is getting directly delivered from there.

Enable Gzip compression and logging

from fapws.contrib import zip, log

@log.Log()
@zip.Gzip()
def staticlong(environ, start_response):
	start_response('200 OK', [('Content-Type','text/html')])
	return ["hello world!!"]

Simply use the two decorators @log.Log() and @zip.Gzip() to enable request logging and on the fly Gzip compression.

Server CGI scripts

from fapws.contrib import cgiapp

    testphp=cgiapp.CGIApplication("/tmp/test.php")
    evwsgi.wsgi_cb(("/testphp",testphp))

with this simple config you will be able to server CGI applications. In this example we serve a simple cgi PHP script.