Forem: Learn Django

Django Email and Contact Form Tutorial

Will Vincent — Fri, 26 Jan 2024 17:47:00 +0000

Let's build a simple contact form that sends email from a Django 5.0 website. We can take advantage of Django's built-in email support to make this relatively painless by first outputting emails to our terminal and then sending them in production using an email service like SendGrid.

Initial setup

The first step is to create a dedicated directory for our code. A convenient location is the Desktop. From the command line, execute the following commands to navigate to the Desktop and create a new contact folder with either Windows or macOS.

# Windows
$ cd onedrive\desktop\code
$ mkdir contact
$ cd contact

# macOS
$ cd ~/desktop/code
$ mkdir contact
$ cd contact

Now we can create and activate a virtual environment called .venv. Then, install the latest version of Django.

# Windows
$ python -m venv .venv
$ .venv\Scripts\Activate.ps1
(.venv) $ python -m pip install django~=5.0

# macOS
$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) $ python3 -m pip install django~=5.0

Next, let's create a new Django project called django_project and within it an app called sendemail:

(.venv) $ django-admin startproject django_project .
(.venv) $ python manage.py startapp sendemail

To ensure everything is installed correctly, let's migrate the initial database and execute runserver to start the local web server.

(.venv) $ python manage.py migrate
(.venv) $ python manage.py runserver

If you open you browser to 127.0.0.1:8000 you should see the following screen:

Update settings.py

We've created a new app, so we must explicitly add it to our Django project. Within your settings.py file, under INSTALLED_APPS, add sendemail at the bottom.

# django_project/settings.py
INSTALLED_APPS = [
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",
    "sendemail",  # new
]

The send_email function is what sends our emails, and its required parameters include subject, message, from_email, and recipient_list.

At the bottom of the same settings.py file, specify the EMAIL_BACKEND we'll use, which should be console for local development. We also need to add a DEFAULT_FROM_EMAIL. And since send_email requires a recipient_list, we will add a new setting, NOTIFY_EMAIL for that purpose.

# django_project/settings.py
EMAIL_BACKEND = "django.core.mail.backends.console.EmailBackend"
DEFAULT_FROM_EMAIL = "will@learndjango.com"
NOTIFY_EMAIL = "will@learndjango.com"

Update urls.py

Since we've added an app to our Django project, we need to update the root django_project/urls.py file, importing include at the top and listing a new urlpattern for the app at the empty string, "":

# django_project/urls.py
from django.contrib import admin
from django.urls import path, include  # new

urlpatterns = [
    path("admin/", admin.site.urls),
    path("", include("sendemail.urls")),  # new
]

Next, create a new file called sendemail/urls.py and add the following code so that the main contact form is at contact/ and a successful submission redirects to success/. We have yet to create the corresponding views: SuccessView and ContactView.

# sendemail/urls.py
from django.urls import path

from .views import SuccessView, ContactView

urlpatterns = [
    path("contact/", ContactView.as_view(), name="contact"),
    path("success/", SuccessView.as_view(), name="success"),
]

Create forms.py

Still, within our sendemail app, create a new file named sendemail/forms.py. It will have a ContactForm class containing the fields in our contact form: from_email, subject, and message.

# sendemail/forms.py
from django import forms


class ContactForm(forms.Form):
    email = forms.EmailField(
        widget=forms.TextInput(attrs={"placeholder": "Your e-mail"})
    )
    subject = forms.CharField(widget=forms.TextInput(attrs={"placeholder": "Subject"}))
    message = forms.CharField(
        widget=forms.Textarea(attrs={"placeholder": "Your message"})
    )

We're using Django's built-in Forms API to create three fields and add placeholder text.

Create views.py

Now, let's create the view that will do the bulk of the work for our contact form. Update the existing sendemail/views.py file, and we'll review the code below.

# sendemail/views.py
from django.conf import settings
from django.core.mail import send_mail
from django.shortcuts import reverse
from django.views.generic import TemplateView, FormView

from .forms import ContactForm


class SuccessView(TemplateView):
    template_name = "success.html"


class ContactView(FormView):
    form_class = ContactForm
    template_name = "contact.html"

    def get_success_url(self):
        return reverse("contact")

    def form_valid(self, form):
        email = form.cleaned_data.get("email")
        subject = form.cleaned_data.get("subject")
        message = form.cleaned_data.get("message")

        full_message = f"""
            Received message below from {email}, {subject}
            ________________________


            {message}
            """
        send_mail(
            subject="Received contact form submission",
            message=full_message,
            from_email=settings.DEFAULT_FROM_EMAIL,
            recipient_list=[settings.NOTIFY_EMAIL],
        )
        return super(ContactView, self).form_valid(form)

The first thing we do is create a SuccessView that displays a template, success.html. The ContactView is where the real work happens: it extends Django's FormView and refers to the corresponding form, ContactForm, and template that should be used, contact.html. Next, we have to set get_success_url, which takes the URL name of our success form from the sendemail/urls.py file.

And then we come to form_valid, meaning if the form is successfully submitted, what should happen next? Django provides excellent support for form and field validation, so the main task for us, as developers, is to ensure each field is cleaned, layout the format of the message we want to receive, and then use send_email to send the subject, message, from email, and recipient list. It is worth reading the Django docs on forms and validation for a fuller picture of all that happens behind the scenes, but suffice it to say that forms are an incredibly deep and difficult area of web development that Django handles elegantly for us.

Create templates

The final step is to create the templates for our contact and success pages. I like to make a project-level templates folder and put all of my templates in there. So, create a new directory called templates in the project directory.

(.venv) $ mkdir templates

Next, update our settings.py file to tell Django to look in this directory for templates. Update the DIRS settings within TEMPLATES with a one-line change.

# django_project/settings.py
TEMPLATES = [
    {
        ...
        "DIRS": [BASE_DIR / "templates"],  # new
        ...
    },
]

Now create a new file called templates/contact.html and update it with the following code:

<!-- templates/contact.html -->
<h1>Contact Us</h1>
<form method="post">
  {% csrf_token %}
  {{ form }}
  <div class="form-actions">
    <button type="submit">Send</button>
  </div>
</form>

Send first email

Make sure the server is running with python manage.py runserver and load http://127.0.0.1:8000/email/ in your web browser, fill out the form, and click the Send button.

If the email goes through, you will be redirected to the http://127.0.0.1:8000/success/.

And in your console/terminal, you can see that the email was sent:

(.venv) $ python manage.py runserver
Watching for file changes with StatReloader
Performing system checks...

System check identified no issues (0 silenced).
January 26, 2024 - 15:49:19
Django version 5.0.1, using settings 'django_project.settings'
Starting development server at http://127.0.0.1:8000/
Quit the server with CONTROL-C.

Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Subject: Received contact form submission
From: will@learndjango.com
To: will@learndjango.com
Date: Fri, 26 Jan 2024 15:49:28 -0000
Message-ID: <170628416888.90389.17657223448384564388@1.0.0.127.in-addr.arpa>


            Received message below from will@email.com, Hello
            ________________________


            Does this work?

-------------------------------------------------------------------------------
[26/Jan/2024 15:49:28] "POST /contact/ HTTP/1.1" 302 0
[26/Jan/2024 15:49:28] "GET /success/ HTTP/1.1" 200 43

Production Email Service

To send actual emails, we first must switch the EMAIL_BACKEND from console to SMTP.

# django_project/settings.py
DEFAULT_FROM_EMAIL = "will@learndjango.com"
NOTIFY_EMAIL = "will@learndjango.com"
EMAIL_BACKEND = "django.core.mail.backends.smtp.EmailBackend"  # new

All of the managed email services like SendGrid, mailgun, or SES have the option to send emails via SMTP.

When you sign up for an account, you will be assigned an email host, username, and password. The update to settings.py is nearly identical and looks like the one below, which uses SendGrid as an example.

# django_project/settings.py
DEFAULT_FROM_EMAIL = "will@learndjango.com"
NOTIFY_EMAIL = "will@learndjango.com"
EMAIL_BACKEND = "django.core.mail.backends.smtp.EmailBackend"
EMAIL_HOST = "smtp.sendgrid.net"  # new
EMAIL_HOST_USER = "apikey"  # new
EMAIL_HOST_PASSWORD = "<sendgrid_password>"  # new
EMAIL_PORT = 587  # new
EMAIL_USE_TLS = True  # new

For more advanced usage, django-anymail is a popular package that makes it much easier to switch between email providers.

It is also worth noting that your email apikey and password should be kept secret and stored with environment variables, not in the source code and searchable via Git.

Conclusion

With this configuration in place, you can send real emails from your Django app. Often, this is used when a user signs up for the first time, needs to reset a password, and so on. All these steps, including implementing environment variables and customizing emails are covered in the Django for Beginners book.

Django Stripe Tutorial

Will Vincent — Sat, 06 Jan 2024 02:02:20 +0000

In this tutorial, we will create a Stripe-powered Django website to handle purchases. The final site will have a homepage for orders, a success page when an order goes through, and a cancel page if the order fails.

Initial Setup

To start, open up your terminal and create a new Python virtual environment.

