MongoDB and Python

Pyramid and MongoDB

Pyramid is an unopinionated web framework which resulted from the merge of the repoz.bfg framework into the Pylons umbrella project (not to be confused with Pylons 1.x, the web framework). Pyramid can be considered to be a bit like a Pylons 2.0; it is a clean break, a completely new codebase with no code-level backwards compatibility with Pylons 1.x.

However, many of the concepts are very similar to the older Pylons 1.x. Pyramid is where all the new development is happening, and it has fantastic code test coverage and documentation. This section is only intended to be a brief introduction to setting up a Pyramid project with a MongoDB connection. To learn more, refer to the excellent Pyramid book and other resources available free online at http://docs.pylonsproject.org/.

On its own, Pyramid is just a framework, a set of libraries you can use. Projects are most easily started from a what is known as a scaffold. A scaffold is like a project skeleton which sets up plumbing and placeholders for your code.

A number of different scaffolds are included with Pyramid, offering different persistence options, URL mappers and session implementations. Conveniently enough, there is a scaffold called pyramid_mongodb which will build out a skeleton project with MongoDB support for you. pyramid_mongodb eliminates the need for you to worry about writing the glue code to make a MongoDB connection available for request processing in Pyramid.

As with Pylons 1.x, to start using Pyramid you first need to create a virtual environment for your project. These instructions assume you have the virtualenv tool installed on your system. Install instructions for the virtualenv tool are provided in the first chapter of this book.

To create the virtual environment and install Pyramid and its dependencies, run the following commands:

virtualenv --no-site-packages myenv
cd myenv
source bin/activate
easy_install pyramid

Take note of the line sourcing the bin/activate script. It is important to remember to do this once in every shell to make the virtual environment active. Without this step, your default system Python install will be invoked, which does not have Pyramid installed.

Now your virtual environment has Pyramid and all its dependencies installed. However, you still need pyramid_mongodb and its dependencies like PyMongo etc. Run the following command to install pyramid_mongodb in your virtual environment:

easy_install pyramid_mongodb

With Pyamid and pyramid_mongodb installed in your virtual environment, you are ready to create a Pyramid project with MongoDB support. Decide upon a project directory and a project name. From that project directory execute in the shell:

paster create -t pyramid_mongodb <project_name>

After I ran the paster create command, a “mongofoo” directory (I chose “mongofoo” as my project name) was created with the following contents:

README.txt
development.ini
mongofoo
mongofoo.egg-info
production.ini
setup.cfg
setup.py

The default configuration files tell Pyramid to connect to a MongoDB server on localhost, and a database called “mydb”. If you need to change that, simply edit the mongodb.url and mongodb.db_name settings in the INI-files. Note that if you do not have a MongoDB server running at the address configured in the INI-file, your Pyramid project will fail to start.

Before you can run or test your app, you need to execute:

python setup.py develop

This will ensure any additional dependencies are installed. To run your project in debug mode, simply execute:

paster serve --reload development.ini

If all went well, you should see output like the following:

Starting subprocess with file monitor
Starting server in PID 54019.
serving on 0.0.0.0:6543 view at http://127.0.0.1:6543

You can now open http://localhost:6543/ in a web browser and see your Pyramid project, with the default template. If you made it this far, Pyramid is correctly installed and pyramid_mongodb was able to successfully connect to the configured MongoDB server.

The pyramid_mongodb scaffold sets up your Pyramid project in such a way that there is a PyMongo Database object attached to each request object. To demonstrate how to use this, open the file <project_name>/views.py in your favourite editor. There should be a skeletal Python function named my_view:

def my_view(request):
    return {'project':'mongofoo'}

This is a very simple Pyramid view callable. Pyramid view callables are similar to controller actions in Pylons 1.x, and are where much of the application-defined request processing occurs. Since view callables are passed an instance of a request object, which in turn has a property containing the PyMongo Database object, this is an ideal place to interact with MongoDB.

Imagine a somewhat contrived example whereby we wish to insert a document into a collection called “page_hits” each time the my_view view callable is executed. We could do the following:

import datetime
def my_view(request):
    new_page_hit = {"timestamp":datetime.datetime.utcnow(), "url":request.url}
    request.db.page_hits.insert(new_page_hit, safe=True)
    return {"project":"mongofoo"}

If you now reload the web page at http://localhost:6543 you should see a collection called “page_hits” in the MongoDB database you configured in your INI-file. In this collection there should be a single document for each time the view has been called.

From here, you should be well on your way to building web applications with Pyramid and MongoDB.