Structuring Python Project Directories

Introduction to Project Directories

Developing a project in Python requires careful planning, especially when it comes to organizing the project’s directory structure. A well-structured directory is essential for keeping your code organized, maintainable, and scalable. It not only helps you understand the project’s layout but also makes it easier for others (and your future self) to navigate and contribute to the codebase effectively.

To appreciate the importance of this organization, it's helpful to understand what a directory actually is. A directory is a container used to organize files and folders on a computer in a hierarchical structure. Just as you use physical folders to keep your documents organized, the operating system uses directories to manage and locate files. Directories act like folders, helping to keep the digital workspace tidy and making it easier to navigate and find stored data.

To simplify: In programming, directories are folders in your computer.

My Preferred Project Structure

If you've been developing Django applications, you're likely familiar with Two Scoops of Django (TSD). In the book, the authors recommend creating virtual environments in a separate directory where you keep all of your environments for various Python projects, while the project source code is stored in a different directory.

While this approach works well for many, I take a slightly different path. I prefer to keep everything organized under a single root directory for each project. Inside that root directory, I have separate subdirectories: one for the project’s source code and another for the virtual environment. This way, everything related to a particular project—its code, environment, and configuration files—remains neatly contained under one top-level folder. This setup makes your project portable.

Here's how I prefer to structure the main directories for a Python project in both my local and production environments:

1
2
3

| - root_directory/
    | - source_code/
    | - virtual_environment/

Implementation of the Project Structure

Let's imagine we have a project called Gen EMR, an electronic medical record (EMR) platform with artificial intelligence capabilities developed using the Django framework. The project directory could be structured as follows:

1
2
3

| - gen_emr/
    | - gen_emr_src/
    | - gen_emr_venv/

To create the project directories on your computer, enter the following command in your terminal:

1
2
3
4

mkdir gen_emr 
cd gen_emr
mkdir gen_emr_src
mkdir gen_emr_venv

Here are descriptions for each directory in the Gen EMR project structure:

- Root directory

The root directory, named gen_emr, serves as the top-level container for the entire project. It houses the main source code and virtual environment. The root directory may live anywhere in your computer system, but just make it easy for you to find it.

- Source code directory

The gen_emr_src directory contains all the core application codes for the Gen EMR system. This includes the Django project, apps, settings, templates, and static files.

- Virtual environment directory

The gen_emr_venv directory holds the virtual environment for the project. This isolated environment contains all the Python packages and dependencies needed for the Gen EMR system.

I find this structure easier to manage because I don’t have to juggle different locations for environments and source code, and it also makes the project more portable. When sharing or moving the project to another directory or system, everything is logically grouped together.