Scheduling Posts with Blogofile

I wanted to be able to schedule posts with blogofile and this was the quickest way I could think of to do it. If someone knows of a better way, than please comment cause I would love to read about.

My change is pretty simple, if the date in the YAML header is > than now, throw a PostProcessing exception and continue on with the next post. I added a cronjob that runs blogofile build every hour, so this solution sucks for blogs that take a long time to build or if you want precision scheduling, but my site builds fast and I am ok with an hour delay.

diff -r e370cb5a903f blog/_controllers/blog/post.py
--- a/blog/_controllers/blog/post.py    Tue Aug 23 23:16:37 2011 -0400
+++ b/blog/_controllers/blog/post.py    Sun Aug 28 19:03:28 2011 -0400
@@ -70,7 +70,14 @@
     def __str__(self):
         return repr(self.value)

+class PostProcessException(Exception):

+    def __init__(self, value):
+        self.value = value
+
+    def __str__(self):
+        return repr(self.value)
+                
 class Post(object):
     """
     Class to describe a blog post and associated metadata
@@ -179,7 +186,11 @@
             self.slug = slug

if not self.date:
-            self.date = datetime.datetime.now(pytz.timezone(self.__timezone))
+            self.date       = datetime.datetime.now(pytz.timezone(self.__timezone))
+        else:
+            if self.date > datetime.datetime.now(pytz.timezone(self.__timezone)):
+                raise PostProcessException('Post date is in the future.')
+
         if not self.updated:
             self.updated = self.date

@@ -367,7 +378,7 @@
             raise
         try:
             p = Post(src, filename=post_fn)
-        except PostParseException as e:
+        except (PostParseException,PostProcessException) as e:
             logger.warning(u"{0} : Skipping this post.".format(e.value))
             continue
         #Exclude some posts

Hooking up Whoosh and SQLalchemy (sawhoosh)

I was talking to Tim VanSteenburgh (we both do work for Geek.net) and he had a proof of concept for automatically updating a search index when a change happens to a model and pairing a unified search results page with that to make an easy one-stop search solution for a website. I thought this was a pretty cool idea, so I decided to do a implementation of it on top of the Pyramid framework and share it the readers of my blog. I choose Whoosh only so that I could have an easy way for users to try the project out. Since whoosh is pure python it installs when you run your setup.py develop. But this approach could be applied to any searching system. Tim was using solr.

Demo Project

The purpose of the post is to summarize briefly the steps taken to achieve the desired results of automatically updating the index information when models change. Please browse the source and clone and run the project, looking at the source as a whole will definitely give you a better start to finish understanding than just reading this blog post.

GitHub: sawhoosh

Whooshing Your Models

There are few parts that make up the magic of all this, but each part is really simple. First you have the index schema itself. This is setup to hold the unique ID of an item, as well as a pickled version of the uninstantiated class, and an aggregate of values (decided by you) that you want to be searchable for the item. The schema looks like this:

class SawhooshSchema(SchemaClass):
    value = TEXT
    id = ID(stored=True, unique=True)
    cls = ID(stored=True)

In the Whoosh world this basically says store ID and CLS so it comes back with the search results, but not value. value will be what we will search over in order to find our results. We need to tell our models what attributes are important to use for indexing, I've chosen to do this with a whoosh_value property on the model itself.

class Document(Base):
    __tablename__ = 'document'
    __whoosh_value__ = 'id,title,content,author_id'
    id = Column(CHAR(32), primary_key=True, default=new_uuid)
    title = Column(String, nullable=False)
    content = Column(Text, nullable=False)
    author_id = Column(Integer, ForeignKey('author.id'), index=True)
    def __str__(self):
        return u'Document - Title: {0}'.format(self.title)

This says make the id, title, content, and author_id for document all searchable values. This happens automatically for us because our Base class has a parent class that handles all of the Whoosh work. This parent class, I've called it SawhooshBase, handles all the indexing, reindexing, and deindexing of our models. The class itself looks like this:

class SawhooshBase(object):
    # The fields of the class you want to index (make searchable)
    __whoosh_value__ = 'attribue,attribute,...'
    def index(self, writer):
        id = u'{0}'.format(self.id)
        cls = u'{0}'.format(pickle.dumps(self.__class__))
        value = u' '.join([getattr(self, attr) for attr in self.__whoosh_value__.split(',')])
        writer.add_document(id=id, cls=cls, value=value)
    def reindex(self, writer):
        id = u'{0}'.format(self.id)
        writer.delete_by_term('id', self.id)
        self.index(writer)
    def deindex(self, writer):
        id = u'{0}'.format(self.id)
        writer.delete_by_term('id', self.id)

Base = declarative_base(cls=SawhooshBase)

As you can see in the index method, we use the whoosh_value to create an aggregate of searchable strings and supply that to the value we defined in our search schema. We pickle the class and also store the ID. This is what later lets us easily take search results and turn them in to object instances.

Those methods above are only ever run by our SQLalchemy after_flush session event, though that is not to say you couldn't run them manually. The callback and event hook looks like this:

def update_indexes(session, flush_context):
    writer = WIX.writer()
    for i in session.new:
        i.index(writer)
    for i in session.dirty:
        i.reindex(writer)
    for i in session.deleted:
        i.deindex(writer)        
    writer.commit()
event.listen(DBSession, 'after_flush', update_indexes)

The WIX object you see being used here is created much the same way you create your DBSession and you can view that in the search.py file of the project. Everything else is pretty straight forward. Call the respective indexer methods for new, dirty, and deleted items in the session.

Using in the View

Now we have our models all whooshified (technical term) and we want to have our users searching and displaying usable results. To start we have a simple search form that when submitted does a GET request to our search method with keywords. Now since the whoosh query parser is already smart enough to pickup things like AND and OR we don't have to do much.

The view code itself is where we use another helper method called results_to_instance (also in search.py). This method takes our search results, unpickles the class, fetches the instance from the DB and places the result in to a list. That method looks like this:

def results_to_instances(request, results):
    instances = []
    for r in results:
        cls = pickle.loads('{0}'.format(r.get('cls')))
        id = r.get('id')
        instance = request.db.query(cls).get(id)
        instances.append(instance)
    return instances

Now this is where you see the benefit of pickling the class type with the search result. We have ready to use instances of multiple types from a single search result. We can pass them in to a template to render the results, but since we have a mix of instance types, we need a unified way to render them out without explicitly checking their type or using a series of if attribute checks. I decided I would use str on the model to be a search results safe friendly way to display the object to the user and that I would define a route_name helper method on the model so that I can use request.route_url(object.route_name()) to generate the clickable links in the results. The combination of this can be viewed below:

%if results:

% for r in results:
    
${r}
%endfor

%else:
No results found
%endif

And the view itself uses some things we haven't talked about yet. QueryParser is just part of Whoosh and it is what turns your keywords in to something useful. request.ix is just a shortcut to our WIX object we created, we've added it using a custom Request class (same as we've done with db), you can see that in the security.py file of the project. From there we render the search results html and return it to our AJAX caller to inject in to the page. You can see this is also where we use the results_to_instances method discussed earlier.

@view_config(route_name='search', renderer='json', xhr=True)
def search_ajax(request):
    query = request.params.get('keywords')
    parser = QueryParser('value', request.ix.schema)
    with request.ix.searcher() as searcher:
        query = parser.parse(query)
        results = searcher.search(query)
        search_results_html=render('sawhoosh:templates/search/results.mako',
                              dict(results=results_to_instances(request, results)),
                              request=request)
    return dict(search_results_html=search_results_html)

Summary

There you have it. A search indexer using SQLalchemy on top of Pyramid. I highly recommend you clone the git repo for this project or review the code using the Git website if you are interested in getting a start to finish feel. The project allows you to add Authors and Documents and Edit and Delete them all while updating the local search index stored in the a directory on the file system.

GitHub: sawhoosh

Pyramid and Traversal with a RESTful interface

UPDATE (2011-08-05)

Please use caution when reading this post. A lot of the approach and implementation here is flawed. I am keeping the post up for historical purposes, but I am currently working on a follow up post that has a much better and proper implementation of traversal for SQLalchemy models. The practice of not returning real instances as traversal expects and tightly coupling the models to the traversal method is something that is less than desirable and will lead to more pain than gain long term. That being said, some of the approaches here are a good way to learn about traversal and how one might want to use it with their data model.

Original Post

When Pyramid was first being developed I was intrigued by the idea that I could create context aware views and use a host of methods to check permissions on those contexts, generate URLs based off those contexts, and auto-magically call the view required based on the context and the requested resource path.

So one of my first experiments with Pyramid was to implement proper resource urls for contexts in a RESTful fashion. Eventually I plan to do this for the entire collection as well, but for now all I need is the context level RESTful interface. The goal of which is to have URLs that go something like this.

• /resource/id (GET) - default view of the resource
• /resource/id/edit (GET) - the form that allows you to edit the resource
• /resource/id/create (GET) - the form that allows you to edit the resource
• /resource/id (PUT) - updates
• /resource/id (POST) - create
• /resource/id (DELETE) - delete

This ends up being pretty damn simple with Pyramid and Traversal and for those of you new to traversal or even those who aren't, I highly recommend reading the Much Ado About Traversal chapter in the Pyramid documentation. Also on a side note all of the snippets from this post are part of a real project called Stockpot and the code is freely available via SourceForge.

My Root

So first step for me was to design my Root object. This is the really the foundation for traversal and determines what resources it will be able to find and how to interact with them once it finds them. My Root object is simple and looks like this.

def _owned(obj, name, parent):
    obj.__name__ = name
    obj.__parent__ = parent
    return obj

class Root(dict):
    __name__ = None
    __parent__ = None
    #
    def __init__(self, request):
        dict.__init__(self)
        self.request = request
        self['user'] = _owned(User, 'user', self)

This is pretty straightforward. We create a user entry point for the first call to getitem and return the User model with a name of user and the Root object as the parent.

My Model

For my Root object to really do anything useful our model class needs to do some work so that when the traversal algorithm calls getitem on our User model it actually gets something useful back. I've done this using a base class for my declarative_base call.

class StockpotBase(object):
    @classmethod
    def __getitem__(cls, k):
        try:
            result =  DBSession().query(cls).filter_by(id=k).one()
            result.__parent__ = result
            result.__name__ = str(k)
            return result
        except NoResultFound, e:
            raise KeyError
    @classmethod
    def __len__(cls):
        return DBSession().query(cls).count()    
    @classmethod
    def __iter__(cls):
        return (x for x in DBSession().query(cls))

Base = declarative_base(cls=StockpotBase)

class User(Base):
    __tablename__ = 'users'
    __name__ = 'user'
    #
    def __init__(self, email, password=None, display_name=None):
        self.email = email
        self.password = password
        self.display_name = display_name
    #
    id = Column(Integer, primary_key=True)
    email = Column(String, nullable=False, unique=True)
    password = Column(String, nullable=True)
    display_name = Column(String, nullable=True)
    user_groups = relation(Group, backref='user', secondary=groups)
    groups = association_proxy('user_groups', 'name', creator=Group.group_creator)
    recipes = relation(Recipe, backref='user')
    #
    def __str__(self):
        return 'User(id={0}, email={1}, groups={2})'.format(self.id, self.email, self.groups)

def __repr__(self):
        return self.__str__()

So that is a pretty big chunk of code so let me go through what is happening, it is rather simple. I've created StockpotBase which has the methods our traversal algorithm is going to want. I've used that as the cls for my declarative_base call so that any class that I create that inherits from Base will have all of the proper methods needed.

The getitem itself ensures that the parent is set to the generic user class and the name of the class is set to the primary key. This is important later when we start using resource_url() to generate links for us in our templates, if you consider that the urls will be generated with the pattern of /parent.name/context.name

My Views

With the Root object setup and our model "traversal enabled", we can look at how the views for this will be setup. I personally like to use the config.scan('stockpot.views') helper and use the @view_config decorator for my views. I find it cleaner and easier to to have the view_config right with the actually def.

# RESOURCE_URL = /user/id
@view_config(context=User, renderer='user/view.mako')
def get(request):
    return dict(user=request.context)

# RESOURCE_URL = /user/id/edit
@view_config(name='edit', context=User, renderer='user/edit.mako')
def edit(request):
    return dict(user=request.context)

So here is the default GET view. It allows anyone to use this view, but I will have a blog post about permissions with ACL and traversal later, and it uses the renderer of my user/view.mako template. Then we have the edit view which requires User:edit permissions and uses the edit.mako template. Pretty simple. Next we have the first of the JSON views (they don't have to be JSON).

@view_config(context=User, request_method='PUT', xhr=True, renderer='json')
def put(request):
    user = request.context
    return dict(method='PUT', user_id=user.id, email=user.email)

And the mako template jQuery for this might look something like this

$$code(lang=javascript, linenums=True) $(document).ready(function() { $('#put').click(function() { $.ajax({ url: '${request.resource_url(user)}', type: 'PUT', context: document.body, dataType: 'json', success: function(data) { console.log(data); alert('done'); } }); }); });

And that is it. You would repeat the same view pattern for request_method POST and request_method DELETE and you would have RESTful API in to your resources/models in a very clean fashion.

What Happens

When a user visits the resource url a simple series of calls to getitem happens. The Root (/) object is called with 'user'. A User object with the name of 'user' and the parent of Root is returned. The User class has it's getitem called and uses the DBSession to lookup a user based on the key given. For example /user/1 (Root / User / k) would result in '1' being passed to the user objects getitem as the key. If it locates the user, it returns the instance and sets the name and parent. If you don't set the name when you call resource_url with the context, the generated URL would look read /user instead of /user/1.

There is nothing after the 1 so it looks for a generic unnamed view that handles the User context. In our case, our get method. When you add on edit, /user/1/edit it works in the same fashion, but when it tries to call getitem a second time on the User instance it will throw a key error which tells Pyramid that I am looking for a view named edit with the context of User. This traversal works the same way for the JSON calls as well.

Feedback

I don't like the fact that there are extra DB calls here, but it is a trade off. Even the /user/1/edit has to make two database calls to get the KeyError and review the proper view, but as a side-effect I can do something like /user/1/collection/1 and get the specific item of the collection owned by the user. That extends to edits as well ... /user/1/collection/1/edit. Overall I like how this pattern has evolved in my application, but would appreciate any feedback or suggested improvements to what I've done so far.