Additional topics

Check functions

When using the query, post, and resource decorators, you can define a check function. Before calling the decorated function, the check function is called. If the check function returns a response, the check function’s response is used rather than calling the decorated function. A common use of check functions is for authorization:

import bobo, webob

data = {'x': 'some text'}

def authenticated(inst, request, func):
    if not request.remote_user:
        return webob.Response(status=401)

@bobo.post('/:name', check=authenticated)
def update(name, body):
    data[name] = body
    return 'Updated'

In this example, we use a very simple authorization model. We can update data if the user is authenticated. Check functions take 3 positional arguments:

• an instance
• a request
• the decorated function (or callable)

If a resource is a method, the first argument passed to the check function will be the instance the method is applied to. Otherwise, it will be None.

Decorated objects can be used directly

Functions or callables decorated by the query, post, resource and subroute decorators can be called as if they were undecorated. For example, with:

@bobo.query('/:name', check=authenticated)
def get(name):
    return data[name]

We can call the get function directly:

>>> get('x')
'some text'

Similarly, classes decorated with the subroute decorator can be used normally. The subroute decorator simply adds a bobo_response class method that allows the class to be used as a resource.

Configured routes

For simplicity, you normally specify routes in your application code. For example, in:

@bobo.query('/greeters/:myname')
def hello(name="world", myname='Bobo'):
    return "Hello %s! My name is %s." % (name, myname)

You specify 2 things:

1. Which URLs should be handled by the hello function.
2. How to call the function.

In most cases, being able to specify this information one place is convenient.

Sometimes, however, you may want to separate routes from your implementation to:

• Manage the routes in one place,
• Omit some routes defined in the implementation,
• Change the routes or search order from what’s given in the implementation.

Bobo provides a way to explicitly configure the routes as part of configuration. When you specify resources, you can control the order resources are searched and override the routes used.

The bobo_response takes a number of resources separated by newlines. Resources take one of 4 forms:

modulename

Use all of the resources found in the module.

modulename:expression

Use the given :term:resource. The resource is specified using a module name and an expression (typically just a global name) that’s executed in the module’s global scope.

route -> modulename:expression

Use the given object with the given route. The object is specified using a module name and an expression (typically just a global name) that’s executed in the module’s global scope.

The object must have a bobo_route method, as objects created using one of the query, post, resource or subroute decorators do, or the object must be a class with a constructor that takes a request and route data and returns a resource.

route +> modulename:expression

Use a resource, but add the given route as a prefix of the resources route. The resource is given by a module name and expression.

The given route may not have placeholders.

Resources are separated by newlines. The string ->, or +> at the end of a line acts as a line continuation character.

To show how this works, we’ll look at an example. We’ll create a 2 modules with some resources in them. First, people:

import bobo

@bobo.subroute('/employee/:id', scan=True)
class Employee:
    def __init__(self, request, id):
        self.id = id

    @bobo.query('/')
    def hi(self):
        return "Hi, I'm employee %s" % self.id

@bobo.query('/:name')
def hi(name):
    return "Hi, I'm %s" % name

Then docs:

import bobo

documents = {
    'bobs': {
    'hi.html': "Hi. I'm Bob.",
    'hobbies': {
      'cooking.html': "I like to cook.",
      'sports.html': "I like to ski.",
      },
    },
}

@bobo.subroute('/docs', scan=True)
class Folder:

    def __init__(self, request, data=None):
        if data is None:
            data = documents
        self.data = data

    @bobo.query('')
    def base(self, bobo_request):
        return bobo.redirect(bobo_request.url+'/')

    @bobo.query('/')
    def index(self):
        return '\n'.join('<a href="%s">%s<a><br>' % (k, k)
                         for k in self.data)

    @bobo.subroute('/:item_id')
    def subitem(self, request, item_id):
        item = self.data[item_id]
        if isinstance(item, dict):
           return Folder(request, item)
        else:
           return Document(item)

@bobo.scan_class
class Document:

    def __init__(self, text):
        self.text = text

    @bobo.query('')
    def get(self):
        return self.text

We use the bobo_resources option to control the URLs we access these with:

