Quickstart

This section will guide you through everything you need to know to get up and running with flask-simple!

Installation

The first thing you need to do is install flask-simple. Installation can be done through pip, the Python package manager.

To install flask-simple, run:

$ pip install flask-simple

If you’d like to upgrade an existing installation of flask-simple to the latest release, you can run:

$ pip install -U flask-simple

Set Environment Variables

In order to run properly, flask-simple requires that you set several environment variables.

The required environment variables are:

• AWS_ACCESS_KEY_ID (your Amazon access key ID)
• AWS_SECRET_ACCESS_KEY (your Amazon secret access key)

There is also an optional variable you can set:

• AWS_REGION (defaults to us-east-1)

These credentials can be grabbed from your AWS Console.

Note

A full list of Amazon regions can be found here: http://docs.aws.amazon.com/general/latest/gr/rande.html#sdb_region

If you’re unsure of how to set environment variables, I recommend you check out this StackOverflow question.

Specify Your Domains

The next thing you need to do is tell flask-simple which domains you’ll be using.

If you’re not sure how domains work with SimpleDB, you should read through the boto SimpleDB tutorial before continuing.

The way you can specify your domains is by creating an array called SIMPLE_DOMAINS (this is what flask-simple uses to set everything up).

Below is an example:

# app.py


from flask import Flask
from flask.ext.simple import Simple

app = Flask(__name__)
app.config['SIMPLE_DOMAINS'] = [
    'users',
    'groups',
]

In the above example, I’m defining two SimpleDB domains: users and groups.

flask-simple will respect any boto domains you define.

Initialize simple

Now that you’ve defined your domains, you can initialize flask-simple in your app.

All you need to do is pass your app to the simple constructor:

# app.py


from flask import Flask
from flask.ext.simple import Simple

app = Flask(__name__)
app.config['SIMPLE_DOMAINS'] = [
    'users',
    'groups',
]

simple = Simple(app)

From this point on, you can interact with SimpleDB through the global simple object.

Create Your Domains

If you haven’t already created your SimpleDB domains, flask-simple can help you out!

After configuring flask-simple, you can use the following code snippet to create all of your predefined SimpleDB domains:

with app.app_context():
    simple.create_all()

This works great in bootstrap scripts.

Working with Domains

Now that you’ve got everything setup, you can easily access your domains in one of two ways: you can either access the domains directly from the simple global, or you can access the domains in a dictionary-like format through simple.domains.

Below is an example view which creates a new user account:

# app.py

@app.route('/create_user')
def create_user():
    simple.users.put_attributes('r@rdegges.com', {
        'username': 'rdegges',
        'first_name': 'Randall',
        'last_name': 'Degges',
        'email': 'r@rdegges.com',
    })

    # or ...

    simple.domains['users'].put_attributes('r@rdegges.com', {
        'username': 'rdegges',
        'first_name': 'Randall',
        'last_name': 'Degges',
        'email': 'r@rdegges.com',
    })

Either of the above will work the same.

Note

When storing items in SimpleDB, you need to specify two fields: an item name (the first parameter), and the item contents (a Python dictionary).

On a related note, you can also use the simple.domains dictionary to iterate through all of your domains (this is sometimes useful). Here’s how you could iterate over your existing SimpleDB domains:

# app.py

with app.app_context():
    for domain_name, domain in simple.domains.iteritems():
        print domain_name, domain

Deleting Domains

If, for some reason, you’d like to destroy all of your predefined SimpleDB domains, flask-simple can also help you with that.

The below code snippet will destroy all of your predefined SimpleDB domains:

# app.py

with app.app_context():
    simple.destroy_all()

Note

Please be extremely careful when running this – it has the potential to completely destroy your application’s data!