DEV Community: Michael Obasoro

An Introduction to Asynchronous Tasks and Background Workers in Django

Michael Obasoro — Wed, 04 Jun 2025 18:59:50 +0000

Asynchronous tasks are operations that are carried out independently of the main program's flow. These operations are performed by simple processes called background workers.

If you didn't quite get that, don't worry. It'll make much more sense in a bit.

In this article, we will go through what asynchronous tasks and background workers are, why they're so important, and how to build a project that utilizes them with Django.

Who is this article for?

I welcome anyone interested in learning something new (or from a different perspective) to gain from my writing. However, I wrote this article with a specific set of people in mind, and they are:

Developers who have seen these terms before but never really got to understand what they meant
Django developers who want to learn how to use asynchronous tasks and background workers in their projects

Prerequisites

To get the most out of this tutorial, you'll need:

Basic Django knowledge (You know, project setup, models, views, templates, etc)
Basic understanding of the request-response cycle

ATTENTION: To get our hands dirty with asynchronous tasks, we're going to be relying on a distributed queuing system called Celery. Now while Celery technically runs on all major operating systems, there is no (longer) official support for Windows. This means some features like multiprocessing won't work out of the box.

If you're on Windows, I strongly urge you to consider using WSL (Windows Subsystem for Linux) for a smoother experience—as I will assume every reader on Windows is, from here onward. Head here for crystal-clear instructions on how to get it set up, then come back once you're done.

Synchronous Tasks vs Asynchronous Tasks

Before we unravel the secrets of asynchronous tasks, let's understand what it means for tasks to be synchronous using a simple example.

Take a look at this view function:

def example_view(request):
    do_something()
    do_another_thing()
    do_one_last_thing()
    return HttpResponse("Thank you for using our services, User!")

In our example_view, each task is processed one after the other, from top to bottom, before displaying a thank you response to our visiting user. That means do_something is executed completely before do_another_thing is processed, and so on. That is, the tasks run synchronously, or in order.

Additionally, Django was originally built on the WSGI (Web Server Gateway Interface) standard. Don't worry if you're not familiar with that term and what it means. All you need to know (for now), is that Django was designed to handle one request at a time. It will only process request_2 after request_1 has been processed completely. In other words, Django is synchronous by default.

Okay. Nothing wrong here, right?

True, but let's take a closer look at the tasks in our view and give them a little more context.

In Django views, certain operations are typically carried out before returning a response to the client. Creating and updating objects using data from the request are a couple of the more common ones, but what about tasks that are less simple and can involve delays or heavy computation—such as sending emails or generating a PDF:

def example_view(request):
    if request.method == "POST":
        # This is our example_view "doing something" i.e creating a new Note object
        new_note_title = request.POST.get('title')
        Note.objects.create(title=new_note_title) 

        # ...and these are its other two tasks renamed to give additional context
        send_email_to_someone_somewhere()
        some_heavy_task_that_takes_30_seconds()

        # Return a response to the client once the tasks are complete
        return HttpResponse("Thank you for using our services, User!")

We now have a clear idea of what happens in our view. A new note is created first, then the other two tasks are processed one after the other.

Here's the problem.

To send an email, your Django application has to communicate with an SMTP server or email service API. To generate a PDF, you'd typically work with a library that converts rendered HTML to a PDF document. The duration of each of these activities can range from a couple of seconds to a few minutes depending on certain factors. Some of these factors such as SMTP latency and the speed of the PDF library are beyond your control.

What this means for us is that Django will be stuck on a request to our example_view until every task within the view has been processed and completed:

def example_view(request):
    ...

    send_email_to_someone_somewhere() # Takes some time 
    some_heavy_task_that_takes_30_seconds() # Takes at least 30 seconds

    # The user probably leaves your web application dissatisfied before even seeing the appreciative text response
    return HttpResponse("Thank you for using our services, User!")

To prevent scenarios where users have to wait for such operations to complete before making another request, we can convert them to asynchronous tasks, that is, they would run independently and out of the main program's flow. These asynchronous tasks are offloaded to be performed by simple processes called background workers.

What are Background Workers?

Background workers are separate processes or programs that run independently from the main application to perform tasks asynchronously. These workers handle long-running, resource-intensive or time-consuming jobs without blocking the main application's responsiveness.

When we offload these sort of tasks to background workers, our web applications can remain fast and responsive to user requests while ensuring that heavy operations are completed reliably, but in the background.

Put simply, our user wouldn't have to wait on a loading screen while the email sends or some heavy task that takes about 30 seconds:

def example_view(request):
    ...

    # Pretend these operations are now being performed by background workers
    send_email_to_someone_somewhere() # but asynchronously
    some_heavy_task_that_takes_30_seconds() # still takes 30 seconds, but asynchronously (doesn't block the request)

    # The user sees the response almost instantaneously
    return HttpResponse("Thank you for using our services, User!")

How to use Asynchronous Tasks and Background Workers in Django

Now that you understand what asynchronous tasks and background workers are, it's time to figure out how to use them by building a small Django project.

Project Overview

We're going to build an app with an "About Me" form for users to fill. The form will contain fields for their name, bio, hobbies, etc. Our app will generate a PDF summary of their inputs and automatically send it to their email.

Project Setup

Create a new folder that will house our Django project. You can name it whatever you want to:

