.. testsetup:: *
from pesto.response import Response
from pesto import to_wsgi
from pesto.testing import TestApp
Getting started with Pesto
##########################
.. contents:: Contents
Introduction
=============
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
Installation
=============
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.
Installing Pesto
```````````````````
Download and install the latest version from the Python Package Index::
% pip install pesto
Installing the development version
````````````````````````````````````
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
Programming with Pesto: basic concepts
======================================
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.
Sample application
```````````````````
Here's a simple web application giving an overview of the functions provided
by Pesto. Save this code in a file called ``guestbook.py``:
.. testcode::
#!/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 = [
'
Welcome to my Guestbook
'
'' % add_entry.url()
]
content.extend([
'From %s @ %s
%s
view details' % (
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/', '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(["""
Name | %s |
Time | %s |
IP address | %s |
Browser | %s |
Message | %s |
Back""" % (
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()
.. doctest::
:hide:
>>> app = TestApp(app)
>>> 'Welcome to my Guestbook
' in app.get('/').body
True
>>> print app.post('/add-entry', data={'name': 'Jim', 'message': "hello, I'm Jim & I like guestbooks"}).text()
302 Found
...
Location: http://localhost/
...
>>> "hello, I'm Jim & I like guestbooks" in app.get('/').body
True
>>> print app.get('/view-entry/2').text()
404 Not Found
...
>>> print app.get('/view-entry/0').text()
200 OK
...
Name | Jim |
Time | ... |
IP address | 127.0.0.1 |
Browser | |
Message | hello, I'm Jim & I like guestbooks |
...
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:///``, while ``add_entry`` will be called for POST requests
to ``http://Welcome to my Guestbook
'
...
]
...
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/', '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 ```` or
````. 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.
Using with CGI
==============================
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:
.. testcode::
#!/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.
CGI with mod_rewrite
```````````````````````````
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**
.. testcode::
#!/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)
Using a standalone WSGI server
===============================================================
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``:
.. testcode::
from pesto import DispatcherApp
import pesto.wsgiutils
app = DispatcherApp()
@app.match('/page/one', 'GET')
def page_one(request):
return Response([
'This is page one. Click here for page two...' % (page_two.url(),)
])
@app.match('/page/two', 'GET')
def page_two(request):
return Response([
'...and this is page two. Click here for page one' % (page_one.url(),)
])
.. doctest::
:hide:
>>> TestApp(app).get('/page/one').body
'This is page one. Click here for page two...'
>>> TestApp(app).get('/page/two').body
'...and this is page two. Click here for page one'
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.
Virtualhosting and Apache
==========================
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.
HTTPS
```````
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 `` section::
RequestHeader set X_FORWARDED_SSL 'ON'
Pesto handlers
```````````````````
Pesto handlers are at the heart of the Pesto library. The basic signature of a handler is:
.. testcode::
def my_handler(request):
return Response(["Whoa Nelly!
"])
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:
.. testcode::
:hide:
cursor = None
.. testcode::
# Simple textual response
Response(['ok'], content_type="text/plain")
# Iterator over database query
def format_results(cursor):
yield ""
for row in iter(cursor.fetchone, None):
yield ''
for column in row:
yield '%d | ' % column
yield '
'
yield "
"
Response(format_results(cursor))
Function decorators
```````````````````
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:
.. testcode::
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:
.. testcode::
@nocache
def handler(request):
return Response(['blah'])
.. testcode::
:hide:
from pesto.testing import TestApp
print TestApp(to_wsgi(handler)).get('/').text()
Giving the following output:
.. testoutput::
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):
.. testcode::
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':
.. testcode::
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:
.. testcode::
from pesto import DispatcherApp
app = DispatcherApp()
@app.match('/drink-preference', 'GET')
@water2wine
@nocache
@to_json
def handler(request):
return {'preferred-drink': 'water' }
.. testcode::
:hide:
from pesto.testing import TestApp
print TestApp(app).get('/drink-preference').text()
This would output the following JSON response:
.. testoutput::
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"}
Running Pesto applications
`````````````````````````````````````
Pesto and WSGI
'''''''''''''''
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``.
Using Pesto with a templating system
=====================================
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:
.. testcode::
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("/", "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:
.. doctest::
>>> f = open('welcome.html', 'w')
>>> f.write('''
...
...
... Greetings, $name!
...
...
... ''')
>>> f.close()
.. testcode::
:hide:
print TestApp(app).get('/fred').body
Once running, a call to ``http://localhost:8080/fred`` should give you the following result:
.. testoutput::
Greetings, Fred!