Wiki Example
============
:author: Ian Bicking
.. contents::
Introduction
------------
This is an example of how to write a WSGI application using WebOb.
WebOb isn't itself intended to write applications -- it is not a web
framework on its own -- but it is *possible* to write applications
using just WebOb.
The `file serving example `_ is a better example of
advanced HTTP usage. The `comment middleware example
`_ is a better example of using middleware.
This example provides some completeness by showing an
application-focused end point.
This example implements a very simple wiki.
Code
----
The finished code for this is available in
`docs/wiki-example-code/example.py
`_
-- you can run that file as a script to try it out.
Creating an Application
-----------------------
A common pattern for creating small WSGI applications is to have a
class which is instantiated with the configuration. For our
application we'll be storing the pages under a directory.
.. code-block:: python
class WikiApp(object):
def __init__(self, storage_dir):
self.storage_dir = os.path.abspath(os.path.normpath(storage_dir))
WSGI applications are callables like ``wsgi_app(environ,
start_response)``. *Instances* of `WikiApp` are WSGI applications, so
we'll implement a ``__call__`` method:
.. code-block:: python
class WikiApp(object):
...
def __call__(self, environ, start_response):
# what we'll fill in
To make the script runnable we'll create a simple command-line
interface:
.. code-block:: python
if __name__ == '__main__':
import optparse
parser = optparse.OptionParser(
usage='%prog --port=PORT'
)
parser.add_option(
'-p', '--port',
default='8080',
dest='port',
type='int',
help='Port to serve on (default 8080)')
parser.add_option(
'--wiki-data',
default='./wiki',
dest='wiki_data',
help='Place to put wiki data into (default ./wiki/)')
options, args = parser.parse_args()
print 'Writing wiki pages to %s' % options.wiki_data
app = WikiApp(options.wiki_data)
from wsgiref.simple_server import make_server
httpd = make_server('localhost', options.port, app)
print 'Serving on http://localhost:%s' % options.port
try:
httpd.serve_forever()
except KeyboardInterrupt:
print '^C'
There's not much to talk about in this code block. The application is
instantiated and served with the built-in module
`wsgiref.simple_server
`_.
The WSGI Application
--------------------
Of course all the interesting stuff is in that ``__call__`` method.
WebOb lets you ignore some of the details of WSGI, like what
``start_response`` really is. ``environ`` is a CGI-like dictionary,
but ``webob.Request`` gives an object interface to it.
``webob.Response`` represents a response, and is itself a WSGI
application. Here's kind of the hello world of WSGI applications
using these objects:
.. code-block:: python
from webob import Request, Response
class WikiApp(object):
...
def __call__(self, environ, start_response):
req = Request(environ)
resp = Response(
'Hello %s!' % req.params.get('name', 'World'))
return resp(environ, start_response)
``req.params.get('name', 'World')`` gets any query string parameter
(like ``?name=Bob``), or if it's a POST form request it will look for
a form parameter ``name``. We instantiate the response with the body
of the response. You could also give keyword arguments like
``content_type='text/plain'`` (``text/html`` is the default content
type and ``200 OK`` is the default status).
For the wiki application we'll support a couple different kinds of
screens, and we'll make our ``__call__`` method dispatch to different
methods depending on the request. We'll support an ``action``
parameter like ``?action=edit``, and also dispatch on the method (GET,
POST, etc, in ``req.method``). We'll pass in the request and expect a
response object back.
Also, WebOb has a series of exceptions in ``webob.exc``, like
``webob.exc.HTTPNotFound``, ``webob.exc.HTTPTemporaryRedirect``, etc.
We'll also let the method raise one of these exceptions and turn it
into a response.
One last thing we'll do in our ``__call__`` method is create our
``Page`` object, which represents a wiki page.
All this together makes:
.. code-block:: python
from webob import Request, Response
from webob import exc
class WikiApp(object):
...
def __call__(self, environ, start_response):
req = Request(environ)
action = req.params.get('action', 'view')
# Here's where we get the Page domain object:
page = self.get_page(req.path_info)
try:
try:
# The method name is action_{action_param}_{request_method}:
meth = getattr(self, 'action_%s_%s' % (action, req.method))
except AttributeError:
# If the method wasn't found there must be
# something wrong with the request:
raise exc.HTTPBadRequest('No such action %r' % action).exception
resp = meth(req, page)
except exc.HTTPException, e:
# The exception object itself is a WSGI application/response:
resp = e
return resp(environ, start_response)
The Domain Object
-----------------
The ``Page`` domain object isn't really related to the web, but it is
important to implementing this. Each ``Page`` is just a file on the
filesystem. Our ``get_page`` method figures out the filename given
the path (the path is in ``req.path_info``, which is all the path
after the base path). The ``Page`` class handles getting and setting
the title and content.
Here's the method to figure out the filename:
.. code-block:: python
import os
class WikiApp(object):
...
def get_page(self, path):
path = path.lstrip('/')
if not path:
# The path was '/', the home page
path = 'index'
path = os.path.join(self.storage_dir)
path = os.path.normpath(path)
if path.endswith('/'):
path += 'index'
if not path.startswith(self.storage_dir):
raise exc.HTTPBadRequest("Bad path").exception
path += '.html'
return Page(path)
Mostly this is just the kind of careful path construction you have to
do when mapping a URL to a filename. While the server *may* normalize
the path (so that a path like ``/../../`` can't be requested), you can
never really be sure. By using ``os.path.normpath`` we eliminate
these, and then we make absolutely sure that the resulting path is
under our ``self.storage_dir`` with ``if not
path.startswith(self.storage_dir): raise exc.HTTPBadRequest("Bad
path").exception``.
.. note::
``exc.HTTPBadRequest("Bad path")`` is a ``webob.Response`` object.
This is a new-style class, so you can't raise it in Python 2.4 or
under (only old-style classes work). The attribute ``.exception``
can actually be raised. The exception object is *also* a WSGI
application, though it doesn't have attributes like
``.content_type``, etc.
Here's the actual domain object:
.. code-block:: python
class Page(object):
def __init__(self, filename):
self.filename = filename
@property
def exists(self):
return os.path.exists(self.filename)
@property
def title(self):
if not self.exists:
# we need to guess the title
basename = os.path.splitext(os.path.basename(self.filename))[0]
basename = re.sub(r'[_-]', ' ', basename)
return basename.capitalize()
content = self.full_content
match = re.search(r'(.*?)', content, re.I|re.S)
return match.group(1)
@property
def full_content(self):
f = open(self.filename, 'rb')
try:
return f.read()
finally:
f.close()
@property
def content(self):
if not self.exists:
return ''
content = self.full_content
match = re.search(r']*>(.*?) ', content, re.I|re.S)
return match.group(1)
@property
def mtime(self):
if not self.exists:
return None
else:
return os.stat(self.filename).st_mtime
def set(self, title, content):
dir = os.path.dirname(self.filename)
if not os.path.exists(dir):
os.makedirs(dir)
new_content = """