mkdir aboutme

Move into the new directory and create a virtual environment:

cd aboutme
python3 -m venv myenv

Now activate it:

source myenv/bin/activate

Install Django and create a new project (we'll call it "core") within the current directory:

(myenv) pip install django
(myenv) django-admin startproject core .

Now, your project structure should look something like this:

- aboutme/
  - manage.py
  - core/
    - __init__.py
    - asgi.py
    - settings.py
    - urls.py
    - wsgi.py

For our project to handle asynchronous tasks, we're going to install Celery, a distributed task queue system, and Redis, to serve as its message broker.
To install the core Celery package and extra dependencies needed to use Redis as its message broker:

(myenv) pip install celery[redis]

The last thing we need to install now is redis-server which runs the actual Redis database process locally:

# On Linux (Ubuntu)
sudo apt-get install redis-server
sudo service redis-server start # Start it

# On MacOS
brew install redis-server
brew services start redis # Start it

To test if redis-server is working correctly, open a new terminal and start the Redis CLI:

# Opens the Redis CLI installed with redis-server
redis-cli

Then type:

ping

If everything works correctly, you should be replied with an enthusiastic:

PONG

Now we're set!

Project Development

To get started, create a new Django application:

(myenv) python manage.py startapp myapp

Now add it to INSTALLED_APPS in your settings.py file:

# settings.py

# ...

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'myapp' # Replace with your application's name if different
]

# ...

Don't forget to tell Django where to check for any templates we'll be using:

# settings.py

# ...

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': [BASE_DIR / 'templates'], # Add this line
        'APP_DIRS': True,
        'OPTIONS': {
            'context_processors': [
                'django.template.context_processors.request',
                'django.contrib.auth.context_processors.auth',
                'django.contrib.messages.context_processors.messages',
            ],
        },
    },

# ...

In your app directory, create a templates directory. Within the newly-created templates directory, create another directory and name it whatever your app was named. This is what your folder structure should look like:

- aboutme/
  - manage.py
  - core/
    - __init__.py
    ...
  - myapp/
    - templates/
      - myapp/

Now let's build the index page for our application.
Create an index.html file in the templates/myapp directory, then copy & paste the HTML code displayed below:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>About Me Form</title>
  <style>
    body {
      font-family: Arial, sans-serif;
      background: #f9f9f9;
      margin: 0;
      padding: 0;
      display: flex;
      align-items: center;
      justify-content: center;
      height: 100vh;
    }

    .form-container {
      background: white;
      padding: 2rem;
      border-radius: 10px;
      box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);
      width: 100%;
      max-width: 500px;
    }

    h2 {
      text-align: center;
      margin-bottom: 1.5rem;
      color: #333;
    }

    label {
      display: block;
      margin: 0.75rem 0 0.25rem;
      font-weight: bold;
    }

    input, textarea, select {
      width: 100%;
      padding: 0.6rem;
      border: 1px solid #ccc;
      border-radius: 5px;
      font-size: 1rem;
    }

    textarea {
      resize: none;
    }

    button {
      margin-top: 1.5rem;
      width: 100%;
      padding: 0.75rem;
      font-size: 1rem;
      color: white;
      background-color: #007bff;
      border: none;
      border-radius: 5px;
      cursor: pointer;
    }

    button:hover {
      background-color: #0056b3;
    }
  </style>
</head>
<body>
  <div class="form-container">
    <h2>Tell Us About You</h2>

    {% if messages %}
      <ul style="list-style: none; padding: 0;">
        {% for message in messages %}
          <li style="
            margin-bottom: 1rem;
            padding: 1rem;
            border-radius: 5px;
            color: white;
            background-color:
              {% if message.tags == 'success' %} #28a745
              {% elif message.tags == 'error' %} #dc3545
              {% elif message.tags == 'warning' %} #ffc107; color: black;
              {% else %} #007bff {% endif %};
          ">
            {{ message }}
          </li>
        {% endfor %}
      </ul>
    {% endif %}

    <form method="POST">
      {% csrf_token %}

      <label for="email">Email</label>
      <input type="email" name="email" id="email" required>

      <label for="name">Name</label>
      <input type="text" name="name" id="name" required>

      <label for="about">About Me</label>
      <textarea name="about" id="about" rows="4" required></textarea>

      <label for="hobby">Favorite Hobby</label>
      <input type="text" name="hobby" id="hobby" required>

      <label for="color">Favorite Color</label>
      <select name="color" id="color" required>
        <option value="">-- Select a color --</option>
        <option value="Red">Red</option>
        <option value="Blue">Blue</option>
        <option value="Green">Green</option>
        <option value="Yellow">Yellow</option>
        <option value="Purple">Purple</option>
        <option value="Black">Black</option>
        <option value="White">White</option>
      </select>

      <label for="saying">Favorite Saying</label>
      <input type="text" name="saying" id="saying">

      <label for="dream_job">Dream Job</label>
      <input type="text" name="dream_job" id="dream_job">

      <button type="submit">Generate My PDF</button>
    </form>
  </div>
</body>
</html>

Now, to set up the index view.
In your views.py, copy & paste the lines of code displayed below:

# myapp/views.py

from django.shortcuts import render, redirect
from django.contrib import messages


