Reusable App Conventions

A Story

A good case of where I really began to question myself was during the development of django-categories. I started the project a little over a year ago. This was literally just before Jonathan Buchanan started to take some ideas on the Django wiki and dump them into what we now know as django-mptt. At the time I was just learning about MPTT and how it can benefit me in storing trees in a relational database. I was tasked with the need to create categories at work so it felt like the right thing to use.

I started to write django-categories in a reusable way. I used a parent foreign key to deal with the hierarchy. It quickly became apparent that the data set I had was a bit too large for some of queries I was doing using a simple parent foreign key. I started to re-work django-categories to include the denormalization that MPTT provides. Right then django-mptt came out. I was simply attonished by how well implemented it was. It stayed out of your way.

At this point I had two choices. One, use django-mptt having a dependancy on another reusable app. Two, continue on having on my own implementation of MPTT that was really lacking. I can't say for sure that this is a case of doing more than one thing, but it certainly broad sided me (in a good way) in understanding where lines can be drawn.

I ultimately just closed the project due to my particular use case and pointed people to django-mptt. However, recently I have come across a few cases where having an app that provided a Category model, a URLconf, views and some feeds around generically relating objects to a tree is a good idea. I have since reopened the project and moving forward with it.

Drawing the lines

The case I show above was specific to my needs, these things need to be thought of on your own. If you are working on a project using Django what is out there? Does it do what I need? It is always best to just start looking.

You may already have reasons for not making an app resuable. In the Pinax project we have a few of those cases. We have three levels of apps.

Models

Models are the foundation around accessing your data in your database. Django will create you a models.py file for you. This is where models go.

One thing that some people don't know is models can be seperated out. If you make a models module (a models directory with an __init__.py in it) you can create many other Python modules with models that belong to that app. You must specify the app name in app_label of the Meta class in all the models for this to work. I typically recommend against this. The first reason is because of the idea behind a resuable app I discussed above. If you have this many models in one app, you doing something wrong. Another issue is you begin to have too many interdepent models that end up causing circular imports.

Forms

Forms are commonly placed in a forms.py module. This includes regular forms and model forms. Putting model forms in your models.py is just the wrong placement. They are just Python classes that could live anywhere though, but that would defeat the purpose of this article.

Admin Inteface

The admin interface is not enabled by default. However, many people use it. It went through a complete refactor during its newforms-admin days. Originally the only place where you specified the admin bits was in your models. NFA fixed that by requiring you to put the new ModelAdmin declarations in an admin.py module.

The admin app comes with a handy function that will properly import all of your admin.py modules for you. It is called autodiscover. I have gone into depth about this in my newforms-admin migration post.

Views

Views are what deal with the request once it is routed. Django provides you with a views.py module where you have your view functions. One thing to note is that these are simply callables. What I mean in the general sense is that you are not tied to using a Python function. One thing that the admin does is it uses a class that represents many methods (aka views) that deal with the HttpRequest. This is commonly refered to as class-based views. Here is a quick example:

class MyView(object):
    def __call__(self, request):
        return HttpResponse(self.get_text())

    def get_text(self):
        return "hello world"

The above is a horrible view, but a good example. In a resuable app you can easily provide overridable behavior for users of the views. There is proposal going around in the Django world about using this approach for generic views. I am personally a big +1 to that idea. It really stemmed out of the many use cases we saw during the newforms-admin period. Views would become their own classes where they can inherit base functionality and everything is overriable.

Templates

This deserves its own post. I have one in the works about I how feel in this area and what is acceptable in a reusable app.

Template tags

Template tags are awesome. They already have a pretty well established convention due to the fact its structure is well defined:

my_super_sweet_app/
    __init__.py
    models.py
    templatetags/
        __init__.py
        my_super_sweet_app_tags.py

my_super_sweet_app/templatetags/my_super_sweet_app_tags.py is where you define your template tags. Be it inclusion tags, filters, custom tags, etc...

One thing that I have not seen addressed well enough is custom template tag syntax. There is sort of convention, but nothing very well established. Let me describe how I typically handle this:

{% images_for_object [obj] as [varname] %}

The structure is that you pluralize what the model is. In this case I have an Image model and it contains a generic foreign key. This template tag takes in an object and then builds a new context variable for you containing the data you are looking for.

The convention I am trying to establish is that template tags read nicely. The above tag uses the word 'as' to indicate that the left hand side is going to be stored in its right hand right. There are other cases where other keywords can be used to show how a template tag works:

{% latest_flights 5 for profile.user as flights %}

In the tag above we are grabbing 5 latest flights for a given user and storing them in the context variable flights. I am not saying we can make a good convention around every template tag there is, but certainly I wanted to bring it up so you too can think about how this might be good in some places of your own template tags.