bzz - the rest framework for worker bees

bzz is a rest framework aimed at building restful apis for the tornado web framework.

https://travis-ci.org/bzz-framework/bzz.svg?branch=master https://coveralls.io/repos/bzz-framework/bzz/badge.png

Getting Started

Installing bzz is as simple as:

$ pip install bzz

After you have it installed, you need to decide what ORM you’ll be using for your models. bzz comes bundled with support for the mongoengine library.

We’ll assume you’ll be using it for the sake of this tutorial. Let’s create our model and our tornado server, then:

import tornado.web
from mongoengine import *
import bzz

# just create your own documents
class User(Document):
   __collection__ = "GettingStartedUser"
   name = StringField()

def create_user():
   # let's create a new user by posting it's data
   http_client.fetch(
      'http://localhost:8888/user/',
      method='POST',
      body='name=Bernardo%20Heynemann',
      callback=handle_user_created
   )

def handle_user_created(response):
   # just making sure we got the actual user
   try:
       assert response.code == 200
   finally:
       io_loop.stop()

# bzz includes a helper to return the routes for your models
# returns a list of routes that match '/user/<user-id>/' and allows for:
# * GET without user-id - Returns list of instances
# * GET with user-id - Returns instance details
# * POST with user-id - Creates new instance
# * PUT with user-id - Updates instance
# * DELETE with user-id - Removes instance
routes = [
    bzz.ModelHive.routes_for('mongoengine', User)
    # and your other routes
]

routes = bzz.flatten(routes)  # making sure tornado gets the correct routes

# Make sure our test is clean
User.objects.delete()

application = tornado.web.Application(routes)
server = HTTPServer(application, io_loop=io_loop)
server.listen(8888)
io_loop.add_timeout(1, create_user)
io_loop.start()

Flattening routes

utils.flatten(routes)

Gets a list of routes that includes hive-generated routes (model, auth or mock), as well as user created routes and flatten the list to the format tornado expects.

Can be used in bzz namespace:

import bzz
bzz.flatten(routes)
Parameters:routes – list of routes created by bzz hives or by the user
Returns:List of routes that a tornado app expects.