Django avoid repeat file download

Django is a high-level Python framework designed for rapid, secure, and scalable web development. Django includes rich support for URL routing, page templates, and working with data.

In this Django tutorial, you create a simple Django app with three pages that use a common base template. You create this app in the context of Visual Studio Code in order to understand how to work with Django in the VS Code terminal, editor, and debugger. This tutorial does not explore various details about Django itself, such as working with data models and creating an administrative interface. For guidance on those aspects, refer to the Django documentation links at the end of this tutorial.

The completed code project from this Django tutorial can be found on GitHub: python-sample-vscode-django-tutorial.

If you have any problems, feel free to file an issue for this tutorial in the VS Code documentation repository.

Prerequisites

To successfully complete this Django tutorial, you must do the following (which are the same steps as in the general Python tutorial):

1. Install the Python extension.

2. Install a version of Python 3 (for which this tutorial is written). Options include:

   • (All operating systems) A download from www.cronistalascolonias.com.ar; typically use the Download Python button that appears first on the page (or whatever is the latest version).
   • (Linux) The built-in Python 3 installation works well, but to install other Python packages you must run in the terminal.
   • (macOS) An installation through Homebrew on macOS using (the system install of Python on macOS is not supported).
   • (All operating systems) A download from Anaconda (for data science purposes).

3. On Windows, make sure the location of your Python interpreter is included in your PATH environment variable. You can check the location by running at the command prompt. If the Python interpreter's folder isn't included, open Windows Settings, search for "environment", select Edit environment variables for your account, then edit the Path variable to include that folder.

Create a project environment for the Django tutorial

In this section, you create a virtual environment in which Django is installed. Using a virtual environment avoids installing Django into a global Python environment and gives you exact control over the libraries used in an application. A virtual environment also makes it easy to Create a www.cronistalascolonias.com.ar file for the environment.

1. On your file system, create a project folder for this tutorial, such as .

2. In that folder, use the following command (as appropriate to your computer) to create a virtual environment named based on your current interpreter:

   Note: Use a stock Python installation when running the above commands. If you use from an Anaconda installation, you see an error because the ensurepip module isn't available, and the environment is left in an unfinished state.

3. Open the project folder in VS Code by running , or by running VS Code and using the File > Open Folder command.

4. In VS Code, open the Command Palette (View > Command Palette or (⇧⌘P (Windows, Linux Ctrl+Shift+P))). Then select the Python: Select Interpreter command:

   

5. The command presents a list of available interpreters that VS Code can locate automatically (your list will vary; if you don't see the desired interpreter, see Configuring Python environments). From the list, select the virtual environment in your project folder that starts with or :

   

6. Run Terminal: Create New Integrated Terminal (⌃⇧` (Windows, Linux Ctrl+Shift+`)) from the Command Palette, which creates a terminal and automatically activates the virtual environment by running its activation script.

   Note: On Windows, if your default terminal type is PowerShell, you may see an error that it cannot run www.cronistalascolonias.com.ar1 because running scripts is disabled on the system. The error provides a link for information on how to allow scripts. Otherwise, use Terminal: Select Default Shell to set "Command Prompt" or "Git Bash" as your default instead.

7. The selected environment appears on the left side of the VS Code status bar, and notice the "(venv)" indicator that tells you that you're using a virtual environment:

   

8. Install Django in the virtual environment by running one of the following commands in the VS Code Terminal:

You now have a self-contained environment ready for writing Django code. VS Code activates the environment automatically when you use Terminal: Create New Integrated Terminal. If you open a separate command prompt or terminal, activate the environment by running (Linux/macOS) or (Windows). You know the environment is activated when the command prompt shows (env) at the beginning.

Create and run a minimal Django app

In Django terminology, a "Django project" is composed of several site-level configuration files along with one or more "apps" that you deploy to a web host to create a full web application. A Django project can contain multiple apps, each of which typically has an independent function in the project, and the same app can be in multiple Django projects. An app, for its part, is just a Python package that follows certain conventions that Django expects.

To create a minimal Django app, then, it's necessary to first create the Django project to serve as the container for the app, then create the app itself. For both purposes, you use the Django administrative utility, , which is installed when you install the Django package.

Create the Django project

1. In the VS Code Terminal where your virtual environment is activated, run the following command:

   This command assumes (by use of at the end) that the current folder is your project folder, and creates the following within it:

   • : The Django command-line administrative utility for the project. You run administrative commands for the project using .

   • A subfolder named , which contains the following files:

     • : an empty file that tells Python that this folder is a Python package.
     • : an entry point for WSGI-compatible web servers to serve your project. You typically leave this file as-is as it provides the hooks for production web servers.
     • : contains settings for Django project, which you modify in the course of developing a web app.
     • : contains a table of contents for the Django project, which you also modify in the course of development.

