API

waterspout.app

class waterspout.app.Waterspout(import_name=None, handlers=None, **config)

TestClient()

Return the TestClient.

Use it like

client = waterspout.TestClient()
assert client.get('/').body == 'Hello World'

add_handler(pattern, handler_class, kwargs=None, name=None)

Add a handler_class to App.

Parameters:

• pattern – Regular expression to be matched. Any groups in the regex will be passed in to the handler’s get/post/etc methods as arguments.
• handler_class – RequestHandler subclass to be invoked.
• kwargs – (optional) A dictionary of additional arguments to be passed to the handler’s constructor.
• name – (optional) A name for this handler. Used by waterspout.reverse_url.

filter(f)

Decorator to add a filter to Waterspout.

Add your filter like

waterspout = Waterspout()

@waterspout.filter
def sort(l):
    return l.sort()

And use it in your template

{{ [1, 4, 5, 3, 2] | sort }}

Parameters:f – function to add as a filter.

register_app(app, prefix='', domain='')

Register an app to waterspout.

Parameters:

• app – A Waterspout app.
• prefix – URL prefix for this app. Will be /<app_name> by default
• domain – Domain for this app.

run()

Run your Waterspout Application.

user_loader(f)

Decoration to change the user loader function.

Example

@waterspout.user_loader
def load_user(session):
    return User.get(int(session["id"]))

Parameters:f – the user loader function

class waterspout.app.App(name, import_name=None, handlers=None)

The App in Waterspout is just like the App in Django. A Waterspout Application consists of plenty of Apps.

The minimal App

from waterspout.app import App
from waterspout.web import RequestHandler


class Foo(RequestHandler):
    def get(self):
        self.write('This is foo app.')

handlers = [
    ('/', Foo)
]

app = App('app name', __name__, handlers)

TestClient()

Return the TestClient for the current Waterspout.

Use it like

client = app.TestClient()
assert client.get('/').body == 'Hello World'

add_handler(pattern, handler_class, kwargs=None, name=None)

Add a handler_class to App.

Parameters:

• pattern – Regular expression to be matched. Any groups in the regex will be passed in to the handler’s get/post/etc methods as arguments.
• handler_class – RequestHandler subclass to be invoked.
• kwargs – (optional) A dictionary of additional arguments to be passed to the handler’s constructor.
• name – (optional) A name for this handler. Used by Waterspout.reverse_url.

filter(f)

Decorator to add a filter to Waterspout App.

Add your filter like

app = App('test')

@app.filter
def sort(l):
    return l.sort()

And use it in your template

{{ [1, 4, 5, 3, 2] | sort }}

Parameters:f – function to add as a filter.

user_loader(f)

Decoration to change the user loader function.

Example

@app.user_loader
def load_user(session):
    return User.get(int(session["id"]))

Parameters:f – the user loader function

waterspout.web

class waterspout.web.RequestHandler(*args, **kwargs)

Base RequestHandler for Waterspout Application

flash(message, category='message')

Flashes a message to the next request. In order to remove the flashed message from the session and to display it to the user, the template has to call get_flashed_messages().

Parameters:

• message – the message to be flashed.
• category – the category for the message. The following values are recommended: 'message' for any kind of message, 'error' for errors, 'info' for information messages and 'warning' for warnings. However any kind of string can be used as category.

get_flashed_messages(with_categories=False, category_filter=[])

Pulls all flashed messages from the session and returns them. Further calls in the same request to the function will return the same messages. By default just the messages are returned, but when with_categories is set to True, the return value will be a list of tuples in the form (category, message) instead.

Filter the flashed messages to one or more categories by providing those categories in category_filter. This allows rendering categories in separate html blocks. The with_categories and category_filter arguments are distinct:

• with_categories controls whether categories are returned with message text (True gives a tuple, where False gives just the message text).
• category_filter filters the messages down to only those matching the provided categories.

Parameters:

• with_categories – set to True to also receive categories.
• category_filter – whitelist of categories to limit return values

globals