# Windows
$ python -m venv .venv
$ .venv\Scripts\Activate.ps1
(.venv) $

# macOS
$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) $

Then install Django, create a new project called django_project, and run migrate to initialize the new SQLite local database. Execute the runserver command to start the local web server and confirm everything works properly.

(.venv) $ python -m pip install django~=5.0.0
(.venv) $ django-admin startproject django_project .
(.venv) $ python manage.py migrate
(.venv) $ python manage.py runserver

In your web browser, navigate to 127.0.0.1:8000 to see the familiar Django welcome page.

Django Configuration

We will create a dedicated products app for our logic now using the startapp command.

(.venv) $ python manage.py startapp products

Don't forget to register the app immediately in our settings.py file so that Django knows to look for it.

# django_project/settings.py
INSTALLED_APPS = [
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",
    "products",  # new
]

Let's start by creating the URL paths for the three pages: home, success, and cancel. We could do this in an app-level file like products/urls.py, but for simplicity, we'll place them in the project-level django_project/urls.py file.

# django_project/urls.py
from django.contrib import admin
from django.urls import path

from products import views


urlpatterns = [
    path("admin/", admin.site.urls),
    path("", views.home, name="home"),
    path("success/", views.success, name="success"),
    path("cancel/", views.cancel, name="cancel"),
]

Next up are our three views that display a template file.

# products/views.py
from django.shortcuts import render


def home(request):
    return render(request, "home.html")

def success(request):
    return render(request, "success.html")

def cancel(request):
    return render(request, "cancel.html")

And lastly, the template files. Create a project-level directory called templates.

(.venv) $ mkdir templates

Then, update django_project/settings.py so that Django's template loader knows to look for it.

# django_project/settings.py
TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [BASE_DIR / "templates"],  # new

Create three new template files--home.html, success.html, and cancel.html--within the templates folder.

<!-- templates/home.html -->
<h1>Homepage</h1>

<!-- templates/success.html -->
<h1>Success page</h1>

<!-- templates/cancel.html -->
<h1>Cancel page</h1>

That's it! Make sure runserver is running, and then confirm that all three webpages exist.

Configure Stripe

Log in to your existing Stripe account or register for a free one. If you only want to use test mode, where we can mock transactions, there is no need to complete the application with bank details. Once registered, head over to the dashboard.

Click on the "Developers" nav link in the upper right-hand corner.

Make sure to activate "Test mode" and then click on the nav link for API keys.

Stripe provides a "Publishable key" and a "Secret key" that work together to process payment transactions. The publishable (or public) key is used to initiate a transaction and is visible to the client; the secret key is used on our server and should be kept confidential.

We will hardcode both for this tutorial into the bottom of our django_project/settings.py file. The live API keys should be stored in environment variables in production for proper security.

# django_project/settings.py
STRIPE_PUBLIC_KEY = "<your_test_public_api_key>"
STRIPE_SECRET_KEY = "<your_test_secret_api_key>"

Now we need a product to sell. On the lefthand sidebar, click the link for "More +" and then "Product catalog," which takes us to the Products page.

Click the "+ Add product" button in the upper right-hand corner to create a product to sell.

The required fields are name, one-off or recurring, and the amount. We are processing a one-off payment here. Click the "Add Product" button.

We are redirected to the main "Product catalog" page, where our new product is now visible.

Click on the new product to open up its page. Under the Pricing section, note the "API ID" which we will use shortly.

Now that we have a product to sell, we will focus on the Django app.

Stripe Hosted Page

If you look at the Stripe docs, the Python example provided is for a Flask Stripe-hosted page. However, we can adapt this for our Django app. At a high level, we need to add an HTML form to the home.html template and then update our views.py file so that when a POST request is sent to Stripe, our server-side Stripe SDK and Stripe Private key are used to generate a new Checkout session. The user is redirected to this unique session and then, if payment is successful, redirected to our success.html page. Otherwise, they will be sent to the cancel.html page.

Let's start by installing the Python library for Stripe, which is available on Github.

(.venv) $ python -m pip install stripe==7.10.0

In our home.html file, add a basic form using the POST method and Django's CSRF protection.

<!-- templates/home.html -->
<h1>Homepage</h1>
<form method="post">
  {% csrf_token %}
  <button type="submit">Purchase!</button>
</form>

Most of the magic happens in our views.py file. The updated code is below, and we'll work through the changes line-by-line. But before getting into specifics, it's essential to understand that at a high level, we are loading in the Stripe Private Key from our settings.py file and using it to create a new Checkout session. The user will be redirected to a custom URL for the Stripe-hosted checkout page and then, after submitting payment, either sent to a success or cancel page.

# products/views.py
from django.shortcuts import render, redirect  # new
from django.conf import settings  # new
from django.urls import reverse  # new

import stripe  # new


def home(request):  # new
    stripe.api_key = settings.STRIPE_SECRET_KEY
    if request.method == "POST":
        checkout_session = stripe.checkout.Session.create(
            line_items=[
                {
                    "price": "<price_API_ID_HERE>",  # enter yours here!!!
                    "quantity": 1,
                }
            ],
            mode="payment",
            success_url=request.build_absolute_uri(reverse("success")),
            cancel_url=request.build_absolute_uri(reverse("cancel")),
        )
        return redirect(checkout_session.url, code=303)
    return render(request, "home.html")


def success(request):
    return render(request, "success.html")


def cancel(request):
    return render(request, "cancel.html")

At the top, we've imported redirect, settings, reverse, and stripe. The first step in our home function-based view is to set the Stripe api_key to the Stripe Private Key for our account; it is stored in our settings.py file for security and not visible to the user client-side. Next, if a POST request is made a new checkout_session is created and requires, at a minimum, the following attributes: line_items, mode, success_url, and cancel_url. Other attributes are available but are not necessary at this stage.

We define a product to sell with the line_items attribute, using the exact Price ID for our product set on the Stripe website. Later on we might want to have the option of storing multiple IDs in our database to load in, but hardcoding it is fine for example purposes. We also specify the quantity of 1.

Next, we set a mode to "payment" for one-time purchases, but we could also do "subscription" for subscriptions or "setup" to collect customer payment details to reuse later.

After the user places an order, they are sent to either a success_url or a cancel_url. Django's reverse() function is used alongside the URL name of each. We also take advantage of Django's [build_absolute_uri] method to send an absolute URL to Stripe.

The final bit is redirecting to Checkout. After our POST request is sent to Stripe, authenticated, and a new Checkout session is created, Stripe's API will send us a unique checkout_session.url that the user is redirected to.

The full Stripe Checkout flow can take a while to sink in, but that's all the code we need!

Ensure the server is running, and go to the homepage at 127.0.0.1:8000 and click on the "Purchase" button.

You'll be redirected to a unique Stripe Checkout session for the product.

Fill in the form. For the credit card information, use the number 4242 4242 4242 4242, any date in the future for expiration, and any three digits for the CVC. Then click the "Pay" button at the bottom.

After successful payment, you will be redirected to the success page at http://127.0.0.1:8000/success/. You can view the confirmation of the payment on your Stripe dashboard. The Payments section, available from the left sidebar, provides further payment details.

If you want to customize the Checkout page, you can pass in additional attributes to the Checkout session.

Next Steps

For more free tutorials and premium courses on Django, check out LearnDjango.com.

Django Best Practices: Security

Will Vincent — Tue, 22 Sep 2020 17:18:17 +0000

Django is a mature, battle-tested web framework with a well deserved reputation for security over the past 15+ years.However the internet remains a dangerous place and web security is an evolving field. Like most web frameworks, Django defaults to local development settings when a new project is created. The onus is on the developer to effectively manage both local defaults and customized production settings.

Django comes with an excellent deployment checklist that can be run on the production version of your website before deployment. As well as copious notes on security in the official documentation.

This tutorial covers Django security best practices starting with the most important and working our way down the list.

Django Version

The number one security recommendation is to always be on the latest version of Django. Django has a new major release every 9 months or so (2.2, 3.0, 3.1, etc) and a minor release with security/bug fixes almost monthly (3.1.1, 3.1.2, etc). Take the time to update regularly to the latest version--there is an official guide in the documentation on upgrading to a newer version--run your test suite, and carry on with your Django project.

Note that writing comprehensive tests and implementing CI so that the tests are run on each commit is a topic for another tutorial or full-length book.

Environment Variables

There is a fundmental tension between settings intended for local development and production. Local development prizes speed, robust bug reports, and access to all features. Production requires locking down the website and minimizing access as much as possible. By default, new Django projects created with the startproject command have local development settings. The developer is responsible for updating them to production settings.

These days, the standard way to switch between local and production settings is with environment variables. Rather than having multiple settings.py files, a single settings.py file can be used with variables loaded in depending upon the environment: local or production.

There are multiple ways to implement environment variables and various third-party packages that can help. Personally, I like using environs, which has a Django-specific option that installs a number of additional packages that help with configuration.

DEBUG

