Note: this is an archive of an old project. I originally wrote it back in about 2007-2008. It was (IMO) good code for the time, but probably isn't something that you want to use now. I'm just posting it up here for posterity. It was originally documented here: https://code.google.com/archive/p/microapps/wikis/Bourbon.wiki Bourbon ======= Bourbon is a small framework designed to make it easy to develop and deploy simple microapps. The idea is that you define a database model (with SQLAlchemy currently) and some minimal controller classes that tie that model to some url patterns (via Selector and WSGICollection) and the usual CRUD methods are then accessible via HTTP. Current Features: * Basic HTTP method to -> CRUD mapping. * JSON loading and rendering * automatic transaction support * strict adherence to rfc2616 (HTTP 1.1) * nested structures * paste deployment with .ini config files * paste template for "quickstart": paster create -t bourbon myapp Todo: * use paste.fixture for more help with testing * content negotiation * command line tools for database init, etc. * better automatic figuring out of primary key columns and parent-child relationships with the url mapping * more hooks to override the default behavior * abstract out ORM requirements so SQLObject or other mappers can be used instead of SQLAlchemy * eliminate need for 'python setup.py develop' step * logging configuration Example: ======== Say we want to create a very simple microapp that stores articles, which each may belong to a category. We'll call our app "storytime". We first use paster to create a skeleton bourbon project for us: $ paster create -t bourbon storytime Enter whatever information you want when it prompts you. The result will be a directory called 'storytime' with the following structure: ------------------------------------- /setup.py /development.ini /storytime.db /storytime/ __init__.py model.py controllers.py wsgiapp.py ------------------------------------- Next we need to define our model in storytime/model.py. Add the following to it: ------------------------------------- # tables category_table = Table('category', metadata, Column('name', String(256), primary_key=True)) story_table = Table('story', metadata, Column('slug',String(256), primary_key=True), Column('title',String(256), index=True, nullable=False), Column('author_name',String(256)), Column('body',String(30000)), Column('created',DateTime,default=datetime.now), Column('category_name',String(256), ForeignKey('category.name'))) # domain classes class Category(object): pass class Story(object): pass # mappers categorymapper = mapper(Category,category_table,properties = { 'stories' : relation(Story, cascade="all, delete-orphan",backref='category')}) storymapper = mapper(Story,story_table) ---------------------------------------- Pretty basic. SQLAlchemy can be a bit verbose, but it's straightforward. Note that the model contains nothing Bourbon related. It's just a plain SQLAlchemy model and could be imported into and used with anything else. storytime/controllers.py sets up the HTTP -> model mapping. We need to create some controller objects and map them to urls. Add two controller classes: ---------------------------------------- class CategoryCollection(Resource): domain_class = Category id_column = Category.c.name class StoryCollection(Resource): domain_class = Story id_column = Story.c.slug parent = dict(column = Story.c.category_name, param = "categoryname", parent_class = Category, parent_class_id_column = Category.c.name) ---------------------------------------- and then add two corresponding url mappers to the end: ---------------------------------------- urls.add('/[{id:word}][;{noun}]', _ANY_=CategoryCollection()) urls.add('/{categoryname}/[{id:word}][;{noun}][/]', _ANY_=StoryCollection()) ---------------------------------------- This is best understood starting with the last couuple lines. Those set up url mappings using selector, mapping all HTTP methods to our controllers and putting a couple particular variables into the WSGI environ so Bourbon can automatically construct/fetch the right model objects. development.ini is a standard paste.deploy config file that 'paster serve' can run. Edit it to change the port number and/or the database connection info (defaults to port 9080 and a sqlite database named for the package). ####################################### currently, it seems necessary to run $ python setup.py develop to get the entry points picked up. I'm still not sure why, but I hope to make that step not necessary ####################################### You should now manually initalialize the database (commandline tools for this are forthcoming): $ python >>> from storytime.model import * >>> engine = create_engine("sqlite:///storytime.db") >>> metadata.create_all(connectable=engine) Then you can run the app with paster server: $ paster serve development.ini And you now have HTTP+JSON access to the database on port 9080. So, eg. $ curl http://localhost:9080/ {"members": [], "next": null} add some categories: $ curl -X PUT http://localhost:9080/world $ curl -X PUT http://localhost:9080/local $ curl http://localhost:9080/ {"members": [{"href": "world"}, {"href": "local"}], "next": null} GET /world gets the category itself $ curl http://localhost:9080/world {"name": "world"} while GET /world/ gets the collection of stories in the category (currently none) $ curl http://localhost:9080/world/ {"members": [], "next": null} DELETE the local category: $ curl -X DELETE http://localhost:9080/local $ curl http://localhost:9080/ {"members": [{"href": "world"}], "next": null} add a story to the world category $ curl -X PUT -d '{"title" : "World Peace Achieved", "author_name" : \ "Dan Rather", "body" : "Yay!"}' http://localhost:9080/world/rather-world-peace an alternate way to add a story: $ curl -X POST -d '{"title" : "Caffeinated Donuts Invented", "author_name" : \ "Dan Rather", "body" : "Better than world peace!", "slug" : \ "rather-donuts"}' http://localhost:9080/world/ The second approach uses a POST to the collection instead of a direct PUT to the resource location. This is how you'll want to do it anytime you use auto-generated keys, or if, eg, the slug was being automatically generated from the title or something. In the style of the Atom API and Ruby on Rails' SimplyREST, you can also define additional actions for controllers to respond to. That's what the '{noun}' stuff in the url mapping was for. You just need to add a method to the appropriate controller object with a name of '<http method>_<noun>'. Eg, to respond to a GET request on '/world;edit_form' you would add a method to CategoryCollection: def get_edit_form(self, environ, start_response): # make a form, call start_response() and # yield the content Within that method, you may want to access the SQLAlchemy session and the model object that the controller is mapped to. you can do that with self._session() and self._fetch(environ) respectively. All methods are automatically wrapped in a transaction. Raising an exception will cause it to rollback.