The Ideal Django Project Structures

In this event loop on {{ PLP }}, I will be discussing what could be the ideal project folder structures in Django based on my experience as a Django web developer.

What could be the default Django project structures and I would love to share it with you the experience that I have so that I can help you ease out your burden in learning Django and Python in building your future web-based applications.

Introduction

I would like you to prepare yourself in this topic as this is the vital information that you’ve to learn and follow these guidelines that I share it with you and mold you to be a successful Django web developer someday.

The Django default project structures is a basic folder structure they’ve provided for us but there is no right or wrong on how you’re dealing with your own project structures.

In fact, I would give you the principle of structuring your common application that would become reusable within your multiple projects in Django and that’s what the micro-services comes into play.

The Default Django Project Structures

Great!, now I would like you to follow this steps and execute the following commands that Django provided for us to create your first Django project that would be easier for you and gives us the default folder structures including some of the Python files as well.  So, let’s do this!

First of all, we will access our web console to write a command, just in case you missed out on how to access your web console using “Lish Console“, just do a quick check on that previous event loop.  All right, let’s get started on this.

Step 1:  Execute Django Command

1
root@localhost:~# django-admin startproject dev

As you can see, this is the Django command line on creating a new Django project.  The command “django-admin startproject” is the Django command line utility and at the end part which is on our example is the “dev” that serves as our main project folder.

That Django would deploy all the default Django project folder structure and “.py” which is the Python file extension as well.

1
2
3
4
5
6
7
dev/
    manage.py
    dev/
        __init__.py
        settings.py
        urls.py
        wsgi.py

The “dev” main folder is just a container of your project but you can rename it if you want and it doesn’t matter to Django.

But I recommend not to rename to the other names, just leave it like that, the second “dev” folder name is the actual Python package folder where all your root project folders or app folder name resides.

As well as the required Python files exists and it’s a mandatory that you don’t rename it nor delete this files as these are all the essential information of your Django project.

What’s the Use of this default Python files inside the second “dev” folder?

These files are very useful for your web-based application to run properly.

1.  manage.py

It’s a command line utility in each Django powered site, don’t relocate nor delete nor rename this file.  For more details about this manage.py on django-admin and manage.py official documentation.

2.  dev/__init.py__

This is to tell the Python interpreter that this second folder called “dev” must consider a Python package folder that must be served by our web server.

So, based on my experience, this is just an empty file, but if this __init.py__ is missing in your folders or subfolders the containing files inside that folder won’t be executed.  So please be careful with this file. 

3.  dev/settings.py

Where Django store all the configurations like the database connection, constant variables, server location and many more.  But, be careful in changing the default Django settings as stated on their documentation.

4.  dev/urls.py

The residence of all your urls directory of your Django project anything that you want to link like for example the “contact page“, “home page“, or any internally used links, etc.  Check out more about the URL Dispatcher documentation.

5.  dev/wsgi.py

This is the default gateway of serving Django powered sites to the web server, but we will not be using this throughout the entire application that we’re about to develop, so, don’t delete this file.

We will be adding asgi.py” file which I’ll explain to you later on.

6.  dev/requirements.txt

Lastly, the requirements.txt consists of all installed Python libraries and Django specific third-party apps that you’re using for your Django project.  This is a good practice that you always follow so that you can keep track of your installed dependencies.

1
2
3
Django
mysqlclient
channels

The example shows that your requirement for the listed dependencies must install the latest versions. However, those installers that need to be installed at the system level, meaning, using sudo apt get <package> must not be listed from the requirements.txt file, otherwise, it won’t proceed with rest of the installations. Please make it as separate notes on your own about the other dependencies that require sudo level.

1
2
3
Django>=2.1.4
mysqlclient
channels==2.0.1

However, you can supply the specific version by providing the >= or == with the correct version of the Python library or the Django third-party apps.

1
2
pip3 install -r requirements.txt  # to install all the dependencies
pip3 freeze > requirements.txt  # to list down all the dependencies

Indeed, the requirements.txt is having a big impact in organizing our Django project structure.

Step 2:  Access your FileZilla

After successful execution of the command, the default Django project files would look like the above illustration, Now in your FileZilla access, you can see that the actual files are there being deployed already.

So, let’s take a look at the actual screenshot below.