Near the top of any settings.py file is the configuration for DEBUG. By default, it is set to True which generates, among other things, a rich and detailed error page that includes a traceback and lots of metadata including all currently defined Django settings. That is a roadmap to debugging locally, but also a guide for any hacker who wants to compromise your website if released in production. Therefore, make sure that in production DEBUG is set to False!

SECRET_KEY

The SECRET_KEY is a randomly generated string used for cryptographic signing created whenever the startproject command is run. It is very important that SECRET_KEY actually be kept, well, secret.

All it takes is one Git commit and your SECRET_KEY is visible to anyone with access to your source code. In practice, most developers develop a working prototype of a website before adding environment variables and production configurations. Therefore, before the first deployment, take the time to generate a new SECRET_KEY. One approach is to use Python's built-in secrets module.

$ python -c 'import secrets; print(secrets.token_urlsafe(38))'

The parameter token_urlsafe returns the number of bytes in a URL-safe text string. With Base64 encoding on average each byte has 1.3 characters. So using 38 results in 51 characters in this case. The important thing is that your SECRET_KEY has at least 50 characters. Each time you run the command, a new value is outputted.

ALLOWED_HOSTS

The ALLOWED_HOSTS setting lists which hosts/domain names your Django site can serve. By default, it is set to the empty list, [], aka any host or domain has access to your site. This needs to be changed in production to avoid HTTP Header attacks.

For local development localhost:8000 and 127.0.0.1:8000 are commonly used in Django, therefore both should be explicitly added to the setting. And once you have a custom URL for your production location--for example, if you're using Heroku it will contain .herokuapp.com, this should be added as well.

A common ALLOWED_HOSTS setting for a Heroku app is therefore the following:

# settings.py
ALLOWED_HOSTS = ['.herokuapp.com', 'localhost', '127.0.0.1']

HTTPS/SSL

These days there is no reason not to deploy your entire website behind HTTPS. Otherwise a hacker could sniff authentication credentials, API keys, or really any information transferred between the client and server. There are a number of settings to enable full SSL support in a Django project.

SECURE_SSL_REDIRECT automatically redirects requests over HTTP to HTTPS. It should be set to True.

HTTP Strict Transport Security (HSTS) is a security policy that lets our server enforce that web browsers should only interact via HTTPS by adding a Strict-Transport-Security header. There are three implicit HSTS configurations in a settings.py file that need to be updated for production:

SECURE_HSTS_SECONDS = 0
SECURE_HSTS_INCLUDE_SUBDOMAINS = False
SECURE_HSTS_PRELOAD = False

The SECURE_HSTS_SECONDS setting is set to 0 by default but the greater the better for security purposes. A good default is to set it to one month, 2,592,000 seconds, instead. SECURE_HSTS_INCLUDE_SUBDOMAINS forces subdomains to also exclusively use SSL so it should be set to True in production. And SECURE_HSTS_PRELOAD only has an effect when there is a non-zero value for SECURE_HSTS_SECONDS, but since we just set one, it will need to be set to True.

Media Files

Most Django websites will contain files that are static and unchanging such as CSS, JavaScript, images, and so on. There are broadly referred to as Static files. For certain websites, user-uploaded content is a key feature, such as an image sharing website similar to Instagram. Django refers to user-uploaded content as Media and additional precautions must be made.

In general, you can't trust your users. Especially when they have the ability to upload something to your website. Therefore for websites with media files, hosting all static content on a cloud service or CDN, like Amazon's S3, is necessary. The third party package django-storages is a popular way to configure this for your website and alleviate media security concerns.

Admin

The Django admin app is a powerful built-in feature. However, since every Django project has it located at /admin by default, it is easy for a hacker to try to force their way into any Django website at this URL. An easy way to secure your admin is to simply change the URL for the admin. In the example below it has been changed to anything-but-admin

# config/urls.py
urlpatterns = [
    path('anything-but-admin/', admin.site.urls),

For additional tips on hardening your admin, see the article 10 Tips for Making the Django Admin More Secure.

Conclusion

There are many more security improvements that can be added to a Django project but this hits the highlights. Make sure to run the Django deployment checklist on your production settings to be sure you have made all the requisite changes.

$ python manage.py check --deploy

For further help on security, the book Django for Professionals walks through building out a production-ready website with proper security features, performance tips, Docker usage, and more.

"Django Hosting Options"

Will Vincent — Fri, 04 Sep 2020 22:02:11 +0000

Django websites can be deployed on any number of hosting providers. The first choice is deciding whether to use a Platform-as-a-service (PaaS) option or a virtual private server (VPS). A PaaS is an easier albeit more expensive option that can handle many deployment issues with minimal configuration. A VPS is less expensive and provides total control but requires more knowledge and effort to setup.

Platform-as-a-Service Options

Heroku

Heroku is the original PaaS. It has a free tier for small projects and progressive pricing as a site grows in size. There is also a robust add-on ecosystem for additional services like database hosting, caching, logging, and more. Check out the Heroku Django Getting Started Guide.

PythonAnywhere

PythonAnywhere is another PaaS option that specializes in online Python environments. It also features a free tier and upgraded plans that start at $5/month. Deploying an existing Django app is straightforward and also demonstrated as part of the excellent DjangoGirls Tutorial.

Divio

Divio is a Django-specific platform that comes with pre-configured projects including Django CMS and Wagtail.

Microsoft Azure

A managed PaaS option that includes a nice video tutorial series with my DjangoChat podcast co-host Carlton Gibson.

Render

Render is a new but quite popular cloud option that allows for deploys directly from Github or Gitlab, similar to Netlify. Has options for hosted databases, cron jobs, and more.

Google Cloud

Google provides multiple PaaS options starting with App Engine which is where to start but continuing with multiple more advanced options including Kubernetes and Compute Engine.

Dokku

A lightweight, open source Docker-powered PaaS that promises to be cheaper than alternatives. There are some good tutorials on using it.

Virtual Private Servers

Digital Ocean

If you're comfortable doing basic server configuration, for as little as $5/month you can host your entire Django project on Digital Ocean. They have fantastic documentation and one-click installs for common setups like Ubuntu.

Linode

Linode is another very popular VPS provider also starting at $5/month that has fantastic customer support.

AWS Lightsail

Amazon's AWS is famously complex and Lightsail bills itself as the "easiest way to get started" by offering virtual servers, storage, databases, and networking in a monthly plan. Appropriate for small applications.

AWS Elastic Beanstalk

Elastic Beanstalk is an orchestration tool that provides a layer of abstraction over AWS's 100+ services. It does all the work to create an EC2, install apps, provides a load balancer, and so on. Lightsail is designed for prototypes while Elastic Beanstalk is more suited to scaling an existing application. It is likely more expensive than raw EC2, which is just a remote Linux machine.

Django NameError: name 'os' is not defined

Will Vincent — Wed, 22 Jul 2020 22:29:35 +0000

If you've started a new Django 3.1+ project and are using older tutorials or guides, it's likely to come across the following error on your command line:

NameError: name 'os' is not defined

Starting with Django 3.1, the startproject command generates a settings.py file that imports pathlib rather than os on the top line.

The quick fix is to import os at the top of your settings.py file:

# settings.py
import os # new
from pathlib import Path

The better fix is learn more about how pathlib works and update your BASE_DIR, DATABASES, STATICFILES_DIRS, and other files to use the newer, modern approach.

What is Django (Python)?

Will Vincent — Mon, 20 Jul 2020 14:15:10 +0000

Django is an open-source web framework written in the Python programming language. Named after the jazz guitarist Django Reinhardt, it is used by some of the largest websites in the world including Instagram, Mozilla, and NASA, but also lightweight enough to be a popular choice for weekend side projects and startups. Its "batteries-included" approach means a powerful website can be generated quickly in the hands of a skilled developer.

Web Framework

A "web framework" is software that standardizes and abstracts away common difficulties and redundancies involved in making a website. For example, most websites need to connect to a database, deploy to a server, handle URL routing, security, user registration, generate templates, and so on. In the early days, programmers had to do all of this from scratch but they quickly recognized the commonalities and started creating web frameworks.

These days, it is rare to write a website from scratch. Web frameworks exist for every modern programming languages including Rails for Ruby, Express for JavaScript, and Django or Flask for Python.

Beyond the underlying programming language, the major difference between competing web frameworks is one of approach: Ruby on Rails and Django both adopt a "batteries-included" frameworks approach whereas Flask and Express are minimal microframeworks. You can think of it as the difference between being given a bag of Legos or a pre-built truck made out of Legos. Django and Rails are faster to start using and come with many built-in guardrails to prevent bad practices. Flask and Express require more customization upfront but allow for total control. See Django vs Flask for a detailed comparison of the two most popular Python web frameworks and the pros/cons of each approach.

Python

Python is one of the most popular programming languages in the world because it is friendly to newcomers, extremely powerful, and has a robust ecosystem of libraries like Django that provide additional functionality. Python recently replaced Java as the most popular programming language at top U.S. universities and is growing rapidly among professional programmers as well, as evidenced by its growth on StackOverflow.

Python emphasizes readability and developer friendliness, as evidenced by its "Hello, World" syntax. Here it is in Python:

print("Hello, World")

And here it is in Java:

class HelloWorldApp {
    public static void main(String[] args) {
        System.out.println("Hello World!"); 
    }
}

Even if you know nothing about either programming language, it is clear at a glance that Python is the easier of the two to understand.

Background

Django was initially developed by web programmers at the Lawrence Journal-World newspaper, specifically Adrian Holovaty, Simon Willison, and Jacob Kaplan-Moss. It was first released to the public as an open source package in 2005 and is currently maintained by the non-profit Django Software Foundation. The source code is freely available online.

Key Features

Django adopts a "batteries-included" approach similar to Python and comes with a number of built-in features including an extensible authentication system, robust admin app, lightweight testing web server, and support for multiple databases including PostgreSQL, MySQL, MariaDB, Oracle, and SQLite. It is known for its leading security best practices and comes with comprehensive documentation, available either online or as a PDF/ePUB for offline consumption.

As a mature project, Django rarely makes breaking changes and has a clear deprecation schedule for any updates. A major new version is released every nine months or so with monthly patch releases for security and bug fixes.

There is also a vibrant ecosystem of third-party applications--visible on the Django Packages site--which provide additional functionality. Over time, the most popular packages are often rolled into Django itself.

Community

A common saying among Django developers is "Come for the framework, stay for the community." It is known for being a welcoming and encouraging community, which is not always the case in technology. There are annual DjangoCon conferences hosted in the U.S, Europe, Australia, and Africa, as well as meetups in many major cities.

Questions about Django can be asked on the official Django forum and newcomers are encourage to contribute to Django itself.

The weekly Django Chat podcast features interviews with key figures in the community as well as deep dives on various core features. There is also a weekly Django News newsletter with updates on events, tutorials, and third-party packages.

Conclusion

If you'd like to learn more about Django and try it out yourself, there is an official tutorial as well as many more beginner friendly resources available on LearnDjango.com.

Django Log In with Email not Username

Will Vincent — Mon, 13 Jul 2020 14:06:47 +0000

Django was first released in 2005 and since then a lot has changed in web development, notably the predominant pattern at the time of using username/email/password has been simplified to just email/password. However, due to legacy reasons around the built-in Django User model, it can take a few extra steps to implement this change in practice.

In this tutorial we'll walk through how to implement email and password only for sign up and log in on a new Django project using a custom user model and the popular django-allauth package.

Getting Started

I'll assume you know how to start and install a new Django project using Pipenv. If not, please see here for additional help.

On the command line, create a new directory for our code called code (it can live anywhere on your computer but we'll use the Desktop as I'm on a Mac). Then install Django, start the virtual environment with shell, and create a new project.

$ cd ~/Desktop
$ mkdir code && cd code
$ pipenv install django~=3.0.0
$ pipenv shell
(code) $ django-admin startproject config .

Ok, we could just jump into it here but I'm done, done, done with writing any more Django tutorials that don't use a custom user model upfront. So, let's configure a custom user model before running migrate for the first time.

Custom User Model

I wrote about this in length over here so I'm just going to give the commands in this post.

Create a users app.

(code) $ python manage.py startapp users

Update the settings.py file.

# config/settings.py
INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',

    # Local
    'users.apps.UsersConfig', # new
]
...
AUTH_USER_MODEL = 'users.CustomUser' # new