def index(request):
    if request.method == 'POST':
        email = request.POST.get('email')
        name = request.POST.get('name')
        about = request.POST.get('about')
        hobby = request.POST.get('hobby')
        color = request.POST.get('color')
        saying = request.POST.get('saying')
        dream_job = request.POST.get('dream_job')

        data = {
            'email': email,
            'name': name,
            'about': about,
            'hobby': hobby,
            'color': color,
            'saying': saying,
            'dream_job': dream_job
        }

        # Nothing special happens yet. Just printing the form data
        print(data)

        messages.success(request, "Your summary is being generated and will be emailed shortly.")
        return redirect('index')

    return render(request, 'myapp/index.html')

Let's configure the URL routing. In your Django app's directory, create a urls.py file and set up the route to our index view:

# myapp/urls.py

from django.urls import path
from . import views 

urlpatterns = [
    path('', views.index, name='index'), 
]

Now in your project's core urls.py, include your app's urls:

# core/urls.py

from django.contrib import admin
from django.urls import path, include

urlpatterns = [
    path('admin/', admin.site.urls),
    path('', include('myapp.urls')) # Add this line
]

Now run the development server and check out what we've done so far:

(myenv) python manage.py runserver

# ...then visit http://localhost:8000 in your browser

Perfect. We now have the basic backbone of our project: a form that collects data from users and sends it to our view.

It's time to handle actually generating the PDF and sending it to the user's email—asynchronously.

How Does Celery Work?

Celery is a task queue system that allows you to run operations asynchronously in the background, outside the main request-response cycle of your application.

When a task is triggered, it's packaged as a message and sent to a message broker (in our case, Redis)—instead of being executed immediately. This broker acts as a middleman, holding the task until a separate process, known as a Celery worker, retrieves it.

The worker continuously listens for new tasks, picks them up from the queue, and executes them independently.

Setting Up Celery

Before we can write any asynchronous tasks, we need to configure our project to use Celery. We've already installed Celery and its dependencies, we just need to tell our project how to work with it and vice-versa.

In the same directory as your settings.py (that is, the core directory), create a celery.py file and paste the following lines of code:

# core/celery.py

import os
from celery import Celery

# set the default Django settings module
os.environ.setdefault("DJANGO_SETTINGS_MODULE", "core.settings")

app = Celery("core")

# Load task modules from all registered Django app configs.
app.config_from_object("django.conf:settings", namespace="CELERY")
app.autodiscover_tasks()

@app.task(bind=True)
def debug_task(self):
    print(f"Request: {self.request!r}")

Then in the __init__.py file in the same directory, add the following lines to make sure Celery is loaded when Django starts:

# core/__init__.py

from .celery import app as celery_app

__all__ = ("celery_app",)

Now we need to add Celery-related configurations to our settings.py file:

# core/settings.py

# Use Redis as the broker
CELERY_BROKER_URL = 'redis://localhost:6379/0'

# (Optional) Celery backend to store task results
CELERY_RESULT_BACKEND = 'redis://localhost:6379/0'

Our Django project is now ready to work with Celery for queueing and processing asynchronous tasks.

If you found these configurations a bit confusing or overwhelming, that's perfectly fine. These are things that stick the more you use them. You are not expected to grasp it immediately or have it all stored in your head. The Celery docs are perfect for making references and going deeper.

What you need to know (for now) is that you will always make such configurations before your projects can use Celery.

Generating PDFs and Sending Emails Asynchronously

We want to define an asynchronous task that generates a PDF and sends it in an email to a user.

First, we need to install a package that handles the conversion of HTML to PDF. For this, we'll use WeasyPrint:

(myenv) pip install weasyprint

Now we need to create the HTML template that will be converted to a PDF with the user's summary. In your templates/myapp directory create a pdf_template.html file and paste the following lines of code:

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>{{ name }}'s Personal Summary</title>
  <style>
    @page {
      margin: 2cm;
    }
    body {
      font-family: 'Georgia', serif;
      background: #f9f9f9;
      color: #2c3e50;
      padding: 2rem;
    }
    .container {
      background: white;
      border: 1px solid #ddd;
      border-radius: 10px;
      padding: 2rem;
      box-shadow: 0 0 10px rgba(0, 0, 0, 0.1);
    }
    h1 {
      text-align: center;
      color: #34495e;
      font-size: 28px;
      margin-bottom: 1.5rem;
    }
    .field {
      margin-bottom: 1.2rem;
    }
    .label {
      font-weight: bold;
      color: #555;
    }
    .value {
      margin-top: 0.2rem;
      font-size: 16px;
      line-height: 1.5;
      padding: 0.4rem 0.8rem;
      background: #ecf0f1;
      border-radius: 5px;
    }
    .quote {
      font-style: italic;
      color: #7f8c8d;
    }
    .footer {
      margin-top: 3rem;
      text-align: center;
      font-size: 12px;
      color: #aaa;
    }
  </style>
</head>
<body>
  <div class="container">
    <h1>{{ name }}'s Personal Summary</h1>

    <div class="field">
      <div class="label">About Me:</div>
      <div class="value">{{ about }}</div>
    </div>

    <div class="field">
      <div class="label">Favourite Hobby:</div>
      <div class="value">{{ hobby }}</div>
    </div>

    <div class="field">
      <div class="label">Favorite Color:</div>
      <div class="value">{{ color }}</div>
    </div>

    <div class="field">
      <div class="label">Favorite Saying:</div>
      <div class="value quote">"{{ saying }}"</div>
    </div>

    <div class="field">
      <div class="label">Dream Job:</div>
      <div class="value">{{ dream_job }}</div>
    </div>

    <div class="footer">
      Generated with ❤️ 
    </div>
  </div>