[app:main]
use = egg:bobo
bobo_resources =
    # Same routes
    people:Employee # 1
    docs            # 2

    # new routes
    /long/winded/path/:name/lets/get/on/with/it -> # 3
       people:hi                                   # 3 also
    /us/:id -> people:Employee  # 4

    # prefixes
    /folks +> people # 5
    /ho +> people:hi # 6

This example shows a number of things:

• We can use blank lines and comments. Route configurations can get involved, so comments are useful. In the example, comments are used to assign numbers to the individual routes so we can refer to them.

• We have several form of resource:

  1. Use an existing resource with its original route.

     If we use a URL like:

     http://localhost:8080/employee/1/

     We’ll get output:

     Hi, I'm employee 1

  2. Use the resources from a module with their original routes.

     If we use a URL like:

     http://localhost:8080/docs/bobs/hi.html

     We’ll get output:

     Hi. I'm Bob.

  3. Define a new route for an existing resource.

     If we use a URL like:

     http://localhost:8080/long/winded/path/bobo/lets/get/on/with/it

     We’ll get output:

     Hi, I'm bobo

  4. Define a new route for an existing subroute.

     If we use a URL like:

     http://localhost:8080/us/1/

     We’ll get output:

     Hi, I'm employee 1

  5. Use all of the routes from a module with a prefix added.

     If we use a URL like:

     http://localhost:8080/folks/employee/1/

     We’ll get output:

     Hi, I'm employee 1

  6. Use an existing route adding a prefix.

     If we use a URL like:

     http://localhost:8080/ho/silly

     We’ll get output:

     Hi, I'm silly

Configuring routes in python

To configure routes in Python, you can use the bobo.resources function:

import bobo

myroutes = bobo.resources((
    # Same routes
    'people:Employee', # 1
    'docs',            # 2

    # new routes
    bobo.reroute(
      '/long/winded/path/:name/lets/get/on/with/it', # 3
      'people:hi'),                                  # 3 also
    bobo.reroute('/us/:id', 'people:Employee'),  # 4

    # prefixes
    bobo.preroute('/folks', 'people'), # 5
    bobo.preroute('/ho', 'people:hi'), # 6
))

The resources function takes an iterable of resources, where the resources can be resource objects, or strings naming resource objects or modules.

The reroute function takes a route and an existing resource and returns a new resource with the given route. The resource must have a bobo_route method, as resources created using one of the query, post, resource or subroute decorators do, or the resource must be a class with a constructor that takes a request and route data and returns a resource.

The preroute function takes a route and a resource and returns a new resource that uses the given route as a subroute to get to the resource.

The example above is almost equivalent to the earlier example. If the module containing the code above is given to the bobo_resources option, then the resources defined by the call will be used. It is slightly different from the earlier example, because if the module defines any other resources, they’ll be used as well.

Resource modules

Rather than defining a resource in a module, we can make a module a resource by defining a bobo_response module attribute:

import bobo, docs, people

bobo_response = bobo.resources((
    # Same routes
    people.Employee, # 1
    docs,            # 2

    # new routes
    bobo.reroute(
      '/long/winded/path/:name/lets/get/on/with/it', # 3
      people.hi),                                    # 3 also
    bobo.reroute('/us/:id', people.Employee),  # 4

    # prefixes
    bobo.preroute('/folks', people), # 5
    bobo.preroute('/ho', people.hi), # 6

)).bobo_response

Here, rather than adding a new resource to the module, we’ve copied the bobo_response method from a new resource to the module, making the module a resource. When bobo scans a module, it first checks whether the module has a bobo_response attribute. If it does, then bobo uses the module as a resource and doesn’t scan the module for resources. This way, we control precisely which resources will be used, given the module.

This example also illustrates that, rather than passing strings to the resources, reroute and preroute functions, we can pass objects directly.

Error response generation

There are three cases for which bobo has to generate error responses:

1. When a resource can’t be found, bobo generates a “404 Not Found” response.
2. When a resource can be found but it doesn’t allow the request method, bobo generates a “405 Method Not Allowed” response.
3. When a query or post decorated function requires a parameter and the parameter is isn’t in the given form data, bobo generates a “405 Forbidden” response with a body that indicates the missing parameter.

