Project design / FS layout for large django projects

Question

What is the best way to layout a large django project? The tutuorials provide simple instructions for setting up apps, models, and views, but there is less information about how apps and projects should be broken down, how much sharing is allowable/necessary between apps in a typical project (obviously that is largely dependent on the project) and how/where general templates should be kept.

Does anyone have examples, suggestions, and explanations as to why a certain project layout is better than another? I am particularly interested in the incorporation of large numbers of unit tests (2-5x the size of the actual code base) and string externalization / templates.

Answer 1

This page does a good job of addressing some of my questions: http://www.b-list.org/weblog/2006/sep/10/django-tips-laying-out-application/

Specifically:

1. To define custom template tags or filters, you must create a sub-directory in the application’s directory called templatetags, and it must contain a file named __init__.py so that it can be imported as a Python module.
2. To define unit tests which will automatically be noticed by Django’s testing framework, put them in a module called tests (which can be either a file named tests.py or a directory called tests). The testing framework will also find any doctests in that module, but the preferred place for those is, of course, the docstrings of the classes or functions they’re designed to test.
3. To provide custom SQL which will be executed immediately after your application is installed, create a sub-directory called sql inside the application’s directory; the file names should be the same as the names of the models whose tables they’ll operate on; for example, if you have an app named weblog containing a model named Entry, then the file sql/entry.sql inside the app’s directory can be used to modify or insert data into the entries table as soon as it’s been created.

The note about tests.py and tests (the directory) also holds for models, which helps address the problem of having way to many tests (or models) for one file.

I would still like to see some examples / suggestions for app/project break down, and big django sites that work well.

Answer 2

The major guidelines are similar to any other large code project. Apps should address a single, clearly-defined responsibility. The name "application" is a misnomer; Django apps should be thought of more as reusable components which can be plugged together to create a real application. Tests for each app should be contained within that app. Apps should be decoupled from each other as much as possible, but clearly there will be dependencies, so the goal should be to keep the dependency graph as simple and sane as possible.

I prefer to keep all the templates for a project under a single project-wide templates directory, with a subdirectory for each app (using a template subdirectory for each app is a very strong convention in Django, as it avoids template name collisions between apps). The reason for a single project-wide templates directory is that templates, template inheritance trees, and block names can be quite project-specific, so it's hard to provide "default" app templates that can plug in to any project. There have been some attempts to settle on standard naming conventions for base site-wide templates and the blocks they define, but I haven't seen a standard emerge yet (the way they do things over at Pinax is probably the closest we have to a standard).

Re "string externalization", if you mean i18n and l10n, Django has strong support for that and standard places where it puts the .po files - check the docs.

Answer 3

The Pinax project is built around the idea of small reusable apps, which are easily brought together into a project. They've used the project Cloud 27 as a demo project.

The Django project I'm working on (called Basie. It's pre-0.1, so no link yet.) is trying to follow the Pinax model, and so far it's working out fairly well.

Answer 4

My current layout stems from me wanting to have a test-version of my sites. This means having two projects for every site, since they need different configurations, and forces me to move all the applications out of the projects.

I've created two folders: $APP_ROOT/devel and $APP_ROOT/prod. These contain all the apps. Using source control (in my case git) I have the apps in devel at the HEAD revision, while the apps in prod are locked to the PROD tag. The templates also have their own folder with the same layout as the apps.

Now I'm able to do all my development in the devel-apps folder and the matching template-folder. When I have something I'm happy with, I tag that revision and update prod.

Answer 5

I found Zachary's layout quite useful Zachary Voase’s Blog » Django Project Conventions, Revisited.