Create our CustomUser model.

# users/models.py
from django.contrib.auth.models import AbstractUser
from django.db import models

class CustomUser(AbstractUser):
    # add additional fields in here

    def __str__(self):
        return self.email

Create a new users/forms.py file and then fill it with the following code.

# users/forms.py
from django import forms
from django.contrib.auth.forms import UserCreationForm, UserChangeForm
from .models import CustomUser

class CustomUserCreationForm(UserCreationForm):

    class Meta:
        model = CustomUser
        fields = ('username', 'email')

class CustomUserChangeForm(UserChangeForm):

    class Meta:
        model = CustomUser
        fields = ('username', 'email')

And update the admin.

# users/admin.py
from django.contrib import admin
from django.contrib.auth import get_user_model
from django.contrib.auth.admin import UserAdmin

from .forms import CustomUserCreationForm, CustomUserChangeForm
from .models import CustomUser

class CustomUserAdmin(UserAdmin):
    add_form = CustomUserCreationForm
    form = CustomUserChangeForm
    model = CustomUser
    list_display = ['email', 'username',]

admin.site.register(CustomUser, CustomUserAdmin)

Now make a migrations file, migrate the database the first time, and create a superuser so we can access the admin.

(code) $ python manage.py makemigrations users
(code) $ python manage.py migrate
(code) $ python manage.py createsuperuser
(code) $ python manage.py runserver

The local server is now running so you can visit both http://127.0.0.1:8000 for the Django welcome page and also http://127.0.0.1:8000/admin to log in with our new superuser account.

Make sure to log out of the admin at this point. Why? Because if you don't then Django will automatically send all future URL requests to /accounts/profile/ and future stuff won't work.

We will configure this properly later on but for now, just make sure you're logged out or stuff will break.

django-allauth

Django does not come with built-in views, urls, and templates for a sign up page. So while we can roll our own a better approach--and the current default for many professionals--is to use the django-allauth package instead.

Install it with Pipenv making sure you've used Control+c to stop the local server.

(code) $ pipenv install django-allauth~=0.42.0

Add it to our INSTALLED_APPS setting and add Django's optional sites framework which django-allauth uses.

# config/settings.py
INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'django.contrib.sites', # new

    # 3rd party
    'allauth', # new
    'allauth.account', # new
    'allauth.socialaccount', # new

    # Local
    'users.apps.UsersConfig',
]

Ok, here's where the magic happens. django-allauth has a lengthy list of configuration options. Here's what we need.

Add this at the bottom of our config/settings.py file.

# config/settings.py
EMAIL_BACKEND = 'django.core.mail.backends.console.EmailBackend'

AUTHENTICATION_BACKENDS = (
    # Needed to login by username in Django admin, regardless of `allauth`
    "django.contrib.auth.backends.ModelBackend",

    # `allauth` specific authentication methods, such as login by e-mail
    "allauth.account.auth_backends.AuthenticationBackend",
)

SITE_ID = 1

ACCOUNT_EMAIL_REQUIRED = True
ACCOUNT_USERNAME_REQUIRED = False
ACCOUNT_SIGNUP_PASSWORD_ENTER_TWICE = False
ACCOUNT_SESSION_REMEMBER = True
ACCOUNT_AUTHENTICATION_METHOD = 'email'
ACCOUNT_UNIQUE_EMAIL = True

Now run migrate since we've updated our INSTALLED_APPS.

(code) $ python manage.py migrate

URLs

We need to tell Django where to put our fancy django-allauth config so let's use the accounts/ path.

# config/urls.py
from django.contrib import admin
from django.urls import path, include # new

urlpatterns = [
    path('admin/', admin.site.urls),
    path('accounts/', include('allauth.urls')), # new
]

Default Log In and Sign Up Pages

If you start up the local server now with python manage.py runserver you can navigate to our working log in page at http://127.0.0.1:8000/accounts/login/.

Now take a look at the sign up page at http://127.0.0.1:8000/accounts/signup/.

Templates

Time to configure our templates so things look better. django-allauth uses templates in an account folder so we'll override its defaults there.

Create a project-level templates folder and then account within it.

(code) $ mkdir templates
(code) $ mkdir templates/account

Now tell Django to look here so update the TEMPLATES config within settings.py.

# config/settings.py
TEMPLATES = [
    {
        ...
        'DIRS': [os.path.join(BASE_DIR, 'templates')], # new
        ...
    }
]

And make our log in and sign up templates.

(code) $ touch templates/account/login.html
(code) $ touch templates/account/signup.html

Ok here's the code for each.

<!-- templates/account/login.html -->
<h2>Log In</h2>
<form method="post">
  {% raw %}{% csrf_token %}
  {{ form.as_p }}{% endraw %}
  <button type="submit">Log In</button>
</form>

<!-- templates/account/signup.html -->
<h2>Sign Up</h2>
<form method="post">
  {% raw %}{% csrf_token %}
  {{ form.as_p }}{% endraw %}
  <button type="submit">Sign Up</button>
</form>

Here is the new log in page.

And the new sign up page.

But are we done? Haha, of course not. If you try out the forms you'll see they result in error pages. Why? We need to tell Django where to redirect our user after they log in and sign up.

Redirects

The setting for redirects is, not surprisingly, in our settings.py file. Here are the two lines to add:

# config/settings.py
LOGIN_REDIRECT_URL = 'home'
ACCOUNT_LOGOUT_REDIRECT_URL = 'home'

Both reference a template with the named URL of home so we'll need to create that homepage now.

Homepage

I like to create a dedicated pages app for all static pages in my Django projects. Let's blast through that quickly which means also adding a new template, view, and url. Here we go...make sure to stop the local server with Control+c.

(code) $ python manage.py startapp pages

Add the new pages app to our INSTALLED_APPS.