2. To verify the Django project, make sure your virtual environment is activated, then start Django's development server using the command . The server runs on the default port , and you see output like the following output in the terminal window:

   When you run the server the first time, it creates a default SQLite database in the file , which is intended for development purposes but can be used in production for low-volume web apps. Also, Django's built-in web server is intended only for local development purposes. When you deploy to a web host, however, Django uses the host's web server instead. The module in the Django project takes care of hooking into the production servers.

   If you want to use a different port than the default , specify the port number on the command line, such as .

3. Ctrl+click the URL in the terminal output window to open your default browser to that address. If Django is installed correctly and the project is valid, you see the default page shown below. The VS Code terminal output window also shows the server log.

   

4. When you're done, close the browser window and stop the server in VS Code using Ctrl+C as indicated in the terminal output window.

Create a Django app

1. In the VS Code Terminal with your virtual environment activated, run the administrative utility's command in your project folder (where resides):

   The command creates a folder called that contains a number of code files and one subfolder. Of these, you frequently work with (that contains the functions that define pages in your web app) and (that contains classes defining your data objects). The folder is used by Django's administrative utility to manage database versions as discussed later in this tutorial. There are also the files (app configuration), (for creating an administrative interface), and (for tests), which are not covered here.

2. Modify to match the following code, which creates a single view for the app's home page:

3. Create a file, , with the contents below. The file is where you specify patterns to route different URLs to their appropriate views. The code below contains one route to map root URL of the app () to the function that you just added to :

4. The folder also contains a file, which is where URL routing is actually handled. Open and modify it to match the following code (you can retain the instructive comments if you like). This code pulls in the app's using , which keeps the app's routes contained within the app. This separation is helpful when a project contains multiple apps.

5. Save all modified files with ⌥⌘S (Windows Ctrl+K S, Linux ).

6. In the VS Code Terminal, again with the virtual environment activated, run the development server with and open a browser to to see a page that renders "Hello, Django".

   

Create a debugger launch profile

You're probably already wondering if there's an easier way to run the server and test the app without typing each time. Fortunately, there is! You can create a customized launch profile in VS Code, which is also used for the inevitable exercise of debugging.

1. Switch to Run view in VS Code (using the left-side activity bar). Along the top of the Run view, you may see "No Configurations" and a warning dot on the gear icon. Both indicators mean that you don't yet have a file containing debug configurations:

   

