Python: Django Rest Framework (Part 1)

Introduction

This post is for people who are interested in why certain patterns are used by developers when choosing Python as a backend language and also need a quick and clear set of instructions on how to set up a Django backend as an API. Since set up can often be an achilles heel for newer programmers, owing how little of our time is actually spent on set up as opposed to coding (and debugging), I decided to save people some heartache and headaches.

In my case, I will be using a certain set of tools. First, I will use VS Code as my text editor/IDE. Honestly, VS Code is a fantastic tool which provides a host of extensions which make programming even easier. Second, I will be using a mac computer which means that Terminal commands will be Unix-based. Lastly, I am using Python 3.7 for this demo so please make sure that you are running the same version of Python (or at least newer than Python 3.4).

Create your file structure

This section depends largely on personal preference but I would like to propose a simple and elegant file structure. First, create a directory for your project that will house both your frontend and backend applications. Then, move into that directory in order to create the aforementioned subdirectories.

mkdir my-new-project && cd my-new-project

Since this first blog post is focused primarily on settings up Django as an API in the backend only, I will only provide instructions for server side set up in this post. So in the case of the backend, I recommend creating the directory and adopting a ‘project-name-server’ naming convention. Functionally, it makes no difference whatsoever how these folders are named, but it is nice to pick certain, easy-to-remember patterns and stick to them. Furthermore, it is a robust convention if you decide to make multiple clients for the API, such as a web client and a mobile client. All of these directories could easily be identified as belonging to one project but the specific roles of each application would be easily discerned. Finally, navigate into the backend folder in order to continue the set up process.

mkdir my-new-project-server && cd my-new-project-server

Virtual Environment

Upon the release of Python 3.3, the venv module has become the defacto way to create a virtual environment for running Python apps. Furthermore it is included in the Python library which makes installation a breeze and using pip for sourcing packages equally as simple.

Virtual environments are officially recommended by the Python documentation because they allow developers to manage library dependencies on a per project basis. Therefore, packages are installed within a particular context instead of globally, reducing the possibility of conflicts with other system tools. Even though, it could seem off putting to developers with backgrounds in other languages, this additional step is quick and painless.

If you are on mac OS or linux just run the code below in your terminal within the directory that will run your backend Django application:

python3 -m pip install --user --upgrade pip

Since creating a virtual environment in order to isolate package installations is a best practice, we should create the env file in the backend folder for the project. After updating pip, run the following command in the terminal:

python3 -m venv env

This command will produce an env file within the current folder, so it is important to make sure that run this script in the appropriate folder. The -m flag allows a user to run modules from the Python library as scripts. Therefore, we are commanding Python to create a virtual environment in an env folder, by using the venv module and passing it env as an argument. Functionally, the env file is similar to a Gemfile or a Package file customary in Ruby or Javascript apps, respectively. However, the Python documentation suggests that the env file should be exclude from version control systems, such as Git, by including it in the .gitignore file, unlike the previous two examples.

An additional step in the Python-as-a-backend workflow requires developers to activate and deactivate the virtual environment prior to and after each programming session. Once again, this step is simple and detailed below. In order to active your virtual environment execute the following command in the terminal within the corresponding backend folder:

source env/bin/activate

Activating the virtual environment changes the shell’s PATH, which is how the packages can be isolated from the rest of the system. Prior to running the activation command, try running:

which python3

Next, activate the virtual environment and run the previous script again. See the difference?

The location of the Python interpreter should point to a path which includes the env directory. While the virtual environment is activated, pip will install packages into this environment file. Consequently, it is just as important to build the muscle memory to deactivate the environment as it is to activate it. Deactivation is just another, simple command which is shown below:

deactivate

While in the virtual environment, packages can be installed by using ‘pip install’ in the terminal. In order to continue with the set up process, we will install the django and djangorestframework dependencies as follows:

pip install django djangorestframework

Select your interpreter: Two roads diverged

As mentioned in the introduction, this blog post is provides a step-by-step breakdown for setting up a Django backend as an API in VS Code. One of the many benefits to working in VS Code is that it allows users to configure their python environments per project. Therefore, developers should configure their VS Code in accordance with the corresponding Python version. If a developer has a project which uses Python 2.x and another using Python 3.x, VS Code can distinguish between which executable to run by accessing a special settings.json file, which should live in the Django project directory.

There are at least two ways to configure your Python environment in VS Code. The first is by using the Command Palette found in the View menu and selecting the Python interpreter path which points at the Python executable found in the ‘my-new-project-server/env/bin’ path.

The second way is by setting it up manually. First, navigate to the Django project level directory and create a .vscode folder. This new folder should occupy the same level as the env file.

mkdir .vscode && cd .vscode

Next, create the settings.json file inside of the .vscode folder.

touch settings.json

Lastly, create a json object within the settings.json file with a key/value pair that sets the path for the interpreter through the virtual environment. In this case, we can use “python.pythonPath” as the key and “my-new-project-server/env/bin/python”. Remember that the object will be in JSON so wrap the key and value in quotes.

# ./my-new-project/.vscode/settings.json
{
"python.pythonPath": "${workspaceFolder}/env/bin/python"
}

Additional Settings

While the following is not required, the blog post “DJANGO PROJECTS IN VISUAL STUDIO CODE” by AutomationPanda, makes the helpful suggestion to install a few additional packages. According to the post, linting and formatting can be automated and simplified with the packages below by simply activating the virtual environment and running pip:

pip install pep8 autopep8 pylint

After successfully installing the packages, include the following key-value pairs in the settings.json file:

# ./my-new-project/.vscode/settings.json
{ 
   "python.pythonPath": "${workspaceFolder}/env/bin/python",
   "editor.formatOnSave": true,
   "python.linting.pep8Enabled": true,
   "python.linting.pylintPath": "/path/to/pylint",
   "python.linting.pylintArgs": [
      "--load-plugins",
      "pylint_django"
   ],
   "python.venvPath": "${workspaceFolder}/env/bin/python",
   "python.linting.pylintEnabled": true
}

Conclusion

Ultimately, my hope is that this blog post can provide newer developers with context surrounding the why’s of Django (and Python) as an API (and backend language), and to clarify the how’s by producing a simple, step-by-step process to follow. In the next section, I hope to cover the initializing the Django app, creating models and migrations, and setting up Postgresql as a database.

Resources

Installing packages using pip and virtual environments - Python Packaging User Guide

Django Projects in Visual Studio Code