Let’s start by creating a new pylons project and some controllers.

Also, delete public/index.html.

For our controller main, we are going to add one action called index. This will be the main page for the site and will only be accessible for logged in users. If a user is not logged in, they will be redirected to the login page. Let’s add some routes for the main page, login, logout, and registration. Open up config/routing.py.

For checking to see if a user is logged in, we will store a user_id in the session. Let’s make a decorator that we can add to our index action that will check to see if a user is logged in. If the user isn’t logged in, it will redirect to the login page. Your controllers/main.py should look have this:

If you start the server now and go to http://localhost:5000 you will be redirected to /auth/login. Good. Let’s get into CouchDB now…

Open up http://localhost:5984/_utils and create a new database, and call it userdemo.

Now we are going to define our User schema in model/__init__.py. A schema describes a certain type of document, and in this case, it will be a User document. This example is very simple, so we only need username, password, and salt. Note the other field, type. This will specify that the document is for users, and it will be automatically set with the default parameter when we store a document. We are also going to create a simple helper function that will return an instance of our database(from couchdb-python).

Next, we are going to create a simple template for auth/login. This will prompt the user to login, or register if the user does not have an account. (I assume you are using mako for your template engine).

templates/login.mak:

Notice that we used h.text() and h.password(). These helpers create our input boxes and will also display an error when we get into form validation. Make sure to import those functions in lib/helpers.py.

Now that we’ve created or login template, let’s implement our action auth/login in controllers/auth.py.

Okay, let’s run the server and try to go to http://localhost:5000. We are redirect to our new login page.

Okay, now let’s implement our login action. This is under controllers/auth.py, and the action is login_post. The first thing we will do is add a formencode schema for our login form. This will make sure the username and/or password is not empty, and it will display an error accordingly. Here is what our new auth.py file might look like.

This login_post action first checks to see if the form is valid, if not, it will display the login form with the appropriate errors. If the form is valid, we attempt to call the function authenticate_user, which will return a valid User document if the login is successful, or raise an Exception if the login information is invalid. If the login is valid, we save the user.id in our session. If not, we set the invalid_user context variable and return the login page.

Okay, so we have our login_post action defined, but we don’t have an authenticate_user method yet. Let’s implement that. But before we do that, we need to know a little bit more about CouchDB views. A view is a way to query data from our database. A view is defined by implementing map and reduce functions.

Let’s start by adding a user view, that will let us query user data. To create the view, go to http://localhost:5984/_utils and select the userdemo database. Go to Create Document. We are going to create a design document which is where the views are defined. The document ID should be _design/user. This view is accessible via http://localhost:5984/userdemo/_view/user/VIEW_FUNC. To define our view functions, open the newly created _design/user document and add a field called views. For now, just put {} for the value. Hit save document.

Each view function defines a map and optionally a reduce function. This lets us limit and control what documents our view will return. For now, we just want a simple view that allows us to query the database and get a user by the username. Remember that CouchDB returns data with a key/value. The key we want to return is the username.

Let’s talk about map for a second. A map function is passed a CouchDB document, and then emits, or adds, key/value pairs. CouchDB uses javascript as the default view server. We will call our view function by_username, and it will return the username as the key and the user document as the value. Open your _design/user document and put this in for the views field.

CouchDB should look like this:

Notice that we check doc.type. This is because all documents are stored under one namespace, so we need a way to differentiate between different documents. We do this by setting a type field for every user, with the value “user”. You can access this view by going here: http://localhost:5984/userdemo/_view/user/by_username.

Alright, now that we have our view defined, let’s implement the authenticate_user function. We also create a custom exception class that we use for an invalid user. We use hashlib to generate a sha256 hash of the user’s password and a random salt. gen_hash_password is used later for our registration functions, for creating a new salt and getting a hash. Add this above your controller in controllers/auth.py.

Okay, now our site can login a user. Let’s get into registration. Create the following functions for our registration action in controllers/auth.py.

These functions are similar to the login ones, except here we store a new user into the database, using the User schema document class that we defined in model/__init__.py. We also need to implement the RegisterForm, and also a custom validator, which checks to see if a username is taken.

And that’s it! You can now register an account, login, and view the protected page(with the require_login decorator). Now you just need to add require_login to any function that is only for logged in users. In the next tutorial, I will go into some more advanced CouchDB topics and some cool map/reduce views.

You can download the pylons userdemo project here.

Django is a great web framework and I think it is perfect for people that want to build news/content sites. Everything in Django works very well together which makes it a one-stop shop.

Pylons is awesome too but compared to Django is lacking in a lot of documentation. You need to look in a lot of different places to learn all the aspects that Pylons has to offer. I will say that Genshi + SQLAlchemy + Pylons + Routes is very very powerful.

I’m going to be moving on to TurboGears now to see what is has different. I’ve read that the documentation is more complete but for the most part the components in each framework are pretty much the same(or can be).

Here it goes.