bottle-streamline¶

Bottle route handlers behind the scenes¶

Conventional bottle route handlers are written as functions. There are also many decorators that you can use to modify the way these functions work (e.g., a @view() decorator that causes the output of your function to be rendered using a template).

Any parameters that are found in the path pattern that is associated with a route handler will be mapped to the function’s parameters. When the request is made to the path, handler will receive parsed out data as arguments.

The return value of a route handler function can be:

• a string
• an iterable of strings
• bottle.HTTPResponse object
• bottle.HTTPError objecta string
• file-like object (StringIO, file object, et al)

Bottle contains a function that looks at the return value, and then tries to determine the type. It does different things depending on what the value is, and converts it to a form that is compatible with the underlying WSGI protocol (it expects an iterable). This function is bottle.Bottle._cast(). Going through all the cases it handles would be too long, so we will only focus on the iterables which are relevant to bottle-streamline.

If the return value of a route handler is an iterable, then _cast() attempts to fetch the first object. Failing that, it returns an empty string. If the first object is found, it checks its type. It only allows two kinds of objects at this stage:

• HTTPResponse
• string (either unicode or bytes)

If the first object is an HTTPResponse object, _cast() is called on it.

How CBRH fit into bottle route handling¶

When a CBRH is invoked, it is basically instantiated (its __init__ method is invoked). Unlike handler functions, CBRHs don’t do any actual work when they are invoked/instantiated. Instead, they implement the container interface of the iterator types and presents itself as an iterator. The entire CBRH object is, therefore, acts as a http response.

The main implication of CBRH being an iterator container is that the response body (discussed in later chapters) can only be a string or HTTPResponse object. In your handler code, you cannot expect to return any other kind of object. If you need to return objects other than strings you need to either raise or return HTTPResponse objects (these objects double as exception classes so they can be raised) and pass the object you want to return as body. Here is an example:

class MyRoute(RouteBase):
    def get(self):
        data = open('somefile.ext', 'r')
        return self.HTTPResponse(data)

The following chapters will go into the details of how to use CBRH classes in different scenarios.

Named routes¶

Named routes can be useful if you want to change the paths later. Instead of using hard-coded paths, bottle allows you to construct the paths using a route name and parameters. This is facilitated by the (somewhat underdocumented) get_url() method.

This method takes a route name as its first argument, and route parameters as any number of additional keyword arguments.

All streamline CBRH are named by default, even if you don’t explicitly specify the name when invoking the route() method. The default name is calculated by using the name of the module in which your subclass resides, and the name of the class itself, which is decamelized. For instance, if your subclass is users.AccountList, it will be named users:account_list. Keeping your route handlers neatly organized and named will help you take advantage of this naming convention.

If you are not happy with the default names, you can supply an alternative name:

MyRoute.route('/hello/:name', name='hello')

You can also overload the get_generic_name() method:

class MyRoute(RouteBase):
    ....
    name = 'hello'

    @classmethod
    def get_generic_name(cls):
        return cls.name

The above example allows you to specify the route name as a name property.

Handling different HTTP methods¶

In a single route, you can have any number of methods that match HTTP verbs, and the route handler will be valid for those verbs. These methods can be:

• get()
• post()
• put()
• patch()
• delete()

A handler will only be registered for the HTTP methods it supports, and result in a HTTP 405 response for missing verbs.

You can have multiple route handlers with different verbs on the same path (if, for example, you wish to have different handlers for different verbs).

Including and excluding plugins¶

If you are using the bottle plugins, you can include additional plugins or skip the default ones by using include_plugins and exclude_plugins attributes. Both are lists of plugin names.

Here is an example:

class MyRoute(RouteBase):
    include_plugins = ['auth', 'session']
    exclude_plugins = ['static']
    ....

Route configuration¶

Normally, when invoking the bottle.route() function (or using it as a decorator), you can pass additional keyword arguments which become part of what is known as route configuration. The same is possible with the route() method.

Convenience properties and methods¶

The RouteBase class has several properties and methods that are added to its namespace for your convenience. These are:

• bottle: the bottle module
• request: bottle.request object
• response: bottle.response object
• abort(): bottle.abort() function
• redirect(): bottle.redirect() function
• HTTPResponse: bottle.HTTPResponse class

After initialization, two more properties will be available in the instances:

• app: application object that is tied to the request
• config: application’s configuration

Simple template rendering¶

The simple variant is the streamline.template.TemplateRoute, which renders a single template for all methods.

Let’s take a look at example code:

from streamline import TemplateRoute


class MyRoute(TemplateRoute):
    template_name = 'accounts/profile'

    def get(self, uid):
        return {'user': Users.get_by_id(uid)}


MyRoute.route('/profiles/:uid')

If you remember what we’ve discussed about the return value of route handlers, you will notice that a dict is not one of the allowed return values. This is because a dict is not returned directly by TemplateRoute handlers.

The return value of the business logic methods is used as a template context, and a template specified by the template_name is rendered and returned as response (a string).

If you return any object other than a dict, it wil also be made available to the template context as body variable. The only exception is a HTTPResponse object which completely bypasses template rendering.

XHR partial rendering¶

XHR partial rendering is a technique where we use full and partial HTML representations of a single resource and return one or the other depending on whether a request is made using XHR (AJAX) or not. This can be useful for partial page updates using XHR.

The streamline.template.XHRPartialRoute is a variant of the TemplateRoute which uses two template names and selects an alternative template when a request is made using XHR.

Here is an example:

from streamline import XHRPartialRoute


