Herberth's blog

Just another software engineer

A New Template for Django Projects

Since Django 1.4 it is possible to use project templates. This means that you can start off your Django project with a different project structure, which also means that you can avoid some initial configuration hassle.

Django follows Python’s principle of “explicit is better than implicit”. And this is the justification I’ve got when I asked why Django does not have some configurations done by default. I think “convention over configuration” is not necessarily “explicit is better than implicit”’s enemy. Both can live together as long you keep the configurations explicit.

Thinking about that I’ve decided to write a project template which eliminates some of the Django’s annoyances when starting a project, mainly related to paths (templates, media and static). This is specially useful for newcomers so they don’t lose a lot of time configuring the project.

Show me it working!

You can start off a project using this template like this:

$ django-admin.py startproject myproject \
  --template=https://github.com/herberthamaral/django_project_template/archive/master.zip
$ cd myproject
$ python manage.py runserver

At this point you can point out your browser to http://localhost:8000 and you can see Django’s initial page. But, if you point it to http://localhost:8000/static/readme.txt, you can also see the static folder’s configuration working. The same for the media folder: http://localhost:8000/media/readme.txt.

The template path is also configured. And there is a example template located in myproject/templates/index.html. Yup, it is the initial Django’s template, slightly modified.

Limitations and workarounds

Not everything is a sea of roses, though:

  • Django does not offer a way to change the project folder name. For that reason, I’ve been forced to add a custom code in manage.py in order to change this folder name to match the application name.
  • There is some extra code in urls.py too.

Final words

I hope this can solve some problems for newcomers willing to learn Django. Please contact me if you find a bug or if you have a suggestion.