Download the Default Deployed Django Files

I would like you to download this files to your local development PC for us to work on locally to start the coding works and then deploy the modified files to our development cloud web server for thorough testing.

So, basically, I really like to do this kind of working environment as I can be able to work anywhere using the internet and upload my files using the FileZilla.

Why these Django Files must reside inside the “root” directory or something like “home/project“?

Because, this is the safest directory from any Linux systems, as this location is not publicly accessible by any other unauthorized users.

Your entire Django project folder will only be residing at the safest place rather than display at “var/www/public_html” or similar publicly accessible folder from your web server.

Step 3:  Create new sub-folder name “myroot” that serves as our main app.

The “myroot” folder is our main app directory for our web-based application, you can rename this main app folder to your own liking but I preferred this name to distinguish the main app folder for our Django powered site.

Creating a project name or subfolder name in Django must not use the common namespace that used by Django itself like the “django” or “test” as the folder name, so, please avoid those common naming conventions.

What’s the folder structures for the Main App folder?

As you can see, I gave you personally my own style of structural design for better micro-services ready layout for your Django powered web application.

The purpose of this “myroot” folder as your primary main app in Django that serves all the functional callable functions, common constant variables, and your app global configurations.

That would be available and ready anytime you want to serve and call these necessary configurations you need from your various multiple apps inside your Django web application.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
dev/
  manage.py
  dev/
    __init__.py
    settings.py
    urls.py
    wsgi.py

  myroot
    __init__.py
    forms
      __init__.py
      forms.py

    migrations
      __init__.py

    templates
      myroot
        __init__.py
        account
          login.html
          change_password.html
         
        registration
          register.html

        index.html

    templatetags
      __init__.py
      myroot_extras.py

    views
      __init__.py
      vmain.py

  __init__.py
  admin.py
  apps.py
  common.py
  globalconfig.py
  models.py
  requirements.txt

The “myroot” main app layout storage information.

Did you notice that the “__init__.py” it’s actually a Python file, although it’s empty, but, it must exist in every folder containing “.py” file extension.

Without this __ini__.py file, it won’t execute any “.py” Python code that we need to execute inside our Django web application.  So, again, be aware of this important file.

Inside the “myroot” main app details

The main subfolders inside the “myroot” consist of the following subfolders.

1.  form

If you ask for user inputs from one of your web pages, you probably have “forms.py” file inside of the “form” subfolder.

All of your new form class creations will be there only.  See the official documentation about working with Django forms

2.  migrations

This folder will store all the database schema that the Django migration command utility will be automatically generated and regenerated from Django models if you create a new table or modify the existing table from your database. 

Take note that this folder is present in every app in Django powered site.  See the official documentation about the Django migrations.

3.  templates

The “templates” folder will keep all your “.html” files and a bloodline for our Django powered site to display anything to the web browser.

Place the “__init__.py” at the parent folder name called “templates“, and the rest of the subfolders.  No need for you to include it as these files is not the “.py” file type. 

Please take a look at more information about the Django templates.  I added the common folders like “account” and “registration” as later part we will be using this when we start the default Django Authentication System.

4.  templatetags

This is in relation to the Django templates that we’re having some of our custom functions to be called inside the “.html” file for further processing from our web application.

You must include the “__init__.py” file inside of this folder and the “myroot_extras.py” file as well where all of your custom functions that need to be called from your “.html” file, in short, this is called a Django template and load it each time you need it from your template.

By the way, keep that in mind to load that “myroot_extras.py” or whatever file name you’ve into your template before you can use any of your custom functions from that file.

See the Django docs about Custom template tags and filters.  Definitely, I’ll be further discussing this topic when we start our web development with Django and Python.

5.  views

In short, this is where you create your Python functions to accept web request and send a response to the requesting user either an HTML response, ajax response, XML or almost anything.  See more details about writing your views

I purposely create this “views” folder to organize the multiple functions and separate with different file names, for now, I created the “vmain.py” as the main views.

But you can add more files if your web app is bigger enough so better split your views into other views file.

Other Python codes inside the parent “myroot” app folder.

Inside the parent folder “myroot“, there are Python files “.py” from the list below.  Because these are the fundamental Python codes that must reside from the main app.

1.  admin.py

This “admin.py” is most likely present in each of your app that needs to manage your back-end database.

