Contents
This guide covers:
- Downloading and installing the Pesto library
- Running applications with an existing web server or a standalone WSGI server.
- Integrating applications with a templating system
Pesto requires Python 2.5, 2.6 or 2.7 (recommended).
You will need a webserver to run the examples. There are examples in this guide for integrating with a CGI webserver (eg Apache), or using a WSGI server which can either run standalone or be integrated with a front end server such as Apache.
Download and install the latest version from the Python Package Index:
% pip install pesto
For the cutting edge, fetch the development version of Pesto from its darcs repository:
% darcs get http://patch-tag.com/r/pesto/pullrepo pesto
% cd pesto
% sudo python setup.py install
Pesto provides:
- A request object that gives you easy access to information about the request, eg the URL and any submitted form data.
- A response class that makes it easy to construct and modify HTTP responses.
- A URI dispatch mechanism to help you map URIs to handler functions.
- Functions that convert your handler functions to WSGI functions, and back again.
Here’s a simple web application giving an overview of the functions provided by Pesto. Save this code in a file called guestbook.py:
#!/usr/bin/python
from cgi import escape
from datetime import datetime
from pesto import Response, DispatcherApp
app = DispatcherApp()
entries = []
@app.match('/', 'GET')
def guestbook(request):
"""
Display an index of all entries
"""
content = [
'<html><body><h1>Welcome to my Guestbook</h1>'
'<form method="POST" action="%s">'
'Name: <input type="text" name="name"/><br/>'
'Your message: <textarea name="message"></textarea><br/>'
'<input type="submit" value="Add message"/>'
'</form>' % add_entry.url()
]
content.extend([
'<h2>From %s @ %s</h2><p>%s</p><a href="%s">view details</a>' % (
escape(entry['name']),
entry['date'].strftime('%d/%m/%Y %H:%M'),
escape(entry['message']),
view_entry.url(index=ix),
) for ix, entry in reversed(list(enumerate(entries)))
])
return Response(content)
@app.match('/add-entry', 'POST')
def add_entry(request):
"""
Add an entry to the guestbook then redirect back to the main
guestbook page.
"""
entries.append({
'date': datetime.now(),
'name': request.form.get('name', ''),
'message': request.form.get('message', ''),
'ip': request.remote_addr,
'useragent': request.get_header('User-Agent', ''),
})
return Response.redirect(guestbook.url())
@app.match('/view-entry/<index:int>', 'GET')
def view_entry(request, index):
"""
View all details of an individual entry
"""
try:
entry = entries[index]
except IndexError:
return Response.not_found()
return Response(["""
<html><body>
<table>
<tr><th>Name</th><td>%s</td></tr>
<tr><th>Time</th><td>%s</td></tr>
<tr><th>IP address</th><td>%s</td></tr>
<tr><th>Browser</th><td>%s</td></tr>
<tr><th>Message</th><td>%s</td></tr>
</table>
<a href="%s">Back</a>""" % (
escape(entry['name']),
entry['date'].strftime('%d %m %Y %H:%M'),
escape(entry['ip']),
escape(entry['useragent']),
escape(entry['message']),
guestbook.url()
)
])
if __name__ == "__main__":
from wsgiref import simple_server
httpd = simple_server.make_server('', 8080, app)
httpd.serve_forever()
Run the file by typing python guestbook.py and a web server should start on port 8080.
Here’s a line-by-line breakdown of the important functionality illustrated here:
app = DispatcherApp()
DispatcherApp is a WSGI application that takes incoming requests and routes them to handler functions. In their simplest form, handler functions take a single argument (a pesto.request.Request object) and must return a pesto.response.Response object.
@app.match('/', 'GET')
def guestbook(request):
...
@app.match('/add-entry', 'POST')
def add_entry(request):
...
Using @app.match is the most convenient way to match URIs to handler functions. You need to specify both the path and at least one HTTP method (usually GET or POST).
In this case, the function guestbook will be called for all GET requests to http://<your-server>/, while add_entry will be called for POST requests to http://<your-server/add-entry.
content = [
'<html><body><h1>Welcome to my Guestbook</h1>'
...
]
...
return Response(content)
The Response object returned by a handler function specifies the response body and any HTTP headers. Response requires one argument, which must be an iterator over the content you want to return. Other arguments can be used to specify HTTP headers and other aspects of the response. If you don’t tell Pesto otherwise it will assume that the HTTP status should be 200 OK and that the content type should be text/html; charset=UTF-8.
return Response.redirect(guestbook.url())
Response.redirect is a method that returns a 302 redirect to the web browser to any given URL. Because the guestbook has been mapped to a URL via the DispatcherApp class, we can call guestbook.url() to retrieve the fully qualified URL pointing to that function.
@app.match('/view-entry/<index:int>', 'GET')
def view_entry(request, index):
"""
View all details of an individual entry
"""
Again we are using a DispatcherApp to map a URI to a function. Here we want to extract the second part of the URI and pass it as the named argument index to the function. We also tell Pesto that it should convert the value to an integer. Other pattern types are supported, like <name:unicode> or <flavour:any('vanilla', 'mango', 'grape')>. You can also define your own pattern matching rules.
try:
entry = entries[index]
except IndexError:
return Response.not_found()
The Response class contains predefined functions for most error responses. Returning Response.not_found will automatically return a 404 response to the web browser.
If you have access to a web server that is already configured to run CGI scripts and then this is a quick way to get started with Pesto. However it is more limited that other methods and can give poor performance.
Let’s start by creating a CGI script as follows:
#!/usr/bin/env python
import pesto
from pesto import Response
def handler(request):
return Response(["Welcome to Pesto!"])
if __name__ == "__main__":
app = pesto.to_wsgi(handler)
pesto.run_with_cgi(app)
Save this file in your web server’s cgi-bin directory with the filename pesto_test.cgi
Visit the script with a web browser and if all is well you should see the “Welcome to Pesto!” message.
If you don’t see this message, check that the file permissions are set correctly (ie chmod 755 pesto_test.cgi). You may also need to change the first line of your script to read either #!/usr/bin/python or #!/usr/local/bin/python, depending on your hosting provider.
If you are using Apache and mod_rewrite is enabled, then using a RewriteRule in your server configuration or from a .htaccess file is an easy way of running CGI scripts that gives you user friendly URIs and the possibility of having more than one handler function per script.
Here is how to set up a script that responds to the URIs /pages/one and /pages/two.
.htaccess
RewriteEngine On
RewriteBase /
RewriteRule ^(pages/.*) cgi-bin/pesto_test.cgi/$1
cgi-bin/pesto_test.cgi
#!/usr/bin/python
import pesto.wsgiutils
from pesto import DispatcherApp, Response
app = pesto.DispatcherApp()
@app.match('/page/one', 'GET')
def render_page(request, response):
return Response(["This is page one"])
@app.match('/page/two', 'GET')
def render_page(request):
return Response(["This is page two"])
if __name__ == "__main__":
app = pesto.wsgiutils.use_redirect_url()(app)
pesto.run_with_cgi(app)
The first time you try this, you might want to enable debugging in the dispatcher to log details of the URL processing. To do this, change the first 7 lines of your script to the following:
#!/usr/bin/python
import logging
logging.getLogger().setLevel(logging.DEBUG)
import pesto
import pesto.wsgiutils
from pesto import Response
app = pesto.DispatcherApp(debug=True)
You can run a Pesto based web application under any WSGI server. If you have Python 2.5 or above, you can use the wsgiref module from the Python standard library.
First, create a file called myhandlers.py:
from pesto import DispatcherApp
import pesto.wsgiutils
app = DispatcherApp()
@app.match('/page/one', 'GET')
def page_one(request):
return Response([
'This is page one. <a href="%s">Click here for page two</a>...' % (page_two.url(),)
])
@app.match('/page/two', 'GET')
def page_two(request):
return Response([
'...and this is page two. <a href="%s">Click here for page one</a>' % (page_one.url(),)
])
And a file called myapp.py:
import myhandlers
if __name__ == "__main__":
print "Serving application on port 8000..."
httpd = make_server('', 8080, app)
httpd.serve_forever()
Now you can start the server by running myapp.py directly:
% python myapp.py
Serving application on port 8080...
Visit http://localhost:8080/page/one in your web browser and see the application in action.
Using a standalone webserver has many advantages. But it’s better if you can proxy it through another web server such as Apache. This gives added flexibility and security and if necessary, you can set up proxy caching to get a big performance boost.
For the following to work, you need to make sure your apache installation has the proxy and rewrite modules loaded. Refer to the Apache HTTP server documentation for details of how to achieve this.
Let’s assume that you want to run a site at the URL http://example.com/. For this configuration we need Apache to listen on port 80, and the WSGI server on any other port – we’ll use port 8080 in this example.
In your httpd.conf, set up the following directives:
RewriteEngine On
RewriteRule ^/(.*)$ http://localhost:8080/$1 [L,P]
ProxyVia On
The first RewriteRule simply proxies everything to the WSGI server.
Restart apache and visit http://localhost/page/one - you should see a Bad Gateway error page. Don’t panic – this means that the proxying is working in apache, but your application is not running yet.
Modify myapp.py to read as follows:
import myhandlers
import pesto.wsgiutils
def make_app():
app = myhandlers.app
app = pesto.wsgiutils.use_x_forwarded()(app)
return app
if __name__ == "__main__":
print "Serving application on port 8000..."
httpd = make_server('', 8080, make_app())
httpd.serve_forever()
To see it in action, fire up the server:
% python myapp.py
Serving application on port 8080...
and reload http://localhost/page/one in your browser: you should now see your pesto application being server through Apache.
For a more sophisticated setup suitable for production applications, you should investigate the Paste package.
For URI generation to work correctly when proxying from an Apache/mod_ssl server, you will need to add the following to the Apache configuration in the SSL <virtualhost> section:
RequestHeader set X_FORWARDED_SSL 'ON'
Pesto handlers are at the heart of the Pesto library. The basic signature of a handler is:
def my_handler(request):
return Response(["<h1>Whoa Nelly!</h1>"])
Handlers must accept a request object and must return a pesto.response.Response object. The Response constructor takes at least one argument, content, which must be an iterator over the content you want to return.
In the example above the payload is HTML, but any data can be returned. For example, the following are also examples of valid Response objects:
# Simple textual response
Response(['ok'], content_type="text/plain")
# Iterator over database query
def format_results(cursor):
yield "<table>"
for row in iter(cursor.fetchone, None):
yield '<tr>'
for column in row:
yield '<td>%d</td>' % column
yield '</tr>'
yield "</table>"
Response(format_results(cursor))
Function decorators are simple, expressive and a natural way to add functionality to web applications using Pesto. Here are a few examples.
First up, a decorator to set caching headers on the response:
from functools import wraps
def nocache(func):
"""
Pesto middleware to send no-cache headers.
"""
@wraps(func)
def nocache(request, *args, **kwargs):
res = func(request, *args, **kwargs)
res = res.add_header("Cache-Control", "no-cache, no-store, must-revalidate")
res = res.add_header("Expires", "Mon, 26 Jul 1997 05:00:00 GMT")
return res
return nocache
This could be used as follows:
@nocache
def handler(request):
return Response(['blah'])
Giving the following output:
200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: text/html; charset=UTF-8
Expires: Mon, 26 Jul 1997 05:00:00 GMT
blah
Second: a decorator to allow handlers to return datastructures which are automatically converted into JSON notation (this example requires python 2.6, for earlier versions you will need to install the SimpleJSON module installed):
import json
def to_json(func):
"""
Wrap a Pesto handler to return a JSON-encoded string from a python
data structure.
"""
@wraps(func)
def to_json(request, *args, **kwargs):
result = func(request, *args, **kwargs)
if isinstance(result, Response):
return result
return Response(
content=[json.dumps(result)],
content_type='application/json'
)
return to_json
Finally, a decorator to turn ‘water’ into ‘wine’:
def water2wine(func):
@wraps(func)
def water2wine(*args, **kwargs):
res = func(*args, **kwargs)
return res.replace(
content=(chunk.replace('water', 'wine') for chunk in res.content)
)
return water2wine
Decorators may be chained together, for example:
from pesto import DispatcherApp
app = DispatcherApp()
@app.match('/drink-preference', 'GET')
@water2wine
@nocache
@to_json
def handler(request):
return {'preferred-drink': 'water' }
This would output the following JSON response:
200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: Mon, 26 Jul 1997 05:00:00 GMT
{"preferred-drink": "wine"}
The to_wsgi utility function adapts a Pesto handler function to form a WSGI application. This can then be run by any WSGI compliant server, eg wsgiref.simple_server:
from wsgiref.simpleserver import make_server
app = pesto.to_wsgi(my_handler)
httpd = make_server('', 8000, app)
print "Serving on port 8000..."
httpd.serve_forever()
Or in a CGI environment (eg for shared hosting) by using pesto.run_with_cgi:
app = pesto.to_wsgi(my_handler)
pesto.run_with_cgi(app)
Pesto DispatcherApp instances are WSGI applications and can be passed directly to pesto.run_with_cgi.
Pesto does not tie you to any particular templating system. As an example of how you can use a templating system in your application, here is a minimal example of code that uses the Genshi templating library:
import os
from functools import wraps
from genshi.template.loader import TemplateLoader
from pesto import Response, DispatcherApp
templateloader = TemplateLoader(["."])
def render(filepath):
"""
Render a template in genshi, passing any keyword arguments to the
template namespace.
"""
def decorator(func):
@wraps(func)
def decorated(request, *args, **kwargs):
template = templateloader.load(filepath)
data = func(request, *args, **kwargs)
return Response([
template.generate(
**data
).render(method='xhtml', encoding='utf8')
])
return decorated
return decorator
app = DispatcherApp(debug=True)
@app.match("/<name:unicode>", "GET")
@render("welcome.html")
def welcome(request, name):
return {'name': name.title()}
if __name__ == "__main__":
from wsgiref.simpleserver import make_server
print "Serving application on port 8080..."
httpd = make_server('', 8080, app)
httpd.serve_forever()
To make this work, we’ll need a template file:
>>> f = open('welcome.html', 'w')
>>> f.write('''
... <html>
... <body>
... <h1>Greetings, $name!</h1>
... </body>
... </html>
... ''')
>>> f.close()
Once running, a call to http://localhost:8080/fred should give you the following result:
<html>
<body>
<h1>Greetings, Fred!</h1>
</body>
</html>