ReleaseEngineering/BuildAPI

Overview

The BuildAPI is a Pylons project used by RelEng to surface information collected from two databases updated through our buildbot masters as they run jobs.

Project Requirements

To run an instance of the buildAPI locally, you will need the following:

• Python w/ easy_install
• MySQL
• Google python visualizations library (gviz_api)
• python-mysqldb
• Snapshots of our two databases 'statusdb' and 'schedulerdb'. They are available here and here respectively. (older snapshot)

Not required, but it would be highly recommended to set up a python virtualenv to work under.

Getting Started

The source for the buildapi is available here: buildapi source

Before you get started with that, you should setup your MySQL database instances. To do that all you need to do is download, extract and load the sql dumps provided. So, create the databases first

$ mysql -u <user> -p
<at prompt>
mysql>create database schedulerdb;
mysql>create database statusdb;
mysql>exit

Download the sql dumps, then load them into the db with:

mysql schedulerdb -u <user> -p < schedulerdb.sql
mysql statusdb -u <user> -p < statusdb.sql

NOTE: The files unzipped can account for more than 10GB. Watch out! :)

Now, to get started with the pylons project, simply run:

 easy_install buildapi

which should handle grabbing pylon project dependencies. You will also need to grab and install the google python visualization library from here.

Next you will need to generate a config file for your project, do this by running:

 paster make-config buildapi config.ini

Now you will need to edit that config.ini to use the correct host(localhost should be fine), and database URLs. Note: MySQL databases take the format `mysql://[username][:password][@hostname]/database_name`

You should now be all set up now! Running the project locally can be done through:

 paster serve --reload --daemon config.ini

Which starts running the buildapi on your local machine. To view it, open up http://localhost:5000.

Building a simple controller

The buildAPI is built on top of the pylons framework, which enforces a strict MVC stack. To add a new feature to the buildapi you will typically want to create a new controller and associate it with one or more models and views.

To create a simple 'hello world' controller, first use paster to create a template to work with.

 # in buildapi/
 paster controller hello_world

This automatically creates a workable template and a functional test case for your new controller. You can now hack the newly created file under buildapi/controllers to your heart's content. Models associated with your controller can be created under buildapi/model. Views are created using Mako python templates. Create a template file under buildapi/templates for your new controller.

To associate with a model, simply add an import to your controller; for example:

 from buildapi.model.<model_name> import <functions to import>

Lastly, once you're done editing your controller and have a resultset to publish, you probably want to render a page. To do this you can call render('/<template-name>.mako') from your controller body to render a view with your results. To access results from your controller, it is best to store the results in a pylons.tmpl_context object, which will make them available to your mako template.

Simple code sample

Now, to write a simple controller that prints "Hello World" using an M-V-C stack, we need three files:

• controllers/hello.py
• model/hello.py
• templates/hello.mako

Our controller lives in: controllers/hello.py

import logging

from pylons import request, response, session, tmpl_context as c, url
from pylons.controllers.util import abort, redirect

from buildapi.lib.base import BaseController, render
from buildapi.model.hello import GetMessage

log = logging.getLogger(__name__)

class HelloController(BaseController):

    def index(self):
        # Return a rendered template
        c.message = GetMessage()
        return render('/hello.mako')

Our model lives in: model/hello.py

def GetMessage():
    return "Hello world!"

Our view lives in: templates/hello.mako (note that the tmpl_context object is available in the template)

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>Hello World!</title>
</head>
<body>
<h1>${c.message}</h1>
</body>
</html>

Troubleshooting Tips

No MySQLdb

If after installing you run:

 paster serve --reload --daemon config.ini

and it does not start the server, check paster.log and if you see "ImportError: No module named MySQLdb" then you need to easy_install MySQL-python into the site-packages of the python it's looking for MySQLdb in.