# config/settings.py
INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'django.contrib.sites',

    # 3rd party
    'allauth',
    'allauth.account',
    'allauth.socialaccount',

    # Local
    'users.apps.UsersConfig',
    'pages.apps.PagesConfig', # new
]

Add it to our config/urls.py file.

# config/urls.py
from django.contrib import admin
from django.urls import path, include

urlpatterns = [
    path('admin/', admin.site.urls),
    path('accounts/', include('allauth.urls')),
    path('', include('pages.urls')), # new
]

Update the views file for it.

# pages/views.py
from django.views.generic import TemplateView


class HomePageView(TemplateView):
    template_name = 'home.html'

Then make a new pages/urls.py file and fill it in like so:

# pages/urls.py
from django.urls import path

from .views import HomePageView

urlpatterns = [
    path('', HomePageView.as_view(), name='home'),
]

Now we can make our homepage template which will tell us if a user is logged in or not and provide helpful links.

Create the templates/home.html file and add some basic logic for if the user is logged in or not. Be careful not to put this within the templates/account directory, this is just in templates itself.

<!-- templates/home.html -->
{% raw %}{% if user.is_authenticated %}
  Hi {{ user.email }}!
  <p><a href="{% url 'account_logout' %}">Log Out</a></p>
{% else %}
  <p>You are not logged in</p>
  <a href="{% url 'account_login' %}">Log In</a> |
  <a href="{% url 'account_signup' %}">Sign Up</a>
{% endif %}{% endraw %}

Phew! Done. Make sure you are logged out which you can confirm by heading over quickly to the Django admin http://127.0.0.1:8000/admin. The "Log out" link is in the upper right corner.

Test it all out

Now go to our snazzy new homepage at http://127.0.0.1:8000/.

If you click on "Log in" and use your superuser account it will redirect back to the homepage. Here's what mine looks like.

Now click on the "Log out" link and then try the "Sign up" link. I've created a new user account called testuser@email.com. Upon signing up I'm redirected back to the homepage.

Next Steps

If you'd like to see a more full-featured Django starter project, my book Django for Professionals covers all of this in great detail as well as using Docker, PostgreSQL, and a host of more advanced Django topics.

What's New in Django 3.1

Will Vincent — Wed, 08 Jul 2020 19:37:36 +0000

Django 3.1 will be released in early August 2020 and comes with a number of major new features and many minor improvements including asynchronous views and middleware support, asynchronous tests, JSONField for all supported database backends (not just PostgreSQL), an updated admin page, SECURE_REFERRER_POLICY, and much more. The official release notes are the canonical reference, but this post will cover some of the highlights as well as tips for upgrading.

How to Upgrade

You really should strive to be on the latest version of both Django and Python. This will result in faster, more supported, and feature-laden code. To upgrade, create a new virtual environment, install Django 3.1, and run your test suite (you have one, yes?) by adding the -Wa flag to show full deprecation warnings.

(env) $ python -Wa manage.py test

If you don't have tests in your project yet, you can still use python -Wa manage.py runserver to see some warnings. Refer to the official upgrade list for more advice.

Django 3.1 requires Python 3.6, 3.7, or 3.8. You can read more about supported Python versions on the Django prerequisites page. If you're curious about Django's version and release policy, the download page shows the supported versions timeline and future LTS (long-term support) releases.

For further context, the Django Chat podcast co-hosted by Django Fellow Carlton Gibson has episodes on Django Versions and Django Security Releases.

Asynchronous Views, Middleware, Tests

With version 3.0, Django began its async journey in earnest with ASGI support. In 3.1, Django now supports a fully asychronous request path with views, middleware, and tests/test client.

A basic example, provided in the docs, is to make a request that waits for half a second and then returns a response.

# views.py
async def my_view(request):
    await asyncio.sleep(0.5)
    return HttpResponse('Hello, async world!')

This works whether you are running WSGI or ASGI mode, which was first added in 3.0.

A more relevant example would be to asynchronously fetch a URL in Django using HTTPX, the next-generation version of the popular requests library.

Cross-db JSONField

JSONField support for models and forms has now been extended to all Django-supported backends (MariaDB, MySQL, Oracle, and SQLite), not just PostgreSQL. This provides full support for JSONField queries.

# models.py
from django.db import models 

class SoccerInfo(models.Model):
    data = models.JSONField()

SoccerInfo.objects.create(data={
    'team': 'Liverpool FC',
    'coaches': ['Klopp', 'Krawietz'],
    'players': {'forwards': ['Salah', 'Firmino', 'Mané']},
})
SoccerInfo.objects.filter(
    data__team='Liverpool',
    data__coaches__contains='Klopp',
    data__players__has_key='forwards',
).delete()

Admin Layout

The admin now has a sidebar on the lefthand side for easier naviation on large screens. The historical breadcrumbs pattern is still available. If you'd like to disable the new sidebar, set AdminSite.enable_nav_sidebar to False.

Here is the older admin view:

And here is the new admin view with sidebar:

pathlib

Django has switched from using os.path to the more modern and concise pathlib. If you create a new project using the startproject command, the automatically generated settings.py file now defaults to pathlib.

Here is the Django 3.0 version:

# settings.py
import os

BASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.sqlite3',
        'NAME': os.path.join(BASE_DIR, 'db.sqlite3'),
    }
}

And here is the newer Django 3.1 version:

# settings.py
from pathlib import Path

BASE_DIR = Path(__file__).resolve(strict=True).parent.parent

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.sqlite3',
        'NAME': BASE_DIR / 'db.sqlite3',
    }
}

SECURE_REFERRER_POLICY

The SECURE_REFERRER_POLICY now defaults to 'same-origin', which is more secure. This is one of many steps the Django team makes around security. You can--and should--run the Django deployment checklist to ensure your project is secure before pushing to production: python manage.py check --deploy.

Conclusion

There are many more new features, extensively documented in the official release notes, which are well-worth reading in full as well as the accompanying Django 3.1 documentation.

Every major new Django release is a team effort and 3.1 is no exception. The Django Fellows, Carlton Gibson and Mariusz Feliask, are resonsible for an enormous amount of work to ensure the release process occurs smoothly and on time. Particular thanks are due to Andrew Godwin for his work on async features and Sage Abdullah for adding cross-db JSONFields.

If you'd like to support the continued development of Django, please do so on the official fundraising page or by becoming a GitHub Sponsor.

Django Static Files Tutorial

Will Vincent — Thu, 02 Jul 2020 15:18:03 +0000

Static files are a common source of confusion for Django newcomers. The term "static files" refers to files like CSS, JavaScript, or images that do not change in a web app. They remain static. For local development, static files are served up by the local Django web server and minimal configuration is required. Django does not support serving static files in production, however, so a number of additional configurations are required to get them working.

In this tutorial, we'll look at how static files work in Django, how to configure them locally, as well as using WhiteNoise to serve them in production.

Local Development

When you first run startproject to create a new Django project, a settings.py file is automatically created which defaults to local development settings. These include DEBUG set to True and DATABASES set to SQLite. It also includes, near the bottom of the file, a solitary line for static files:

# settings.py
STATIC_URL = '/static/'

The STATIC_URL setting controls the actual URL used to locate static files. In this case, that would be /static/, so in local development, 127.0.0.1:8000/static/ or localhost:8000/static/. In production, if our website was called example.com, the static files would be located at example.com/static/.

There are two steps required to use static files locally:

create a static directory
add {% load static %} at the top of a template and use the static template tag

The static directory should be in the same folder as manage.py. Add any desired static files here. For example, you might create another folder called css and within it a file called base.css. To include this file in a template, make sure the first line of the file is {% load static %} and the link would look something like this: <link href="{% static 'css/base.css' %}" rel="stylesheet">. The static template tag is used variable, could also hardcode the result here. This is useful later on for production.

That's it!

collectstatic

For production, Django looks through the entire project for static files (STATICFILES_DIRS) and collects all available static files via the collectstatic command into a dedicated directory (STATIC_ROOT). The way in which the files are stored is dictated by STATICFILES_STORAGE. We therefore need to add these three additional configurations and run the collectstatic command in production every time there is a change to the static files.

STATICFILES_DIRS tells Django where to look for static files in a Django project. Often, this is simply the static directory but there could be static directories in various apps or other locations. When the collectstatic command is run, Django refers to the list of directories here when creating a dedicated directory for production serving.

STATIC_ROOT is the location of the collected static files, often named staticfiles.

STATICFILES_STORAGE is the file storage engine used when collecting static files with the collecstatic command. By default, it is implicitly set to django.contrib.staticfiles.storage.StaticFilesStorage.

In your local Django project, add these three settings to your settings.py file.

# settings.py
STATIC_URL = '/static/'
STATICFILES_DIRS = [os.path.join(BASE_DIR, 'static'),] # new
STATIC_ROOT = os.path.join(BASE_DIR, 'staticfiles') # new
STATICFILES_STORAGE = 'django.contrib.staticfiles.storage.StaticFilesStorage' # new

Then run the command python manage.py collectstatic.

(env) $ python manage.py collectstatic
You have requested to collect static files at the destination
location as specified in your settings.

This will overwrite existing files!
Are you sure you want to do this?