An alias for Environment.globals in Jinja2.

render(template_name, **kwargs)

Renders the template with the given arguments as the response.

Parameters:

• template_name – name of template file
• kwargs – arguments passing to the template

render_string(template_name, **kwargs)

Generate the given template with the given arguments.

We return the generated string. To generate and write a template as a response, use render() above.

Parameters:

• template_name – name of template file
• kwargs – arguments passing to the template

template_namespace

A dictionary to be used as the default template namespace.

class waterspout.web.APIHandler(*args, **kwargs)

Handler class for writing JSON API

write(chunk, callback=None)

Writes the given chunk to the output buffer.

Parameters:

• chunk –

  chunk to be written to the output buffer. If the given chunk is a dictionary or a list, we write it as JSON and set the Content-Type of the response to be application/json. (if you want to send JSON as a different Content-Type, call set_header after calling write()).

  Note that lists are converted to JSON can cause a potential cross-site security vulnerability. More details at http://is.gd/2LqAcE

• callback – callback function name for JSONP. We will look for callback argument if callback is not provided. Waterspout will write your chunk as JSONP if callback is not None.

waterspout.testing

class waterspout.testing.TestClient(application)

A test client for writing test for Tornado Application

Usage

client = TestClient(application)

assert client.get('/').body == 'Hello World'
assert client.post('/').body == '0 o'

Parameters:application (A Tornado Application.) – The application to be tested.

waterspout.config

class waterspout.config.Config(root_path=None, defaults=None)

Works exactly like a dict but provides ways to fill it from files or special dictionaries. There are two common patterns to populate the config.

Either you can fill the config from a config file:

config.from_pyfile('yourconfig.cfg')

Or alternatively you can define the configuration options in the module that calls from_object() or provide an import path to a module that should be loaded. It is also possible to tell it to use the same module and with that provide the configuration values just before the call:

DEBUG = True
COOKIE_SECRET = 'development key'
config.from_object(__name__)

In both cases (loading from any Python file or loading from modules), only uppercase keys are added to the config. This makes it possible to use lowercase values in the config file for temporary values that are not added to the config or to define the config keys in the same file that implements the application.

Probably the most interesting way to load configurations is from an environment variable pointing to a file:

config.from_envvar('YOURAPPLICATION_SETTINGS')

In this case before launching the application you have to set this environment variable to the file you want to use. On Linux and OS X use the export statement:

export YOURAPPLICATION_SETTINGS='/path/to/config/file'

On windows use set instead.

Parameters:

• root_path – path to which files are read relative from.
• defaults – an optional dictionary of default values

waterspout.utils

waterspout.utils.smart_quote(url)

Like urllib.parse.quote, but quote non-ascii words only.

Example ::

smart_quote(“http://whouz.com”) # http://whouz.com smart_quote(“喵.com”) # %E5%96%B5.com

waterspout.utils.get_root_path(import_name)

Returns the path to a package or cwd if that cannot be found. This returns the path of a package or the folder that contains a module.

Not to be confused with the package path returned by find_package().

waterspout.utils.import_string(import_name, silent=False)

Imports an object based on a string. This is useful if you want to use import paths as endpoints or something similar. An import path can be specified either in dotted notation (xml.sax.saxutils.escape) or with a colon as object delimiter (xml.sax.saxutils:escape).

If silent is True the return value will be None if the import fails.

Parameters:

• import_name – the dotted name for the object to import.
• silent – if set to True import errors are ignored and None is returned instead.

Returns:

imported object

class waterspout.utils.ObjectDict

Makes a dictionary behave like an object, with attribute-style access

foo = ObjectDict()
foo['bar'] = 42
assert foo.bar == 42

class waterspout.utils.cached_property(func)

A decorator that converts a function into a lazy property. The function wrapped is called the first time to retrieve the result and then that calculated result is used the next time you access the value:

class Foo(object):

    @cached_property
    def foo(self):
        # calculate something important here
        return 42

The class has to have a __dict__ in order for this property to work.