Creating a virtual environment project file structure

A consistent file structure for your projects makes you well organized and more productive. When you have the basic workflow defined, you can get in the business logic more quickly and create awesome projects.

Getting ready

If you haven't done this yet, create a virtualenvs directory, where you will keep all your virtual environments (read about this in the Working with a virtual environment recipe). This can be created under your home directory.

Then, create a directory for your project's environment, for example, myproject_env. Start the virtual environment in it. We would suggest adding a commands directory for local shell scripts that are related to the project, a db_backups directory for database dumps, and a project directory for your Django project. Also, install Django in your virtual environment if you haven't already done so.

How to do it...

Follow these steps in order to create a file structure for your project:

1. With the virtual environment activated, go to the project directory and start a new Django project as follows:

(myproject_env)$ django-admin.py startproject myproject

For clarity, we will rename the newly created directory django-myproject. This is the directory that you will put under version control, therefore, it will have .git, .svn, or similar subdirectories.

2. In the django-myproject directory, create a README.md file to describe your project to the new developers. You can also put the pip requirements with the Django version and include other external dependencies (read about this in the Handling project dependencies with pip recipe).
3. The django-myproject directory will also contain the following:
   • Your project's Python package, named myproject
   • Django apps (we recommend having an app called utils for different functionalities that are shared throughout the project)
   • A locale directory for your project translations if it is multilingual
   • The externals directory for external dependencies that are included in this project if you decide not to use pip requirements

4. In your project's root, django-myproject. Create the following:
   • A media directory for project uploads
   • A site_static directory for project-specific static files
   • A static directory for collected static files
   • A tmp directory for the upload procedure
   • A templates directory for project templates
5. The myproject directory should contain your project settings in settings.py and a config directory (read about this in the Configuring settings for development, testing, staging, and production environments recipe), as well as the urls.py URL configuration.
6. In your site_static directory, create the site directory as a namespace for site-specific static files. Then, we will divide the static files between categorized subdirectories in it. For instance, see the following:
   • scss for Sass files (optional)
   • css for the generated minified Cascading Style Sheets (CSS)
   • img for styling images and logos
   • js for JavaScript and any third-party module combining all types of files, such as the TinyMCE rich-text editor
7. Besides the site directory, the site_static directory might also contain overwritten static directories of third-party apps, for example, cms overwriting static files from Django CMS. To generate the CSS files from Sass and minify the JavaScript files, you can use the CodeKit or Prepros applications with a graphical user interface.
8. Put your templates that are separated by the apps in your templates directory. If a template file represents a page (for example, change_item.html or item_list.html), then put it directly in the app's template directory. If the template is included in another template (for example, similar_items.html), put it in the includes subdirectory. Also, your templates directory can contain a directory called utils for globally reusable snippets, such as pagination and language chooser.

How it works...

The whole file structure for a complete project in a virtual environment will look similar to the following:

myproject_env/
├── bin/
├── commands/
├── db_backups/
├── include/
├── lib/
└── project/
    └── django-myproject/
        ├── externals/
        │   ├── apps/
        │   └── libs/
        ├── locale/
        ├── media/
        ├── myapp1/
        ├── myapp2/
        ├── myproject/
        │   ├── config/
        │   │   ├── __init__.py
        │   │   ├── base.py
        │   │   ├── dev.py
        │   │   ├── prod.py
        │   │   ├── staging.py
        │   │   └── test.py
        │   ├── tmp/
        │   ├── __init__.py
        │   ├── settings.py
        │   ├── settings.py.example
        │   ├── urls.py
        │   └── wsgi.py
        ├── requirements/
        │   ├── dev.txt
        │   ├── prod.txt
        │   ├── staging.txt
        │   └── test.txt
        ├── site_static/
        │   └── site/
        │       ├── css/
        │       ├── img/
        │       └── js/
        ├── static/
        ├── templates/
        │   ├── admin/
        │   ├── myapp1/
        │   │   └── includes/
        │   └── myapp2/
        │       └── includes/
        ├── utils/
        │   ├── __init__.py
        │   └── misc.py
        ├── README.md
        ├── fabfile.py
        └── manage.py*

See also

• The Handling project dependencies with pip recipe
• The Including external dependencies in your project recipe
• The Configuring settings for development, testing, staging, and production environments recipe
• The Deploying on Apache with mod_wsgi recipe in Chapter 12, Testing and Deployment