Type 'yes' to continue, or 'no' to cancel:

Type yes to continue and hit the Enter key. A new staticfiles directory will be created which has folders for admin (the built-in admin has its own static files), staticfiles.json, and whatever directories are in your static folder.

If you now add a new static file to static, it will be available for local usage. It is only for production where the file won't be present, unless you run python manage.py collectstatic each and every time. For this reason, running collectstatic is typically added to deployment pipelines and is done by default on Heroku.

WhiteNoise

Even though we've configured our Django project to collect static files properly, there's one more step involved which is not included in the official Django docs. That is the configuration of WhiteNoise, radically simplified static file serving for Python web apps. Is it possible to use another package to serve Python static files? Yes. Have I ever seen it done over the last 5 years? No. Everyone uses WhiteNoise and you should, too, since Django won't serve static files in production on its own.

(env) $ pipenv install whitenoise==5.1.0

Then in the settings.py file, add whitenoise to the INSTALLED_APPS above the built-in staticfiles app. Under MIDDLEWARE, add a new WhiteNoiseMiddleware on the third line. And at the bottom of the file, change STATICFILES_STORAGE to use WhiteNoise. It should look like the following:

# settings.py
INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'whitenoise.runserver_nostatic', # new
    'django.contrib.staticfiles',
]

MIDDLEWARE = [
    'django.middleware.security.SecurityMiddleware',
    'django.contrib.sessions.middleware.SessionMiddleware',
    'whitenoise.middleware.WhiteNoiseMiddleware', # new
    'django.middleware.common.CommonMiddleware',
    'django.middleware.csrf.CsrfViewMiddleware',
    'django.contrib.auth.middleware.AuthenticationMiddleware',
    'django.contrib.messages.middleware.MessageMiddleware',
    'django.middleware.clickjacking.XFrameOptionsMiddleware',
]

...

STATIC_URL = '/static/'
STATICFILES_DIRS = [os.path.join(BASE_DIR, 'static'),]
STATIC_ROOT = os.path.join(BASE_DIR, 'staticfiles')
STATICFILES_STORAGE = 'whitenoise.storage.CompressedManifestStaticFilesStorage' # new

That's it! Run python manage.py collectstatic again so that the files are stored using WhiteNoise. And then deploy with confidence to the hosting platform of your choice.

Django Slug Tutorial

Will Vincent — Thu, 02 Jul 2020 15:13:42 +0000

In this tutorial we will add slugs to a Django website. As noted in the official docs: "Slug is a newspaper term. A slug is a short label for something, containing only letters, numbers, underscores or hyphens. They’re generally used in URLs."

To give a concrete example, assume you had a Newspaper website (such as we'll build in this tutorial). For a story titled "Hello World," the URL would be example.com/hello-world assuming the site was called example.com.

Despite their ubiquity, slugs can be somewhat challenging to implement the first time around, at least in my experience. Therefore we will implement everything from scratch so you can see how the pieces all fit together. If you are already comfortable implementing ListView and DetailView you can jump right to the Slug section.

Complete source code can be found on Github.

Set Up

To start let's navigate into a directory for our code. This can be hosted anywhere on your computer but if you're on a Mac, an easy-to-find location is the Desktop.

$ cd ~/Desktop
$ mkdir newspaper && cd newspaper

To pay homage to Django's origin at a newspaper, we'll create a basic Newspaper website with Articles. If you need help installing Python, Django, and all the rest (see here for in-depth instructions).

On your command line, enter the following commands to install the latest version with Pipenv, create a project called config, set up the initial database via migrate, and then start the local web server with runserver.

$ pipenv install django~=3.0.0
$ pipenv shell
(newspaper) $ django-admin startproject config .
(newspaper) $ python manage.py migrate
(newspaper) $ python manage.py runserver

Don't forget to include that period . at the end of the startproject command! It is an optional step that avoid Django creating an additional directory otherwise.

Navigate to http://127.0.0.1:8000/ in your web browser to see the Django welcome page which confirms everything is configured properly.

Articles app

Since the focus of this tutorial is on slugs I'm going to simply give the commands and code to wire up this Articles app. Full explanations can be found in my book Django for Beginners!

Let's start by creating an app called articles. Stop the local server with Control+c and use the startapp command to create this new app.

(newspaper) $ python manage.py startapp articles

Then update INSTALLED_APPS within our config/settings.py file to notify Django about the app.

# config/settings.py
INSTALLED_APPS = [
    ...
    'articles.apps.ArticlesConfig', # new
]

Article Model

Create the database model which will have a title and body. We'll also set __str__ and a get_absolute_url which are Django best practices.

# articles/models.py
from django.db import models
from django.urls import reverse

class Article(models.Model):
    title = models.CharField(max_length=255)
    body = models.TextField()

    def __str__(self):
        return self.title

    def get_absolute_url(self):
        return reverse('article_detail', args=[str(self.id)])

Now create a migrations file for this change, then add it to our database via migrate.

(newspaper) $ python manage.py makemigrations articles
(newspaper) $ python manage.py migrate

Django Admin

The Django admin is a convenient way to play around with models so we'll use it. But first, create a superuser account.

(newspaper) $ python manage.py createsuperuser

And then update articles/admin.py to display our app within the admin.

# articles/admin.py
from django.contrib import admin

from .models import Article

class ArticleAdmin(admin.ModelAdmin):
    list_display = ('title', 'body',)

admin.site.register(Article, ArticleAdmin)

Start up the server again with python manage.py runserver and navigate to the admin at http://127.0.0.1:8000/admin. Log in with your superuser account.

Click on the "+ Add" next to the Articles section and add an entry.

URLs

In addition to a model we'll eventually need a URL, view, and template to display an Article page. I like to move to URLs next after models although the order doesn't matter: we need all four before we can display a single page. The first step is to add the articles app to our project-level config/urls.py file.

# config/urls.py
from django.contrib import admin
from django.urls import path, include # new

urlpatterns = [
    path('admin/', admin.site.urls),
    path('', include('articles.urls')), # new
]

Next we must create the app-level urls.py file.

$ touch articles/urls.py

We'll have a ListView to list all articles and a DetailView for individual articles.

Note that we're referencing two views that have yet to be created: ArticleListView and ArticleDetailView. We'll add them in the next section.

# articles/urls.py
from django.urls import path

from .views import ArticleListView, ArticleDetailView

urlpatterns = [
    path('<int:pk>', ArticleDetailView.as_view(), name='article_detail'),
    path('', ArticleListView.as_view(), name='article_list'),
]

Views

For each view we specify the related model and appropriate not-yet-created template.

# articles/views.py
from django.views.generic import ListView, DetailView

from .models import Article

class ArticleListView(ListView):
    model = Article
    template_name = 'article_list.html'


class ArticleDetailView(DetailView):
    model = Article
    template_name = 'article_detail.html'

Templates

Finally, we come to the last step: templates. By default Django will look within each app for a templates directory. That structure in our case would be articles/templates/template.html.

Type Control+c on the command line and create the new templates directory.

(newspaper) $ mkdir articles/templates

Now add the two new templates.

(newspaper) $ touch articles/templates/article_list.html
(newspaper) $ touch articles/templates/article_detail.html

For our list page we loop over object_list which is provided by ListView. And we add an a href by using the get_absolute_url method added to the model.

<!-- article_list.html -->
<h1>Articles</h1>
{% for article in object_list %}
  <ul>
    <li><a href="{{ article.get_absolute_url }}">{{ article.title }}</a></li>
  </ul>
{% endfor %}

The detail view outputs our two fields--title and body--using the object default provided by DetailView. You can, and probably should, rename both object_list in the ListView and object in the DetailView to be more descriptive.

<!-- article_detail.html -->
<div>
  <h2>{{ object.title }}</h2>
  <p>{{ object.body }}</p>
</div>

Make sure the server is running--python manage.py runserver--and check out both our pages in your web browser.

The list of all articles is available at http://127.0.0.1:8000/.

And the detail view for our single article is at http://127.0.0.1:8000/1.

Slugs

Finally we come to slugs. Ultimately we want our article title to be reflected in the URL. In other words, "A Day in the Life" should have the URL of http://127.0.0.1:8000/a-day-in-the-life.

There are only two steps required: updating our articles/models.py file and articles/urls.py. Ready? Let's go...

In our model, we can add Django's built-in SlugField. But we must also--and this is the part that typically trips people up--update get_absolute_url as well. That's where we pass in the value used in our URL. Currently it passes in the id for the article an args, so 1 for our first article. We need to change that over to a keyword argument, kwargs, for our slug.

# articles/models.py
from django.db import models
from django.urls import reverse


class Article(models.Model):
    title = models.CharField(max_length=255)
    body = models.TextField()
    slug = models.SlugField() # new

    def __str__(self):
        return self.title

    def get_absolute_url(self):
        return reverse('article_detail', kwargs={'slug': self.slug}) # new

Moving along let's add a migration file since we've updated our model.

(newspaper) $ python manage.py makemigrations articles
You are trying to add a non-nullable field 'slug' to article without a default; we can't do that (the database needs something to populate existing rows).
Please select a fix:
 1) Provide a one-off default now (will be set on all existing rows with a null value for this column)
 2) Quit, and let me add a default in models.py