For each of these responses, bobo generates a small HTML body.

Applications can take over generating error responses by specifying a bobo_errors option that specified an object or a module defining 3 callable attributes:

not_found(request, method)

Generate a response when a resource can’t be found.

This should return a 404 response.

method_not_allowed(request, method, methods)

Generate a response when the resource found doesn’t allow the request method.

This should return a 405 response and set the Allowed response header to the list of allowed headers.

missing_form_variable(request, method, name)

Generate a response when a form variable is missing.

The proper response in this situation isn’t obvious.

The value given for the bobo_errors option is either a module name, or an object name of the form: “module_name:expression”.

Let’s look at an example. First, an errorsample module:

import bobo, webob

@bobo.query(method='GET')
def hi(who):
    return 'Hi %s' % who

def not_found(request, method):
    return webob.Response("not found", status=404)

def method_not_allowed(request, method, methods):
    return webob.Response(
        "bad method "+method, status=405,
        headerlist=[
            ('Allow', ', '.join(methods)),
            ('Content-Type', 'text/plain'),
            ])

def missing_form_variable(request, method, name):
    return webob.Response("Missing "+name)

Then a configuration file:

[app:main]
use = egg:bobo
bobo_resources = errorsample
bobo_errors = errorsample

If we use the URL:

http://localhost:8080/hi.html?who=you

We’ll get the response:

Response: 200 OK
Content-Type: text/html; charset=UTF-8
Hi you

But if we use:

http://localhost:8080/ho

We’ll get:

Response: 404 Not Found
Content-Type: text/html; charset=UTF-8
not found

If we use:

http://localhost:8080/hi.html

We’ll get:

Response: 200 OK
Content-Type: text/html; charset=UTF-8
Missing who

If we make a POST to the same URL, we’ll get:

Response: 405 Method Not Allowed
Allow: GET
Content-Type: text/plain
bad method POST

We can use an object with methods rather than module-level functions to generate error responses. Here we define an errorsample2 module that defines an class with methods for generating error responses:

import bobo, webob

class Errors:

    def not_found(self, request, method):
        return webob.Response("not found", status=404)

    def method_not_allowed(self, request, method, methods):
        return webob.Response(
            "bad method "+method, status=405,
            headerlist=[
                ('Allow', ', '.join(methods)),
                ('Content-Type', 'text/plain'),
                ])

    def missing_form_variable(self, request, method, name):
        return webob.Response("Missing "+name)

In the configuration file, we specify an object, rather than a module:

[app:main]
use = egg:bobo
bobo_resources = errorsample
bobo_errors = errorsample2:Errors()

Note that in this example, rather than just using a global name, we use an expression to specify the errors object.

Uncaught exceptions

Normally, bobo let’s uncaught exceptions propagate to calling middleware or servers. If you want to provide custom handling of uncaught exceptions, you can include an exceptions method in object you give to bobo_errors.

import bobo, webob

class Errors:

    def not_found(self, request, method):
        return webob.Response("not found", status=404)

    def method_not_allowed(self, request, method, methods):
        return webob.Response(
            "bad method "+method, status=405,
            headerlist=[
                ('Allow', ', '.join(methods)),
                ('Content-Type', 'text/plain'),
                ])

    def missing_form_variable(self, request, method, name):
        return webob.Response("Missing "+name)

    def exception(self, request, method, exc_info):
        return webob.Response("Dang! %s" % exc_info[1], status=500)

Ordering Resources

When looking for resources (or sub-resources) that match a request, resources are tried in order, where the default order is the order of definition. The order can be overridden by passing an order using the order keyword argument to the bobo decorators [1]. The results of calling the functions bobo.early() and bobo.late() are typically the only values that are useful to pass. It is usually a good idea to use bobo.late() for subroutes that match any path, so that more specific routes are tried earlier. If multiple resources that use bobo.late() (or bobo.early()) match a path, the first one defined will be used.

[1]	Advanced applications may provide their own resource implementations. Custom resource implementations must implement the resource interface and will provide an order using the bobo_order attribute. See IResource.