Using SimpleStore with Pylons

Setting up your Pylons app

$ paster create -t pylons simpleapp
$ cd simpleapp

Note: Make sure you tell Paste to not use SQLAlchemy if it asks.

Edit development.ini in your favorite editor. Add the following lines to the [app:main] section:

simplestore.host = 127.0.0.1:3306
simplestore.user = simplestore_user
simplestore.db = simplestore_test_db

Note: Make sure the user and MySQL database you want to use actually exist on your server. Also, you can use a MySQL password by adding the line

simplestore.passwd = <your_password>

Now you need to create a Python file in simpleapp/model/ called db.py and add this line:

datastore = None

That line lets you bind a DataStore object to your project at runtime. It's similar to how SQLAlchemy is bound to a Pylons project.

Now edit simpleapp/config/environment.py You'll need to import a couple modules first:

from simplestore.datastore import DataStore
from simpleapp.model import db

In the same file, add a function init_datastore that looks like this:

def init_datastore(prefix='simplestore.'):
    kw = {}
    for key in ['host', 'user', 'passwd', 'db']:
        value = config.get(prefix + key)
        if value:
            kw[key] = value
    db.datastore = DataStore(**kw)

The config variable is actually imported from pylons and is used globally in your project.

Under the CONFIGURATION OPTIONS HERE comment, call init_datastore

init_datastore()

Now edit simpleapp/websetup.py so we can create the entities database table. Add these imports:

from simplestore import entities_table
from simpleapp.model import db

Inside the setup_app function, add the following lines:

# use global_execute as of simplestore 0.3
db.datastore.global_execute(entities_table)
db.datastore.close()

cd into the base simpleapp directory (where setup.py resides) and issue a paster setup-app development.ini command.

If you log in to your MySQL client you should see that the entities table was created. If not, something went wrong and you may need to go back through the steps to see what happened.

Setting up your controllers

Edit simpleapp/lib/base.py to look similar to this:

from pylons.controllers import WSGIController
from pylons.templating import render_mako as render

from simpleapp.model import db

class BaseController(WSGIController):

    def __call__(self, environ, start_response):
        try:
            return WSGIController.__call__(self, environ, start_response)
        finally:
            db.datastore.close()

That will tell your Pylons app to close the datastore connection after each request.

Creating SimpleStore models

Create and edit simpleapp/model/entry.py

from simplestore import model

class Entry(model.Model):

    id = model.KeyProperty(required=True)
    title = model.StringProperty()
    content = model.StringProperty()
    created_at = model.DateTimeProperty(auto_now_add=True)

Using the Entry model in a controller

cd into the base simpleapp directory and create a new controller for your app:

$ paster controller entry

Edit simpleapp/controllers/entry.py and add some imports

import uuid

from simpleapp.model import db
from simpleapp.model.entry import Entry

SimpleStore makes use of 32-byte UUIDs for its id columns. A function that is in /trunk but not a current release generates UUIDs for you. For now, just add this function to simpleapp/controllers/entry.py after the imports:

def generate_uuid():
    return str(uuid.uuid4()).replace('-', '')

Here's a sample controller that displays a form, creates a new entry, and then shows you the entry:

class EntryController(BaseController):

    def index(self):
        return """
        <form action="/entry/post" method="post">
            <table>
                <tr>
                    <td><label for="title">Title:</label></td>
                    <td><input type="text" name="title" id="title" /></td>
                </tr>

                <tr>
                    <td><label for="content">Content:</label></td>
                    <td><textarea name="content" id="content" rows="3" cols="30"></textarea></td>
                </tr>

                <tr>
                    <td>&nbsp;</td>
                    <td><input type="submit" /></td>
                </tr>
            </table>
        </form>
        """

    def post(self):
        title = request.POST['title']
        content = request.POST['content']

        entry = Entry(id=generate_uuid(), title=title, content=content)
        db.datastore.put(entry)

        redirect_to('/entry/show/%s' % entry.id)

    def show(self, id):
        entry = db.datastore.get(id)
        return """
        <h1>%s</h1>
        <p>%s</p>
        """ % (entry['title'], entry['content'])

In the future

There's still a lot to document, but this page on Pylons should get you up and running with SimpleStore. I still need to go over how the indexes work and how to do some more advanced stuff with SimpleStore.

If there are any problems with this documentation please let me know.