2. Select the gear icon and wait for a few seconds for VS Code to create and open a file. (If you're using an older version of VS Code, you may be prompted with a list of debugger targets, in which case select Python from the list.) The file contains a number of debugging configurations, each of which is a separate JSON object within the array.

3. Scroll down to and examine the configuration with the name "Python: Django":

   This configuration tells VS Code to run using the selected Python interpreter and the arguments in the list. Launching the VS Code debugger with this configuration, then, is the same as running in the VS Code Terminal with your activated virtual environment. (You can add a port number like to if desired.) The entry also tells VS Code to enable debugging of Django page templates, which you see later in this tutorial.

4. Save (⌘S (Windows, Linux Ctrl+S)). In the debug configuration drop-down list (which reads Python: Current File) select the Python: Django configuration:

   

5. Test the configuration by selecting the Run > Start Debugging menu command, or selecting the green Start Debugging arrow next to the list (F5):

   

6. Ctrl+click the URL in the terminal output window to open the browser and see that the app is running properly.

7. Close the browser and stop the debugger when you're finished. To stop the debugger, use the Stop toolbar button (the red square) or the Run > Stop Debugging command (⇧F5 (Windows, Linux Shift+F5)).

8. You can now use the Run > Start Debugging at any time to test the app, which also has the benefit of automatically saving all modified files.

Explore the debugger

Debugging gives you the opportunity to pause a running program on a particular line of code. When a program is paused, you can examine variables, run code in the Debug Console panel, and otherwise take advantage of the features described on Debugging. Running the debugger also automatically saves any modified files before the debugging session begins.

Before you begin: Make sure you've stopped the running app at the end of the last section by using Ctrl+C in the terminal. If you leave the app running in one terminal, it continues to own the port. As a result, when you run the app in the debugger using the same port, the original running app handles all the requests and you won't see any activity in the app being debugged and the program won't stop at breakpoints. In other words, if the debugger doesn't seem to be working, make sure that no other instance of the app is still running.

1. In , add a route to the list:

   The first argument to defines a route "hello/" that accepts a variable string called name. The string is passed to the function specified in the second argument to .

   URL routes are case-sensitive. For example, the route is distinct from . If you want the same view function to handle both, define paths for each variant.

2. Replace the contents of with the following code to define the function that you can step through in the debugger:

   The variable defined in the URL route is given as an argument to the function. As described in the code comments, always filter arbitrary user-provided information to avoid various attacks on your app. In this case, the code filters the name argument to contain only letters, which avoids injection of control characters, HTML, and so forth. (When you use templates in the next section, Django does automatic filtering and you don't need this code.)

3. Set a breakpoint at the first line of code in the function () by doing any one of the following:

   • With the cursor on that line, press F9, or,
   • With the cursor on that line, select the Run > Toggle Breakpoint menu command, or,
   • Click directly in the margin to the left of the line number (a faded red dot appears when hovering there).

   The breakpoint appears as a red dot in the left margin:

   

4. Start the debugger by selecting the Run > Start Debugging menu command, or selecting the green Start Debugging arrow next to the list (F5):

   

   Observe that the status bar changes color to indicate debugging:

   

   A debugging toolbar (shown below) also appears in VS Code containing commands in the following order: Pause (or Continue, F5), Step Over (F10), Step Into (F11), Step Out (⇧F11 (Windows, Linux Shift+F11)), Restart (⇧⌘F5 (Windows, Linux Ctrl+Shift+F5)), and Stop (⇧F5 (Windows, Linux Shift+F5)). See VS Code debugging for a description of each command.

   

5. Output appears in a "Python Debug Console" terminal. Open a browser and navigate to . Before the page renders, VS Code pauses the program at the breakpoint you set. The small yellow arrow on the breakpoint indicates that it's the next line of code to run.

   

6. Use Step Over to run the statement.

7. On the left side of the VS Code window, you see a Variables pane that shows local variables, such as , as well as arguments, such as . Below that are panes for Watch, Call Stack, and Breakpoints (see VS Code debugging for details). In the Locals section, try expanding different values. You can also double-click values (or use Enter (Windows, Linux F2)) to modify them. Changing variables such as , however, can break the program. Developers typically make changes only to correct values when the code didn't produce the right value to begin with.

   

8. When a program is paused, the Debug Console panel (which is different from the "Python Debug Console" in the Terminal panel) lets you experiment with expressions and try out bits of code using the current state of the program. For example, once you've stepped over the line , you might experiment with different date/time formats. In the editor, select the code that reads , then right-click and select Debug: Evaluate to send that code to the debug console, where it runs:

   Tip: The Debug Console also shows exceptions from within the app that may not appear in the terminal. For example, if you see a "Paused on exception" message in the Call Stack area of Run view, switch to the Debug Console to see the exception message.

9. Copy that line into the > prompt at the bottom of the debug console, and try changing the formatting:

   Note: If you see a change you like, you can copy and paste it into the editor during a debugging session. However, those changes aren't applied until you restart the debugger.

10. Step through a few more lines of code, if you'd like, then select Continue (F5) to let the program run. The browser window shows the result:

    

11. Close the browser and stop the debugger when you're finished. To stop the debugger, use the Stop toolbar button (the red square) or the Run > Stop Debugging command (⇧F5 (Windows, Linux Shift+F5)).

Tip: To make it easier to repeatedly navigate to a specific URL like , output that URL using a statement somewhere in a file like . The URL appears in the VS Code Terminal where you can use Ctrl+click to open it in a browser.

Go to Definition and Peek Definition commands

During your work with Django or any other library, you may want to examine the code in those libraries themselves. VS Code provides two convenient commands that navigate directly to the definitions of classes and other objects in any code:

• Go to Definition jumps from your code into the code that defines an object. For example, in , right-click on in the function and select Go to Definition (or use F12), which navigates to the class definition in the Django library.

• Peek Definition (⌥F12 (Windows Alt+F12, Linux Ctrl+Shift+F10), also on the right-click context menu), is similar, but displays the class definition directly in the editor (making space in the editor window to avoid obscuring any code). Press Escape to close the Peek window or use the x in the upper right corner.

  

Use a template to render a page

The app you've created so far in this tutorial generates only plain text web pages from Python code. Although it's possible to generate HTML directly in code, developers avoid such a practice because it opens the app to cross-site scripting (XSS) attacks. In the function of this tutorial, for example, one might think to format the output in code with something like , where the result in is given directly to a browser. This opening allows an attacker to place malicious HTML, including JavaScript code, in the URL that ends up in and thus ends up being run in the browser.

A much better practice is to keep HTML out of your code entirely by using templates, so that your code is concerned only with data values and not with rendering.

In Django, a template is an HTML file that contains placeholders for values that the code provides at run time. The Django templating engine then takes care of making the substitutions when rendering the page, and provides automatic escaping to prevent XSS attacks (that is, if you tried using HTML in a data value, you would see the HTML rendered only as plain text). The code, therefore, concerns itself only with data values and the template concerns itself only with markup. Django templates provide flexible options such as template inheritance, which allows you to define a base page with common markup and then build upon that base with page-specific additions.

In this section, you start by creating a single page using a template. In subsequent sections, you configure the app to serve static files and then create multiple pages to the app that each contains a nav bar from a base template. Django templates also support control flow and iteration, as you see later in this tutorial in the context of template debugging.

1. In the file, locate the list and add the following entry, which makes sure the project knows about the app so it can handle templating:

2. Inside the folder, create a folder named , and then another subfolder named to match the app name (this two-tiered folder structure is typical Django convention).

3. In the folder, create a file named with the contents below. This template contains two placeholders for data values named "name", and "date", which are delineated by pairs of curly braces, and . All other invariant text is part of the template, along with formatting markup (such as ). As you can see, template placeholders can also include formatting, the expressions after the pipe symbols, in this case using Django's built-in date filter and time filter. The code, then needs only to pass the datetime value rather than a pre-formatted string:

4. At the top of , add the following import statement:

5. Also in , modify the function to use method to load a template and to provide the template context. The context is the set of variables for use within the template. The function takes the request object, followed by the path to to the template relative to the folder, then the context object. (Developers typically name the templates the same as the functions that use them, but matching names are not required because you always refer to the exact filename in your code.)

   You can see that the code is now much simpler, and concerned only with data values, because the markup and formatting is all contained in the template.

6. Start the program (inside or outside of the debugger, using ⌃F5 (Windows, Linux Ctrl+F5)), navigate to a /hello/name URL, and observe the results.

7. Also try navigating to a /hello/name URL using a name like to see Django's automatic escaping at work. The "name" value shows up as plain text in the browser rather than as rendering an actual element.

Serve static files

Static files are pieces of content that your web app returns as-is for certain requests, such as CSS files. Serving static files requires that the list in contains , which is included by default.

Serving static files in Django is something of an art, especially when deploying to production. What's shown here is a simple approach that works with the Django development server and also a production server like gunicorn. A full treatment of static files, however, is beyond the scope of this tutorial, so for more information, see Managing static files in the Django documentation.

In production, you also need to set in , which necessitates some additional work when using containers. For details, see Issue

Ready the app for static files

1. In the project's , add the following statement:

2. In that same file, add the following line at the end, which includes standard static file URLs to the list that the project recognizes:

Refer to static files in a template

1. In the folder, create a folder named .

2. Within the folder, create a subfolder named , matching the app name.

   The reason for this extra subfolder is that when you deploy the Django project to a production server, you collect all the static files into a single folder that's then served by a dedicated static file server. The subfolder ensures that when the app's static files are collected, they're in an app-specific subfolder and won't collide with file from other apps in the same project.

3. In the folder, create a file named with the following contents. After entering this code, also observe the syntax highlighting that VS Code provides for CSS files, including a color preview.

4. In , add the following lines after the element. The tag is a custom Django template tag set, which allows you to use to refer to a file like the stylesheet.

5. Also in , replace the contents element with the following markup that uses the style instead of a tag:

6. Run the app, navigate to a /hello/name URL, and observe that the message renders in blue. Stop the app when you're done.

Use the collectstatic command

For production deployments, you typically collect all the static files from your apps into a single folder using the command. You can then use a dedicated static file server to serve those files, which typically results in better overall performance. The following steps show how this collection is made, although you don't use the collection when running with the Django development server.

1. In , add the following line that defines a location where static files are collected when you use the command:

2. In the Terminal, run the command and observe that is copied into the top level folder alongside .

3. In practice, run any time you change static files and before deploying into production.

Create multiple templates that extend a base template

Because most web apps have more than one page, and because those pages typically share many common elements, developers separate those common elements into a base page template that other page templates then extend. (This is also called template inheritance, meaning the extended pages inherit elements from the base page.)

Also, because you'll likely create many pages that extend the same template, it's helpful to create a code snippet in VS Code with which you can quickly initialize new page templates. A snippet helps you avoid tedious and error-prone copy-paste operations.

The following sections walk through different parts of this process.

Create a base page template and styles

A base page template in Django contains all the shared parts of a set of pages, including references to CSS files, script files, and so forth. Base templates also define one or more block tags with content that extended templates are expected to override. A block tag is delineated by and in both the base template and extended templates.

The following steps demonstrate creating a base template.

1. In the folder, create a file named with the contents below, which contains blocks named "title" and "content". As you can see, the markup defines a simple nav bar structure with links to Home, About, and Contact pages, which you create in a later section. Notice the use of Django's tag to refer to other pages through the names of the corresponding URL patterns rather than by relative path.