</body>
</html>

Now we need to write the actual task.

To define tasks in your project, create a tasks.py file in your app directory, then paste the following lines of code:

# myapp/tasks.py

from celery import shared_task # Special decorator used to define asynchronous tasks
from django.core.mail import EmailMessage
from django.template.loader import render_to_string
from weasyprint import HTML
import tempfile

@shared_task
def generate_and_send_pdf_summary(data):
    # Render HTML from template using user's data
    html_string = render_to_string('myapp/pdf_template.html', data)

    # Generate PDF using WeasyPrint
    with tempfile.NamedTemporaryFile(delete=False, suffix=".pdf") as pdf_file:
        HTML(string=html_string).write_pdf(pdf_file.name)
        pdf_file.seek(0)
        pdf_content = pdf_file.read()

    # Send the PDF via email
    email = EmailMessage(
        subject="Your Personal Summary",
        body="Attached is your personalized summary.",
        to=[data['email']],
    )
    email.attach('summary.pdf', pdf_content, 'application/pdf')
    email.send()

So we have an asynchronous task that can generate a PDF and send it to an email. Now we have to actually trigger it in our view.

Go back to your myapp/views.py and call the asynchronous task we just defined:

# myapp/views.py

# Import the task
from .tasks import generate_and_send_pdf_summary

def index(request):
    if request.method == 'POST':
        # ... shortened for brevity

        data = {
            'email': email,
            'name': name,
            'about': about,
            'hobby': hobby,
            'color': color,
            'saying': saying,
            'dream_job': dream_job
        }

        # Add the task to a queue so it runs in the background
        generate_and_send_pdf_summary.delay(data)

       # ...

    return render(request, 'myapp/index.html')

We're 99% there. One more thing.

Because we want our application to send emails to users, we have to configure our project's email settings.

Create a .env file in your project root directory and paste these lines with their appropriate values:

# aboutme/.env
# ALWAYS USE A .env file to store secrets even if you're not planning on committing to source control immediately (or at all). I think it's safer and good practice

EMAIL_BACKEND = 'django.core.mail.backends.smtp.EmailBackend'
EMAIL_HOST = ''
EMAIL_PORT = 587
EMAIL_USE_TLS = True
EMAIL_HOST_USER = 'your-email@email.com'
EMAIL_HOST_PASSWORD = 'your-password'

Now install the python-dotenv package which helps our Django project load these environmental variables:

(myenv) pip install python-dotenv

Then in the settings.py file, import the load_env function and call it:

# core/settings.py

from dotenv import load_dotenv
import os # You'll need this too
load_dotenv() # Now call it

# ...

Lastly, add the email configurations to your settings:

# core/settings.py

# ...

# EMAIL
EMAIL_BACKEND='django.core.mail.backends.smtp.EmailBackend'
EMAIL_HOST=os.getenv('EMAIL_HOST')
EMAIL_PORT=os.getenv('EMAIL_PORT')
EMAIL_USE_TLS=True
EMAIL_HOST_USER=os.getenv('EMAIL_HOST_USER')
EMAIL_HOST_PASSWORD=os.getenv('EMAIL_HOST_PASSWORD')

And we're done!

Running The Project

It's time to run our entire project.

Starting the Redis Server

