Django project hierarchy/organization

Question

I am new to Django and starting a project, and I would like to do it the right way.

I would like to know what you think is best practice for organizing a project.

Here are some questions I have:

• How do I separate the static resources from the Python code so that I don't waste time processing the static content through Django?
• As apps are reusable modules, they are not really tight to a project, so should they be located in the project directory, or in another directory that would contain all my "homemade" apps?
• Are templates considered to be static or dynamic content?

Here is my current file hierarchy:

webapps/
    myproject/
        apache/
        bin/
        lib/
        templates/
            app1/
            app2/
        src/
            app1/
            app2/
            __init.py
            settings.py
            urls.py
            manage.py
        myproject.wsgi
    admin/
    static/
        css/
        img/

What do you think? What would be better?

Thanks!

Answer 1

Your directory structure could also depend on what version of django that you're using. If you're using django 1.3, handling static content has changed slightly. Your templates could also be arranged separately.

The following only applies for django 1.3.

Within an app directory:

...
app1/
    static/
        app1/
    templates/
        app1/
    models.py
    ...
    views.py

If you use the new django.contrib.staticfiles application, your settings may look something like this:

MEDIA_ROOT = path.join(ROOT_PATH,'uploaded_media/')
MEDIA_URL = '/uploaded_media/'
# static content is collected here, and served from here, but don't add stuff manually here! add to staticfiles_dirs
STATIC_ROOT = path.join(ROOT_PATH, 'collected_static/')
ADMIN_MEDIA_PREFIX = '/static/admin/'
STATIC_URL = '/static/'
# Additional locations of static files
STATICFILES_DIRS = (
    path.join(ROOT_PATH, 'src/extra_static/'),
)

STATICFILES_FINDERS = (
    'django.contrib.staticfiles.finders.FileSystemFinder',
    'django.contrib.staticfiles.finders.AppDirectoriesFinder',
)

Similarly, your templates can be loaded directly from an INSTALLED_APP:

TEMPLATE_LOADERS = (
    'django.template.loaders.filesystem.Loader',
    'django.template.loaders.app_directories.Loader'
)

TEMPLATE_DIRS = (
    path.join(ROOT_PATH,'src/templates/'),
)

The two strategies above mean that templates and static content can live within their specific app directories. In Development, using contrib.staticfiles, static content can be served directly from your application folders. In production, there is a management command to collect all the app directory static content to /path/to/project/collected_static/, and you can point your web server at that directory to serve static content.

For pre-packaged libraries, using virtualenv and pip is a great idea. Otherwise, I like to keep libraries in a lib directory within the project root directory. It makes referencing the source, templates, and static content extremely convenient, rather than installing to site-packages (especially when not using virtualenv).

So, re-arranging your project structure:

webapps/
    myproject/
        apache/
        bin/
        lib/
        collected_static/
        uploaded_media/
        myproject.wsgi
        src/
            templates/ # lib template overrides and site wide templates
                base.html
                lib_1/
                    nav.html
            extra_static/
                lib_1/ # libs that dont support django 1.3 static
                    js/
                    css/
            settings.py
            settingslocal.py # keep developer specific settings here
            urls.py
            manage.py
            app1/
                __init.py
                static/
                    app1/
                        js/
                        css/
                templates/
                    app1/