Ack! What is this?! It turns out we already have data in our database, our single Article, so we can't just willy-nilly add a new field on. Django is helpfully telling us that we either need to a a one-off default of null or add it ourself. Hmmm.

For this very reason, it is generally good advice to always add new fields with either null=True or with a default value.

Let's take the easy approach of setting null=True for now. So type 2 on the command line. Then add this to our slug field.

# articles/models.py
from django.db import models
from django.urls import reverse


class Article(models.Model):
    title = models.CharField(max_length=255)
    body = models.TextField()
    slug = models.SlugField(null=True) # new

    def __str__(self):
        return self.title

    def get_absolute_url(self):
        return reverse('article_detail', kwargs={'slug': self.slug})

Try to create a migrations file again and it will work.

(newspaper) $ python manage.py makemigrations articles

Go ahead and migrate the database as well to apply the change.

(newspaper) $ python manage.py migrate

But if you think about it, what we've done is create a null value for our slug. We have to go into the admin to set it properly. Start up the local server, python manage.py runserver, and go to the Article page in the Admin. The Slug field is empty.

Manually add in our desired value a-day-in-the-life and click "Save."

Ok, last step is to update articles/urls.py so that we display the slug keyword argument in the URL itself. Luckily that just means swapping out <int:pk> for <slug:slug>.

# articles/urls.py
from django.urls import path

from .views import ArticleListView, ArticleDetailView

urlpatterns = [
    path('<slug:slug>', ArticleDetailView.as_view(), name='article_detail'), # new
    path('', ArticleListView.as_view(), name='article_list'),
]

And we're done! Go to the list view page at http://127.0.0.1:8000/ and click on the link for our article.

And there it is with our slug as the URL! Beautiful.

Unique and Null

Moving forward, do we really want to allow a null value for a slug? Probably not as it will break our site! Another consideration is: what happens if there are identical slugs? How will that resolve itself? The short answer is: not well.

Therefore let's change our slug field so that null is not allowed and unique values are required.

# articles/models.py
from django.db import models
from django.urls import reverse


class Article(models.Model):
    title = models.CharField(max_length=255)
    body = models.TextField()
    slug = models.SlugField(null=False, unique=True) # new

    def __str__(self):
        return self.title

    def get_absolute_url(self):
        return reverse('article_detail', kwargs={'slug': self.slug})

Make migration/migrate. Need empty for past entry.

(newspaper) $ python manage.py makemigrations articles
You are trying to change the nullable field 'slug' on article to non-nullable without a default; we can't do that (the database needs something to populate existing rows).
Please select a fix:
 1) Provide a one-off default now (will be set on all existing rows with a null value for this column)
 2) Ignore for now, and let me handle existing rows with NULL myself (e.g. because you added a RunPython or RunSQL operation to handle NULL values in a previous data migration)
 3) Quit, and let me add a default in models.py
Select an option:

Select 2 since we can manually handle the existing row ourself, and in fact, already have. Then migrate the database.

(newspaper) $ python manage.py migrate

PrePopulated Fields

Manually adding a slug field each time quickly becomes tedious. So we can use a prepopulated_field in the admin to automate the process for us.

Update articles/admin.py as follows:

# articles/admin.py
from django.contrib import admin

from .models import Article

class ArticleAdmin(admin.ModelAdmin):
    list_display = ('title', 'body',)
    prepopulated_fields = {'slug': ('title',)} # new

admin.site.register(Article, ArticleAdmin)

Now head over to the admin and add a new article. You'll note that as you type in the Title field, the Slug field is automatically populated. Pretty neat!

Signals, Lifecycle Hooks, Save, and Forms/Serializers

In the real world, it's unlikely to simply provide admin access to a user. You could, but at scale it's definitely not a good idea. And even on a small scale, most non-technical users will find a web interface more appealing.

So...how to auto-populate the slug field when creating a new Article. It turns out Django has a built-in tool for this called slugify!

But how to use slugify? In practice, it's common to see this done with a Signal. But I would argue--as would Django Fellow Carlton Gibson--that this is not a good use of signals because we know both the sender and receiver here. There's no mystery. We discuss the proper use of signals at length in our Django Chat Podcast episode on the topic.

An alternative to signals is to use a lifecycle hook via something like the django-lifecycle package. Lifecycle hooks are an alternative to Signals that provide similar functionality with less indirection.

Another common way to see this implemented is by overriding the Article model's save method. This also "works" but is not the best solution. Here is one way to do that.

# articles/models.py
from django.db import models
from django.template.defaultfilters import slugify # new
from django.urls import reverse

class Article(models.Model):
    title = models.CharField(max_length=255)
    body = models.TextField()
    slug = models.SlugField(null=False, unique=True)

    def __str__(self):
        return self.title

    def get_absolute_url(self):
        return reverse('article_detail', kwargs={'slug': self.slug})

    def save(self, *args, **kwargs): # new
        if not self.slug:
            self.slug = slugify(self.title)
        return super().save(*args, **kwargs)

The best solution, in my opinion, is to create the slug in the form itself. This can be done by overriding the form's clean method so that cleaned_data has the slug, or JavaScript can be used to auto-populate the field as is done in the Django admin itself. If you're using an API, the same approach can be applied to the serializer.

This solution does not rely on a custom signal and handles the slug before it touches the database. In the words of Carlton Gibson, who suggested this approach to me, win-win-win.

Words of Caution

A quick word of caution on using slugs in a large website. Despite requiring an Article to be unique it is almost inevitable to have naming conflicts using slugs. However slugs do seem to have good SEO properties. A good compromise is to combine a slug with a UUID or a username. The ultimate URL would therefore be {{ uuid }}/{{ slug }} or {{ username }}/{{ slug }}. If you look at Github, for example, the source code for this tutorial is at https://github.com/wsvincent/django-slug-tutorial which is a username + slug pattern. While you could also use an id + a slug, using ids is often a security concern and in my opinion should be avoided for production websites.

Next Steps

If you want to compare your code with the official source code, it can be found on Github.

How to Learn Django (2020)

Will Vincent — Sun, 21 Jun 2020 20:05:04 +0000

As a “batteries-included” web framework, Django comes with a host of built-in features and a correspondingly steep learning curve for newcomers. In this post, I discuss what you need to know before giving Django a proper go and links to recommended resources.

HTML/CSS

Web pages are made out of HTML and CSS. Knowing how to build and deploy static websites is highly recommended before embarking on an attempt at Django. Fortunately, there are several good free resources available including FreeCodeCamp; Shay How’s Learn to Code HTML & CSS series, and HTML & CSS is Hard.

HTML itself is not that deep a topic. You can learn the basics in a day and master most of you’ll need within a week. CSS is, unfortunately, far more complex. You don’t need to become a CSS expert, but you should know how it interacts with HTML and be able to style your static websites somewhat. In practice, most developers rely on a CSS framework like Bootstrap or Tailwind, and in companies Django developers typically don’t touch the front-end at all, so a basic understanding is all that you need.

World Wide Web

It’s necessary to also have a fundamental understanding of how the World Wide Web actually works. Mozilla has probably the best guide called How the Web works which is part of its larger, and also recommended, Learn Web Development series.

Python

Django is written entirely in the Python programming language so it shouldn’t be surprising that Python knowledge is part of the list of prerequisites. The question, though, is how much Python do you need to know? Obviously the more the better but I would argue you don’t need to be a Python expert to use Django. At a minimum, you should understand how to install Python packages (like Django), use a virtual environment, imports, and classes. RealPython is a popular source of Python tutorials but if you’re looking for a book, Python Crash Course covers the basics and is enough background to embark on Django itself.

Databases & SQL

A database-driven website relies on, well, databases so you should have a basic understanding of how SQL works as well as database design principles. Khan Academy has a free guide to SQL and this site has a Database Design Tutorial for Beginners that is also worth reading to understand primary keys, one-to-many relationships, and database normalization.

When using Django itself, the ORM abstracts away the need to write raw SQL but understanding how databases work becomes increasingly essential as websites grow in size.

Git

The final prerequisite is knowledge of Git, the version control system you’ll use on every project. It’s not technically part of Django but you’ll use it on any serious side or professional project. Github has a Git Handbook that is a good first step. You should understand how to install git on a new repository, make commits, and push/pull code to a remote repository either GitHub, GitLab, or BitBucket most likely.

Django Tutorials

Finally we come to Django itself whose official docs feature a Start page. The official Polls tutorial is a good place to start but is not a friendly welcome for those new to web development with frameworks. It does not cover how to install Python or deploy your site to the internet, and goes in-depth on some areas of Django itself.

If you find the official tutorial too much, a gentler introduction can be found in the Django Girls tutorial on building and deploying a blog, or the sample chapters of Django for Beginners which cover the building of three Django sites. Mozilla also has a comprehensive though slightly more advanced guide to Django.

Books