Open up a new terminal and start the Redis server by typing redis-server (if it's not already running):

> redis-server

If you got something like "Could not create server TCP listening socket *:6379: bind: Address already in use" as a response, that means the Redis server is already running—which is good news for us.

Starting the Celery worker

To start the Celery worker, open up a new terminal and use the following command from the root of your project (where manage.py is):

celery -A core worker --loglevel=info

Now Celery is ready to handle asynchronous tasks from our application.

Trying out the Application

Make sure the Django development server is running, then check out what you've just created at http://localhost:8000.

Once you fill the form and click on the "Generate My PDF" button, you're immediately shown a message informing you that your PDF would be emailed to you shortly.

This may take a couple of seconds, but you don't have to watch the page load or wait for the process to complete. The app remains responsive, and you could even start filling the form, again. Whenever the task running in the background completes, you'll find your "About Me" summary (or summaries, if you eventually filled the form multiple times) in your email.

I hope this has helped demystify the concept of asynchronous tasks and background workers, and that you now feel more confident approaching them in Django.

If you have any questions, tips, or maybe need some help, please do not hesitate to leave a comment.

Thank you for reading!

How I integrated Google OAuth in my Reddit clone (DRF + React)

Michael Obasoro — Mon, 19 May 2025 14:06:48 +0000

Google OAuth allows users to sign in to your site using their Google account, instead of creating a new username and having to remember yet another password. It also saves development time and greatly reduces security risks, because you wouldn't have to build registration forms and handle password hashing and storage.

In this article, I'm going to show you how I implemented "Log in/Continue with Google" in my full-stack web application, and how you can too in your project.

Before we proceed, it's worth noting that this article was written with a specific stack in mind. There will be slight differences in implementation details depending on what stack your application uses. If this is a feature you want your application to have, and you happen to be using a different stack, you can still read along. Odds are you'll pick up a thing or two.

Prerequisites

To properly follow this tutorial, you should already have:

A running full-stack application (React + Django, or something similar)
Basic understanding of how authentication works
A Google account

Setting up Google OAuth

For your application to use Google OAuth, you'll need to create an account with Google Cloud Platform if you don't already have one.
Then, create a project on the dashboard.
Navigate to your project's Credentials section under APIs & services.
Create an OAuth application/client by filling all required fields in the form. (In this tutorial, we will be using Google's OAuth Popup UX, so do not add any URL in the "Authorised redirect URIs" section)
Configure the consent screen, then safely take note of the Client ID and secret. You will be needing them both in the next few steps.

Frontend Integration

The Google authentication process on web applications starts at the frontend where a user is presented with a link or button asking if they would like to "Continue with Google". This is the exact behaviour we want in our frontend.
The first step is to install the @react-oauth/google package which makes the integration of Google Login into our application a lot easier:

// npm
npm install @react-oauth/google@latest

// yarn
yarn add @react-oauth/google@latest

Once the installation is complete, wrap your React app with the GoogleOAuthProvider component. The component takes a clientId prop. Provide it with the clientId you obtained from the Google Cloud Console:

// app.jsx

import { GoogleOAuthProvider } from '@react-oauth/google';

const App = () => {
  return (
    <GoogleOAuthProvider clientId="your-client-id">
      {/* App components */}
    </GoogleOAuthProvider>
  );
}

export default App;

Adding the Google Button to your React App

The @react-oauth/google package provides a GoogleLogin component that renders a button and manages the sign-in flow. However, we will opt to use the UseGoogleLogin hook that the package provides to give us finer control over how the button looks and behaves:

// Login.jsx

import { useGoogleLogin } from '@react-oauth/google';

The useGoogleLogin hook takes an "options" object with multiple properties for configuration. In our case, there are just three we need to worry about:

onSuccess: A callback function that's called if the Google Authentication succeeds
onError: A callback function that's called if an error occurs during Google Authentication
flow: A string value to set which flow of Google OAuth we want our application to use

We will use this hook to create a custom 'Log in with Google' button that triggers the OAuth popup and handles the authentication flow:

// Login.jsx
...
...
function Login(){
    const handleGoogleLoginSuccess = async (credentialsResponse) => {
    try {
      // Send authorization-code to the backend server
      const response = await fetch(`${BACKEND_URL}/google-login/`, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({'auth_code': credentialsResponse.code})
      });

      if(!response.ok){
        const error = await response.json();
        console.error("Login failed.", error);
      }else{
        const data = await response.json();
        // Handle user login
        login(data);
        // Redirect the user home or to the appropriate page
        navigate("/");
      }
    }catch(err){
        console.error("Google Login failed", err);
    }
  }

  const handleGoogleLoginError = () => {
    // Handle login errors here
    console.log("Google login failed");
  }
  const googleLogin = useGoogleLogin({
    onSuccess: handleGoogleLoginSuccess,
    onError: handleGoogleLoginError,
    flow: 'auth-code' // In this flow, our application will receive an auth-code whenever a user successfully authenticates with Google. We will use this code to complete the authentication process
  })

  return (
    {/* Customize the button and add googleLogin to its click event listener */}
    <button onClick={() => googleLogin()}>
      Continue with Google
    </button>
  );
}

Swapping the Authorization Code for Tokens

Before Google Authentication can be completed, the auth-code has to be sent to Google's authorization server in exchange for tokens. This activity will be carried out on our backend.

To get started, add these two lines in your settings.py file:

# settings.py 

import os

GOOGLE_CLIENT_ID = os.getenv('GOOGLE_CLIENT_ID')
GOOGLE_CLIENT_SECRET = os.getenv('GOOGLE_CLIENT_SECRET') # Your client secret should NEVER be exposed in your codebase. Always use environmental variables

Then in your .env file (assuming you already have one), add both these variables with the actual values obtained from your Google Console:

# .env

GOOGLE_CLIENT_ID='your-google-client-id'
GOOGLE_CLIENT_SECRET='your-google-client-secret'

Because we are using environment variables though a .env file, we're going to install a library that handles loading these variables into our environment so our application can use them.
If you haven't already:

pip install python-dotenv

Then back in your settings.py:

# settings.py

# Import the dotenv function
from dotenv import load_dotenv

# Then call it
load_dotenv()

Now we have to write a view/service that communicates with Google's OAuth 2.0 token endpoint. Luckily for us, there's a Python library that helps us do just that.
google-auth is the Google authentication library for Python. It provides the ability to authenticate to Google APIs using various methods. Install the library:

pip install --upgrade google-auth

Then we write a service that handles the code exchange:

# services.py

from django.conf import settings
from google.oauth2 import id_token
from google.auth.transport import requests as google_requests
import requests

class GoogleAuthService:
    @staticmethod
    def exchange_code_for_tokens(code):
        CLIENT_ID = settings.GOOGLE_CLIENT_ID
        CLIENT_SECRET = settings.GOOGLE_CLIENT_SECRET
        TOKEN_URL = "https://oauth2.googleapis.com/token"

        response = requests.post(
            TOKEN_URL,
            data={
                "code": code, # Passed from the frontend request
                "client_id": CLIENT_ID,
                "client_secret": CLIENT_SECRET,
                "redirect_uri": "postmessage", # A special placeholder that tells Google not to redirect to a URL, but send the auth-code directly to the app. We're doing this because it works great in Single Page Apps where we typically avoid full-page reloads or redirects
                "grant_type": "authorization_code",
            },
        )

        if response.status_code == 200:
            # Google responds with `id_token` and some other tokens with their data
            response_data = response.json()

            try:
                # Google verifies the id_token's authenticity and returns a dictionary of the user's info
                idinfo = id_token.verify_oauth2_token(response_data['id_token'], google_requests.Request(), CLIENT_ID)

                return {
                    # The only user info our implementation requires
                    "email": idinfo.get('email'),
                    "sub": idinfo.get('sub')
                }

            except Exception as e:
                raise ValueError(e)

        else:
            raise Exception(f"Failed to exchange code: {response.text}")

Then in our views.py, we add a view for logging a user in to our application with Google:

# views.py

@api_view(['POST'])
def google_login(request):
    code = json.loads(request.body)['auth_code']

    if not code:
        return Response({'error': 'Token is required'}, status=status.HTTP_400_BAD_REQUEST)

    try:
        user_id_info = GoogleAuthService.exchange_code_for_tokens(code)
        email = user_id_info.get('email')
        # Google has verified that this is a real email address, and its owner has given your application permission to use it
        # Get or Create User object with the email
        # Handle User tokens or session in your application
        return Response({'user': 'some-form-of-user-tokens-and/or-state'})
    except Exception as e:
        return Response({'error': e})

To get a better visual of how it all comes together, take a look at my entire google_login view:

@api_view(['POST'])
def google_login(request):
    code = json.loads(request.body)['auth_code']

    if not code:
        return Response({'error': 'Token is required'}, status=status.HTTP_400_BAD_REQUEST)

    try:
        user_id_info = GoogleAuthService.exchange_code_for_tokens(code)
        user_qs = User.objects.filter(
            Q(email=user_id_info.get('email')) | Q(google_sub=user_id_info.get('sub'))
        )

        if user_qs.exists():
            user = user_qs.first()
            if not user.google_sub:
                user.google_sub = user_id_info.get('sub')
                user.save()

            # Generate Tokens
            refresh = RefreshToken.for_user(user)
            return Response(
                {
                    "refresh": str(refresh),
                    "access": str(refresh.access_token),
                    "user": UserSerializer(user, context={"request": request}).data,
                },
                status=status.HTTP_200_OK,
            )
        else:
            return Response({'error': 'There is no account associated with this email.'}, status=404)

    except Exception as e:
        return Response({'error': e})

...and my User model:

# accounts/models.py

class User(AbstractBaseUser, PermissionsMixin, TimeStampedModel):
    username = models.CharField(max_length=200, unique=True, blank=True, null=True)
    email = models.EmailField(_("email address"), unique=True)
    is_staff = models.BooleanField(default=False)
    is_active = models.BooleanField(default=True)
    is_verified = models.BooleanField(default=False)
    date_joined = models.DateTimeField(default=timezone.now)
    last_seen = models.DateTimeField(null=True, blank=True)
    is_first_login = models.BooleanField(default=True)
    google_sub = models.CharField(max_length=100, null=True, blank=True) 

    USERNAME_FIELD = "email"
    REQUIRED_FIELDS = []

    objects = CustomUserManager()

    class Meta:
        verbose_name = "User"
        verbose_name_plural = "Users"

    def __str__(self):
        return self.email

Theoretically, we could put the logic for exchanging tokens directly within our google_login view. However, it's better practice to keep our views focused on handling the request/response cycle and avoid duplicating logic.

"Wait, where did we duplicate logic?" is what you may be thinking. But don't worry, I'll explain in the next paragraph.

"Continuing with Google" isn't just for users who want to log in to your application. They could also be unauthenticated visitors who want to use their Google accounts to register as users on your platform. To handle this, we're going to create a google_register view, and this is what it would look like:

@api_view(['POST'])
def google_register(request):
    # Get authorization token from FE
    code = json.loads(request.body)['auth_code']

    if not code:
        return Response({'error': 'Token is required'}, status=status.HTTP_400_BAD_REQUEST)

    try:
        # We're avoiding code duplication by using our service here
        user_id_info = GoogleAuthService.exchange_code_for_tokens(code)

        if User.objects.filter(
            Q(email=user_id_info.get('email')) | Q(google_sub=user_id_info.get('sub'))
        ).exists():
            return Response({'error': 'An account with this email address already exists. Please proceed to Login'}, status=400)

        new_google_user = User.objects.create(
            email=user_id_info.get('email'),
            google_sub=user_id_info.get('sub'),
            username=generate_random_username()
        )

        return Response(
            {"message": "User registration successful"}, status=status.HTTP_201_CREATED
        )

    except Exception as e:
        return Response({'error': f'User registration failed, {e}'}, status=400)

That's pretty much it.

To recap, we explored how to securely implement Google authentication in a React + Django application using the auth-code flow. I hope this article has been able to provide clarity on how the integration works. If you have any tips or questions, please do not hesitate to leave a comment.

Thanks for reading!

Breaking scary features down into tiny models and simple logic

Michael Obasoro — Sat, 18 Jan 2025 13:54:34 +0000

If there's one thing developers can collectively agree on, it's that we have all, at one point in time, been faced with a feature we wanted to implement, but did not quite know how to go about implementing it.

In this article, I'm going to show you how to approach such features using a recent project of mine (called Chatter) as an example.

Chatter is a real-time messaging platform built using React and Django. This application offers a variety of features, some of which were less trivial to implement than the others. For the sake of simplicity, I will pick one that is easy to follow, does not require vast knowledge of a specific stack, and is transferrable to whatever feature you might want to implement, no matter how complicated.

You would probably have noticed how in messaging platforms like WhatsApp, each member of a group chat is assigned a color to their display name. The purpose of this feature is to help customers track who said what, by creating a visual distinction between users.

To implement this feature, we will observe the following steps:

1. Define the feature

Without diving into any technical details whatsoever, what is this feature we're trying to implement? In our case, we want users in a group chat to have different colors assigned to their names. Whenever Mark sends a message to a group chat, his name appears, say yellow- and when Laura does, her name appears green.

2. Give it a little more thought

Now that we have a basic understanding of how the feature should work, it's time to go a little deeper. Should Mark's name appear yellow in all group chats, or just some? Does he pick the color, or is it selected at random? Does the color ever change, or should it remain that way as long as he's a member of the group chat?

In this step, it is crucial to attempt to ask all the necessary questions surrounding your feature, as they will play the biggest role in determining the success of its implementation.

3. Getting technical

Most features in web applications work by processing and storing data in one way or the other. In this step, we will describe what data (models) will be worked with, and how (logic).

4. Check your step (3) against steps (1) and (2)

Do the models you defined capture all the data necessary for implementing your feature? Did you happen to forget one tiny detail? What about the logic, does it make sense on paper? Do you have the tools and knowledge about how to make it work and with what techniques?

If you are unsure about the answers to any of these questions, it is perfectly normal (and actually recommended) to retrace your steps and identify what you may have let slip, before proceeding.

If you eventually do choose to proceed and later discover a flaw in your logic or models, it's not the end of the world. You will surely get better at these things with time. Address the oversight you noticed, then reiterate.

The more complicated your feature is, the less likely it is that you get it working in just one go. It is not uncommon to get stuck while ironing out technical details, so do not feel alone.

5. Fire your engines

It's time to start implementing!

The following segment will briefly illustrate how I walked through each of these steps and ended up with one less feature on my checklist. It will also show fragments of code pulled directly from the project's folder(s).

Defining the feature
I want each user in a group chat to see the names of other users displayed in different colors.

Giving it a little more thought
I want Mark's color to be chosen at random whenever he is added to a group. This means that while he appears as color yellow in group chat "A", he may appear as color blue in group chat "B".

For more flexibility and personalization, I want Laura's view of Mark in group chat "A" to be different from Percy's view of him in the same group chat "A". This means that he could appear as yellow to Laura in group chat "A", but appear as purple to Percy in that very same group chat.

Getting technical
Here's the flow I'm trying to achieve:

A user/admin initializes a group chat with a certain set of members.
Each of these members (including the creator) is assigned colors which they will see other members' names displayed in. That is:
- User A will see -> User B as Green, User C as Pink, User D as Cyan.
- User B will see -> User A as Purple, User C as Grey, User D as Orange.
- ...and so on, in that particular group chat.
If a user, User Z, wasn't part of the members the group was initialized with, and an admin decides to add him in future, then User Z will be assigned colors which he will see other members' names displayed in and vice-versa. That is:
- User Z will see -> User A as Violet, User B as Yellow... and so on. And then:
- User A will see -> User Z as Blue
- User B will see -> User Z as Pink
- ...and so on, in that particular group chat.

That's about it for the logic. Now for the models.

To associate each user in a group chat with a color, we would, at the very least, require User and GroupChat models. At this point of the project, we're going to assume that we already have those in place, so most of our focus will be on a new model which I will call UserGroupContactColorMap. This model will store the color value (in hex) to associate with every other member of the group.

One more check
My models seem adequate for what I'm trying to achieve, and the logic pretty much makes sense to me, so I move to the next and final step.

Time to implement
Enough talk. It's time to do some actual coding.

This is the User model:

class CustomUser(AbstractBaseUser, PermissionsMixin):
    class OnlineStatus(models.TextChoices):
        ONLINE = 'ONLINE', 'Online'
        OFFLINE = 'OFFLINE', 'Offline'

    email = models.EmailField(_("email address"), unique=True)
    profile_picture = models.ImageField(
        blank=True,
        null=True,
        upload_to='profile_pictures/',
        validators=[validate_profile_picture]
    )
    first_name = models.CharField(max_length=140)
    last_name = models.CharField(max_length=140)
    display_name = models.CharField(max_length=160, blank=True, null=True)
    status = models.CharField(max_length=10, choices=OnlineStatus.choices, default=OnlineStatus.OFFLINE)
    ...
    ...
    ...
    # Other user-specific fields and metadata

This is the GroupChat model:

class GroupChat(models.Model):
    title = models.CharField(max_length=100)
    owner = models.ForeignKey('accounts.CustomUser', on_delete=models.CASCADE, related_name='groupchats_owned')
    admins = models.ManyToManyField('accounts.CustomUser', related_name='groupchats_admninistrated')
    description = models.TextField()
    picture = models.ImageField(
        blank=True,
        null=True,
        upload_to='group_chat_display_pictures/',
        validators=[validate_profile_picture]
    )
    members = models.ManyToManyField('accounts.CustomUser')
    created_at = models.DateTimeField(auto_now_add=True)
    updated_at = models.DateTimeField(auto_now=True)

This is the UserGroupContactColorMap model:

class UserGroupContactColorMap(models.Model):
    user = models.ForeignKey('accounts.CustomUser', on_delete=models.CASCADE, related_name='user_group_contact_color_maps')
    group = models.ForeignKey('chats.GroupChat', on_delete=models.CASCADE)
    contact_user = models.ForeignKey('accounts.CustomUser', on_delete=models.CASCADE)
    color = models.CharField(max_length=8, default=get_random_color)

To store a random color value in each UserGroupContactColorMap instance, I make use of a helper function called get_random_color(). This function will automatically take care of assigning the color value because it is set as its default:

filtered_colors = [
    "#FF5733",  # Fiery Orange
    "#33FF57",  # Bright Green
    "#3357FF",  # Vivid Blue
    "#FF33A8",  # Vibrant Pink
    "#800080",  # Purple
    "#FF4500",  # Orange Red
    "#2E8B57",  # Sea Green
    "#8A2BE2",  # Blue Violet
    ...
    ...
    ...
    # and some more fun colors.
]

def get_random_color():
    return random.choice(filtered_colors)

In my endpoint for group chat creation, after the GroupChat instance is created, UserGroupContactColorMap instances are created for each member of the group:

# Take each member of the group and create color-maps for every other member

for user_member in new_group_chat.members.all():
    for other_member in new_group_chat.members.exclude(
         id=user_member.id
    ):
        UserGroupContactColorMap.objects.create(
            user=user_member,
            group=new_group_chat,
            contact_user=other_member
        )

       serializer = GroupChatDisplaySerializer(
            new_group_chat, 
            context={"user_id": user.id}
       )
            return Response(serializer.data)

Each user client is presented a contact color map (alongside some other data necessary for rendering a group chat to the browser) that maps the IDs of every other member of the group to the colors randomly assigned to them on group creation:

"contact_color_map": {
     "72": "#6495ED",
     "73": "#32CD32",
     "75": "#4682B4",
     "76": "#EE82EE",
     "82": "#FF33A8"
}

Then the messages are rendered like such:

{groupChat?.messages.length > 0 ? 
    groupChat?.messages.map((message, idx) => (
   <GroupInboxMessage 
       key={idx}
       message={message}
       userIsSender={message?.sender.id===user.id}
       displayNameColor={groupChat?.contact_color_map[message?.sender.id]}
   />
   )) : (
        <div>
             <p className='text-xs text-center text-slate-400'>Send a message to start the conversation.</p>
        </div>
   )}

A closer look at the GroupInboxMessage component:

export default function GroupInboxMessage({ message, userIsSender, displayNameColor}){

    if(!userIsSender){
        return (
        <div className='flex w-[70%] items-center'>
            <div className="w-10 h-10 flex justify-center items-center rounded-full overflow-hidden self-start">
                <img src={getProfilePicture(message?.sender?.profile_picture)} alt="Profile" className="w-full h-full object-cover"/>
            </div>
            <div className='flex flex-col ms-3 w-full max-w-[100%]'>
                <div className='flex justify-between text-xs items-center w-[85%]'>
                    <h2 style={{color: displayNameColor}}>{message?.sender?.name.split(' ')[0]}</h2>
                    <h2 className='text-[10px]'>{formatDatetime(message?.created_at)}</h2>
                </div>
                <div className='mt-1.5 bg-slate-100 p-4 rounded-lg w-fit'>
                    <p className='text-[11px]'>{message?.content}</p>
                </div>
            </div>
        </div>
    )}else{
        return (
            <div className='flex w-[100%] items-center justify-end'>
                <div className='flex flex-col ms-3 max-w-[70%]'>
                    <div className='flex text-xs justify-end min-w-[120px]'>
                        <h2 className='text-[10px]'>{formatDatetime(message?.created_at)}</h2>
                    </div>
                    <div className='mt-1.5 bg-blue-600 p-4 rounded-lg text-white w-fit max-w-full self-end'>
                        <p className='text-[11px]'>{message.content}</p>
                    </div>
                </div>
            </div>
        )
    }
}

Aaand Voila! Here's the final look:

Sometimes the feature we want to implement is not even all that complex. Thinking of it only as a whole rather than carefully breaking it down into calculated steps is what tends to give it that image.

As you become more experienced, you will begin to consider things like performance and whether your logic is efficient regarding usage of resources. For example, how can my logic for creating color maps be rewritten to optimize performance and reduce database hits? What if the platform has hundreds of users in each group chat? Would bulk-creation and batch-processing do the trick? I personally would regard such considerations in an additional step (6).

If you're already aware of methods to ensure the efficiency of the code for your feature, go right ahead and use them; performance is a very important metric for code. Otherwise, I wouldn't advise you to spend hours or days trying to make your code 100% efficient in one go before actually completing the implementation. I'd say give it your best shot, then come back to optimize as soon as you can.

I hope this framework helps you conquer whatever feature needs arise in your project(s).