class MyRoute(XHRPartialRoute):
    template_name = 'accounts/profile'
    partial_template_name = 'accounts/_profile'

    def get(self, uid):
        return {'user': Users.get_by_id(uid)}


MyRoute.route('/profiles/:uid')

As we can see, most of the code is identical to the previous example, with the addition of partial_template_name property.

Using a different rendering function¶

The default implementation of the classes discussed in this chapter use bottle.template() function to render the templates. You can override this by assigning a different function to the template_func attribute on both classes.

Default context¶

The default context can be changed globally by modifying the bottle.BaseTemplate.defaults dict. This will change the default context for all route handlers.

With CBRH, you can additionally change the default context of the route handler classes by modifying the default_context property. By default, the default context is {'request': bottle.request}.

Dynamically changing parameters at runtime¶

All of the values we’ve covered thus far (template_name, partial_template_name, template_func and default_context) can be also modified dynamically by overloading the following methods:

• get_template_name()
• get_template_func()
• get_default_context()

In addition, the way final template context is calculated can also be changed. By default, the context is calculated by merging the default context and the return value of the business logic methods. By overloading the get_context() function, you can change this behavior.

Customizing the rendering function invocation¶

The rendering function is invoked by passing the template name as first positional argument, and template context as second. The function returns the rendered template as a string or an iterable of strings. This is done in the render_template() method. You can customize the behavior by overloading this method.

Form CBRH basics¶

The streamline.forms.SimpleFormRoute is, as its name suggest, a simple variant of form-handling CBRHs but it has all the fundamental pieces that you need to know in order to work with other variants. Let’s take a look at an example of how to works:

import bottle
from streamline import FormRoute

class Simple(FormRoute):
    def show_form(self):
        return 'Imagine this is a form'

    def form_valid(self):
        return 'OK'

    def form_invalid(self):
        self.response.status = 400
        return 'WRONG'

Simple.route('/simple')

The show_form() method is normally used to render the form or otherwise make the form controls available to the user. In this case, we’re simply returning a dummy string for simplicity. It’s more or less an alias for get() and there is nothing wrong with overloading the get() method instead.

The form_valid() and form_invalid() methods are called depending on whether the form is valid or not. Simple class has no validation code, so it will always validate.

Let’s add some validation code:

try:
    unicode = unicode
except NameError:
    unicode = str

required = lambda v: v and v.strip()
numeric = lambda v: unicode(v).strip().isnumeric() if v else True

The first lambda verfies that any data is entered and that the data is not just a series of whitespace characters. Second lambda makes the value optional, but, if specified, required it to be an integer. To make the two lambdas do anything, we first need to add them to the validator dictionary:

Simple.form_factory.validators['string'] = required
Simple.form_factory.validators['number'] = numeric

Now the Simple class is fully equipped to perform validation. Submitting data to an app running

Let’s test the form using curl:

$ curl --data "string=test" localhost:8080/simple
OK
$ curl --data "number=12" localhost:8080/simple
WRONG

It appears to be working.

Within the form_valid() and form_invalid() methods, the form object (as returned by the factory function) is available as the form property. Let’s use this to show a bit more information on sucessful submission:

def form_valid(self):
    return 'OK: {} {}'.format(self.form.data.get('string', ''),
                              self.form.data.get('number', ''))

Let’s test this:

$ curl --data "string=test" localhost:8080/simple
OK: test
$ curl --data "string=test&number=2" localhost:8080/simple
OK: test 2

Using form handling with template rendering¶

Form handling with template rendering is a cross between the FormRoute and the two template classes, TemplateRoute and XHRPartialRoute. The two classes are TemplateFormRoute and XHRPartialFormRoute.

We won’t go into the details of how they work because they are simply a mix of fetures provided by the template CBRHs and the features outlined in the previous section.

Customizing form validation¶

Form validation can be customized in a few different ways. Most straightforward way is to use a different (and proper) form or validation library and write an adaptor for it. Another possibility is to override the validate_form() method.

Here is an example of a custom form adaptor:

from streamline.forms import FormAdaptor


class MyAdaptor(FormAdaptor):
    def __init__(self, data):
        self.messages = {}
        super(MyAdaptor, self).__init__(data)

    def is_valid(self):
        try:
            my_cool_validation_library(self.data)
        except ValidationError as e:
            for error in e.errors:
                self.messages[error.field_name] = error.message
        return not self.messages:


class Simple(FormRoute):
    form_factory = MyAdaptor
    ...

The custom adaptor saves error messages in the messages property on the adaptor object so that it can be accessed in the form_invalid() method later.

Now let’s take a look at the second option of overloading the validation function:

class Simple(FormRoute):
    def __init__(self, *args, **kwargs):
        super(Simple, self).__init__(*args, **kwargs)
        self.errors = {}

    def validate_form(self, _):
        # We will completely ignore the form that is passed in, and instead
        # use ``request.forms``
        data = self.request.forms
        try:
            my_cool_validation_library(data)
        except ValidationError as e:
            for error in e.errors:
                self.errors[error.field_name] = error.message
        return not self.errors

It works similar to the first example, except we have chosen to ignore the form object that is passed in as an argument to validate_form(). The form object passed to this method is a form object returned by the factory function so we could have actually used the form.data instead of request.forms (they are identical).

Performing a redirect on sucessful submission¶

The most common way of performing a redirect is to use the bottle’s own redirect() function. This function is made available as a method on the CBRH instances. Here is an example:

class Simple(FormRoute):
    ...
    def form_valid(self):
        return self.redirect('/see-other')