API Reference

This docs are generated from the docstirngs. Apart from that, feel free to study source code directly.

rainfall.web

class rainfall.web.Application(handlers, settings=None)

The core class that is used to create and start server

Parameters:

• handlers – dict with url keys and HTTPHandler or WSHandler subclasses
• settings –

  dict of app settings, defaults are settings = {

  ‘host’: ‘127.0.0.1’, ‘port’: 8888, ‘logfile_path’: None, ‘template_path’: None,

  }

Example:

app = Application({
    '/': HelloHandler,
})
app.run()

run(process_queue=None, greeting=True, loop=None, run_forever=True)

Starts server on host and port given in settings, adds Ctrl-C signal handler.

Parameters:

• process_queue – SimpleQueue, used by testing framework
• greeting – bool, wheather to print to strout or not
• loop – asyncio event loop, default is asyncio.get_event_loop()
• run_forever – bool=True, set to False if you do not want rainfall to call loop.run_forever()

class rainfall.web.RainfallProtocol

This is a subclass of WebSocketServerProtocol with HTTP flavour. The idea is following: try to parse websocket handshake, if it goes right, use websockets, else - call HTTPHandler.

general_handshake()

Try to perform the server side of the opening websocket handshake. If it fails, switch self._type to HTTP and return.

Returns the (method, url, headers, body)

Copy of WebSocketServerProtocol.handshake with HTTP flavour.

handler()

Presents the whole protocol flow. Copy of WebSocketServerProtocol.handler with HTTP flavour.

rainfall.http

exception rainfall.http.HTTPError(code=500, *args, **kwargs)

Representes different http errors that you can return in handlers.

Parameters:code – http error code

class rainfall.http.HTTPRequest(method, path, headers=None, body=None)

Rainfall implementation of the http request.

Parameters:raw – raw text of full http request

GET

Return type:dict, GET arguments

POST

Return type:dict, POST arguments

class rainfall.http.HTTPResponse(code=200, headers=None, body=None)

Rainfall implementation of the http response.

Parameters:

• body – response body
• code – response code
• additional_headers –

compose()

Composes http response from code, headers and body

Return type:str, composed http response

rainfall.http.read_message(stream)

Read an HTTP message from stream. Return (start_line, headers, body) where start_line is bytes. headers is a Message and body is str.

Copy of websocket.http.read_message with body support.

rainfall.http.read_request(stream)

Read an HTTP/1.1 request from stream.

Return (method, uri, headers, body) uri isn’t URL-decoded.

Raise an exception if the request isn’t well formatted.

Copy of websocket.http.read_request with body support.

rainfall.unittest

class rainfall.unittest.RainfallTestCase(methodName='runTest')

Use it for your rainfall test cases. In setUp rainfall server is starting in the separate Process.

You are required to specify an app variable for tests. E.g.

from example import my_first_app


class HTTPTestCase(RainfallTestCase):
    app = my_first_app

    def test_basic(self):
        r = self.client.query('/')
        self.assertEqual(r.status, 200)
        self.assertEqual(r.body, 'Hello!')

Inside you can use TestClient’s instance via self.client

class rainfall.unittest.TestClient(host, port)

Helper to make request to the rainfall app. Created automatically by RainfallTestCase.

query(url, method='GET', params=None, headers={})

Run a query using url and method. Returns response object with status, reason, body