This is a very powerful back-end management system that Django provided for us.  The interface and the functionality will be automatically created based on your models.

Please don’t rename this file to any other names because Django automatically runs whatever configurations you may have it there mainly for the back-end database management system.

2.  apps.py

For us to make our Django app to be reusable or pluggable from various Django web applications we have, add this file to each of your app folder

But don’t rename this file as this is a built-in naming convention from Django and it will be automatically look the Django app name and integrates the rest of your applications. See the official documentation about the “Applications” from Django.

3.  common.py

I’m using this “common.py” to group in one place our custom functions specific needs.  So, this file is not mandatory for you to add but it’s good to have when you need to organize your built-in functions.

4.  global_config.py

The purpose of this file is to serve our most commonly use constant variables that come from settings.py mainly for the templates use or commonly used configurations that stored from your database, like for example your site name constant variable or anything that globally called that you want to display to your “.html” file or in Django technical term as the template.

5.  models.py

The collections of your table definitions, you can check more information about Models and Databases from our previous lessons. So, please don’t rename this file as this is the naming convention that Django uses to store all your database schemas and use this information during database migrations.  By the way, you can also check about the specific Django model documentation.

Now, what could be the Ideal Structure for your Re-usable App in Django?

This is the most ideal structure to make our Django app be a reusable app, in short, make our app pluggable to any of our Django powered sites because personally I practice this for all of my Django projects.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
  comments
    __init__.py
    migrations
      __init__.py

    templates
      comments
        __init__.py
        index.html

    templatetags
      __init__.py
      comments_extras.py

  __init__.py
  admin.py
  apps.py
  common.py
  forms.py
  models.py
  tasks.py
  urls.py
  views.py

So, in this case, I’ve created a new Django app called “comments” as an example and make this app as a pluggable, because according to our ideal layout design, we will be heading towards building a micro-service type of projects, meaning as I’ve said earlier, to make our app a pluggable in our various web-based applications so that we will not be doing all over again once we’ve done a certain common app for our Django projects.

Inside the “comments” reusable app details

I will not be elaborating more about the other Python files and folders as I’ve already mentioned earlier on this topic, and hopefully, it’s a self- explanatory so I’ll be brief about some of the new file like the “tasks.py“.

What is this tasks.py use for?

We only use this for the celery scheduled tasks or an ad-hoc type of tasks in Django to execute our codes into asynchronous way in getting a response from our web server.

This means that this type of request is a non-blocking execution of your codes without delay from other pending requests of your code that needs to be executed as well.

So, for example, in your web-based app, basically when the user submits a comment to a certain post from other users of your site, what the comment system will do is to notify the author of that post to automatically submit a pre-configured email to the author, saying that “Hey, John, you’ve some reaction from David about your post title:  blah blah kind of thing“.

Based on my experienced about the Asynchronous code execution using Celery tasks

Asynchronous is far way better than the native Synchronous counterparts to execute our codes.  We get back to our email example earlier is that it takes time really, about 10 secs or more to execute the email notifications script without using Celery tasks which is the Asynchronous way.

And because of that delay in the execution, what the Synchronous way will do is to block the other requests not to execute until the first one will finish first and the rest will be then executed.

But for the Asynchronous, it will keep receiving new multiple requests at the same time execute it without blocking the other requests.  This is where the Celery tasks are design for us to make our application to be faster and without delays to the user part.

What is this Message Broker server?

In Celery tasks, the request will be queued to the message broker called the redis or rabbitmq server depending on what message broker you’ll be selecting but I recommend to use Redis server for our message broker queuing system.

Don’t worry, I’ll be discussing the message broker later when we touch the detailed programming using the Redis server.

In the next event loop on {{ PLP }}.

Great!, now you know how to structure your Django project with micro-services design.

Up next, we will now be doing the actual and practical examples on displaying the basic hello world display in the HTML page using Django powered site.  Are you getting excited? Stay tuned for more!

See you in the next event loop on “Hello World” using Django Template.

That’s all, have fun learning with {{ PLP }}.

To help Filipino students to learn Python programming language with Django to enhance their capabilities in developing robust web-based applications with practical and direct to the point tutorials, step-by-step with actual information that I provided for you. Leave a comment below or email me at [email protected], thank you!