For a book-length treatment, Django for Beginners and Django Crash Course are friendly beginner treatments. For intermediate/advanced coverage, Two Scoops of Django, Django for Professionals(https://djangoforprofessionals.com), and Speed Up Your Django Tests are recommended.

Videos

There are many YouTube videos on Django and the quality varies considerably. Solid options include Corey Schafer’s series as well as those by Traversy Media. For a paid option, JustDjango is quality content.

Podcasts

At the moment, there is only one weekly podcast on Django called Django Chat, hosted by the creator of LearnDjango.com and a Django Fellow, Carlton Gibson. Django Riffs is a budding series and Running in Production often features Django-specific content.

Conferences & Meetups

The best way to learn more and become involved in the community is to attend either a DjangoCon or local Meetup. DjangoCon US has been delayed until 2021 although DjangoCon Africa is scheduled for November, and both DjangoConEurope and PyCon Australia are holding virtual conferences. In addition, there are Django meetups in most major cities that meet monthly and even, these days, virtually.

Django Forum

If you’re stuck on a Django issue, Stack Overflow is always an option but a newer one is the official Django Forum which has a wealth of good advice from experts in the community.

Conclusion

Ultimately, learning Django is a constant endeavor. The framework continues to evolve as does the broader World Wide Web, most notably with the current introduction of Async features in Django 3.0+. With a major new release scheduled for every 9 months, there’s never been a better time to learn Django.

Django "Hello, World" 5 Different Ways

Will Vincent — Fri, 12 Jun 2020 14:23:12 +0000

Django is a "batteries-included" framework that comes with built-in scaffolding provided by the startproject command and the general concepts of apps. But, actually, Django provides incredible flexibility if desired around structure.

Consider how to architect a single page website: what's the simplest way to do it? Off the top of my head, at least 5 approaches come to mind. Because if you really think about it, apps are not mandatory at all but rather an organizational convenience that help reason about the codebase. Ditto for independent views files. We don't even need templates for a simple site when we can return strings in a view. Pretty much a urls.py file is the only "mandatory" part of the exercise.

Setup

On your command line, create a new directory called five and make a new Django project. We'll be using Pipenv here and calling our top-level directory config.

$ pipenv install django==3.0.7
$ pipenv shell
(five) $ django-admin startproject config .
(five) $ python manage.py migrate
(five) $ python manage.py runserver

Navigate over to the Django homepage at http://127.0.0.1:8000/ to confirm everything is working.

1. App + TemplateView

The "traditional" approach would be to create a dedicated app for static pages and use TemplateView, a generic class-based view provided by Django.

First, create the app which can be called whatever we choose. In this case, it'll be pages. Make sure you've stopped the local server by typing Control+c.

(five) $ python manage.py startapp pages

Add the new app to our INSTALLED_APPS setting.

# config/settings.py
INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'pages.apps.PagesConfig', # new
]

Update the config/urls.py file by importing include and adding a path for the pages app.

# config/urls.py
from django.contrib import admin
from django.urls import path, include # new

urlpatterns = [
    path('admin/', admin.site.urls),
    path('', include('pages.urls')), # new
]

Ok, now what? We need a urls.py file within our app, a views file, and a template file.

Let's start with the pages/urls.py file. First, create it by using the touch command if you're on a Mac.

(five) $ touch pages/urls.py

The code includes a single path at home1/, a HomePageView we haven't created yet, and the URL name of home.

# pages/urls.py
from django.urls import path

from .views import HomePageView

urlpatterns = [
    path('home1/', HomePageView.as_view(), name='home1'),
]

The view imports TemplateView and points to a template called home.html.

# pages/views.py
from django.views.generic import TemplateView


class HomePageView(TemplateView):
    template_name = 'pages/home.html'

And finally we need a template. Create a templates directory within the pages app, then a new directory called pages, and finally the template called home.html.

<!- pages/templates/pages/home.html ->
<h1>Hello World</h1>

Start up the local server again with python manage.py runserver and navigate to http://127.0.0.1:8000/home1/.

This approach works well for large projects where you want a dedicated pages app for static pages. But since this article is for educational purposes, let's see 4 more ways we can achieve the same outcome.

2. Function-Based View

The first thing we could do is swap out the generic class-based TemplateView for a function-based view. Django allows for either using function-based or class-based views.

We'll import render at the top of pages/views.py and add a new view, home_page_view2, which requests the same template home.html.

# pages/views.py
from django.shortcuts import render # new
from django.views.generic import TemplateView


class HomePageView(TemplateView):
    template_name = 'pages/home.html'


def home_page_view2(request): # new
    return render(request, 'pages/home.html')

This new view will have its own path, home2/, in the pages/urls.py file.

# pages/urls.py
from django.urls import path

from .views import HomePageView, home_page_view2 # new

urlpatterns = [
    path('home1/', HomePageView.as_view(), name='home1'),
    path('home2/', home_page_view2, name='home2'), # new
]

Make sure the server is still running and navigate to http://127.0.0.1:8000/home2/ to see the new version of our homepage in action.

3. No Template!

A third approach would be to remove the template entirely, since all we're displaying is a short amount of text. We can create a new view that does this by importing HttpResponse and hard-coding the string Hello World to be returned.

# pages/views.py
from django.shortcuts import render, HttpResponse # new
from django.views.generic import TemplateView


class HomePageView(TemplateView):
    template_name = 'pages/home.html'


def home_page_view2(request): 
    return render(request, 'pages/home.html')


def home_page_view3(request): # new
    return HttpResponse('Hello World')

# pages/urls.py
from django.urls import path

from .views import HomePageView, home_page_view2, home_page_view3 # new

urlpatterns = [
    path('home1/', HomePageView.as_view(), name='home1'),
    path('home2/', home_page_view2, name='home2'),
    path('home3/', home_page_view3, name='home3'), # new
]

Navigate to http://127.0.0.1:8000/home3/ in your web browser to see this third version in action.

4. No App!

We don't have to use apps, actually, if we don't want to. It's possible to create a "Hello World" page solely within our project-level config directory.

Here is all the code we need in just a single file:

# config/urls.py
from django.contrib import admin
from django.urls import path, include
from django.views.generic import TemplateView # new

urlpatterns = [
    path('admin/', admin.site.urls),
    path('', include('pages.urls')),
    path('home4/', TemplateView.as_view(template_name='pages/home.html'), name='home4'), # new
]

We've imported TemplateView at the top, create a new URL path, pointed to the existed template within the path, and provided an updated URL name of home4.

Navigate to http://127.0.0.1:8000/home4/ to see this in action!

5. Models

A fifth approach would be to use the database to display our "Hello World" message. That involves adding a models.py file and leveraging the built-in DetailView.

Create a new file called pages/models.py. We'll only add a single field, text, to the model called Post. Adding an optional __str__ method means the model will display nicely within the Django admin.

# pages/models.py
from django.db import models


class Post(models.Model):
    text = models.TextField()

    def __str__(self):
        return self.text[:50]

Since we made a change to our database models, it's time for a migrations file and then to invoke migrate to update the database.

(five) $ python manage.py makemigrations
(five) $ python manage.py migrate

We'll want a basic pages/admin.py file to see our pages app within the admin so update pages/admin.py as follows:

# pages/admin.py
from django.contrib import admin

from .models import Post

admin.site.register(Post)

Create a superuser account and start up the server again.

(five) $ python manage.py createsuperuser
(five) $ python manage.py runserver

Click on "+Add" next to it. Add our text which will be "Hello World" and click the "Save" button in the bottom right.

Success! We've added our first post to the database.

To display this post we'll need a urls file, a views file, and a template file. Start with pages/urls.py where we'll import a new view called HomeDetailView and add a path for it.

# pages/urls.py
from django.urls import path

from .views import HomePageView, home_page_view2, home_page_view3, HomeDetailView # new

urlpatterns = [
    path('home1/', HomePageView.as_view(), name='home1'),
    path('home2/', home_page_view2, name='home2'),
    path('home3/', home_page_view3, name='home3'),
    path('home/<int:pk>/', HomeDetailView.as_view(), name='post_detail'), # new
]

The pages/views.py file needs to import DetailView at the top and our Post model. Then create HomeDetailView which references our Post model and a new pages/home5.html template.

# pages/views.py
from django.shortcuts import render, HttpResponse 
from django.views.generic import TemplateView, DetailView # new

from .models import Post # new

class HomePageView(TemplateView):
    template_name = 'pages/home.html'


def home_page_view2(request): 
    return render(request, 'pages/home.html')


def home_page_view3(request): 
    return HttpResponse('Hello, World!)


class HomeDetailView(DetailView): # new
    model = Post
    template_name = 'pages/home5.html'

The last step is to create a new template called home5.html that will display the text field from our model.

<!-- pages/templates/home5.html -->
{{ post.text }}

Make sure the local server is running python manage.py runserver and navigate to http://127.0.0.1:8000/home/1/ to see our 5th approach in action.

And there it is!

Conclusion

If you understand these five approaches you'll be well on your way to understanding all that Django has to offer. And you can start exploring additional ways to tackle this arbitrary challenge, for example, taking a look at base view class, get_context_data, HTTPRequest and likely many others.