DEV Community: AVLESSI Matchoudi

Guide to Building a Complete Blog App with Django using TDD Methodology and PostgreSQL (Part 3): Secure User Authentication

AVLESSI Matchoudi — Fri, 18 Oct 2024 09:04:32 +0000

Welcome back, everyone! In the previous part, we established a secure user registration process for our Django blog application. However, after successful registration, we were redirected to the homepage. This behaviour will be modified once we implement user authentication. User authentication ensures that only authorized users can access certain functionalities and protects sensitive information.

In this series, we are building a complete blog application, guided by the following Entity-Relationship Diagram (ERD). For this time, our focus will be on setting up a secure user authentication process. If you find this content helpful, please like, comment, and subscribe to stay updated when the next part is released.

This is a preview of how our login page will look after we’ve implemented the login functionality. If you haven’t read the previous parts of the series, I recommend doing so, as this tutorial is a continuation of the previous steps.

Okay, let’s get started !!

Django comes with a built-in app called contrib.auth, which simplifies handling user authentication for us. You can check the blog_env/settings.py file, under the INSTALLED_APPS, you’ll see that auth is already listed.

# django_project/settings.py
INSTALLED_APPS = [
    # "django.contrib.admin",
    "django.contrib.auth",  # <-- Auth app
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",
]

The auth app provides us with multiple authentication views for handling login, logout, password change, password reset, etc. This means that the essential authentication functionality, such as user login, registration, and permissions, is ready to use without needing to build everything from scratch.

In this tutorial, we’ll focus solely on the login and logout views, and cover the rest of the views in later parts of the series.

1. Create a login form

Following our TDD approach, let’s begin by creating tests for the login form. Since we haven’t created a login form yet, navigate to the users/forms.py file and create a new class inheriting from AuthenticationForm.

# users/forms.py
from django.contrib.auth import AuthenticationForm

class LoginForm(AuthenticationForm):

Once the form is defined, we can add test cases in users/tests/test_forms.py to verify its functionality.

# users/tests/test_forms.py

#   --- other code

class LoginFormTest(TestCase):
  def setUp(self):
    self.user = User.objects.create_user(
      full_name= 'Tester User',
      email= 'tester@gmail.com',
      bio= 'new bio for tester',
      password= 'password12345'
    )

  def test_valid_credentials(self):
    """
    With valid credentials, the form should be valid
    """
    credentials = {
      'email': 'tester@gmail.com',
      'password': 'password12345',
      'remember_me': False
    }

    form = LoginForm(data = credentials)
    self.assertTrue(form.is_valid())

  def test_wrong_credentials(self):
    """
    With wrong credentials, the form should raise Invalid email or password error
    """
    credentials = {
      'email': 'tester@gmail.com',
      'password': 'wrongpassword',
      'remember_me': False
    }
    form = LoginForm(data = credentials)
    self.assertIn('Invalid email or password', str(form.errors['__all__']))

  def test_credentials_with_empty_email(self):
    """
    Should raise an error when the email field is empty
    """
    credentials = {
      'email': '',
      'password': 'password12345',
      'remember_me': False
    }
    form = LoginForm(data = credentials)
    self.assertFalse(form.is_valid())
    self.assertIn('This field is required', str(form.errors['email']))

  def test_credentials_with_empty_password(self):
    """
    Should raise error when the password field is empty
    """
    credentials = {
      'email': 'tester@gmail.com',
      'password': '',
      'remember_me': False
    }
    form = LoginForm(data = credentials)
    self.assertFalse(form.is_valid())
    self.assertIn('This field is required', str(form.errors['password']))

These tests cover scenarios like successful login with valid credentials, failed login with invalid credentials, and handling error messages appropriately.

The AuthenticationForm class provides some basic validation by default. However, with our LoginForm, we can tailor its behaviour and add any necessary validation rules to meet our specific requirements.

# users/forms.py

# -- other code
from django.contrib.auth.forms import UserCreationForm, UserChangeForm, AuthenticationForm # new line
from django.contrib.auth import get_user_model, authenticate # new line


# --- other code

class LoginForm(AuthenticationForm):
  email = forms.EmailField(
    required=True,
    widget=forms.EmailInput(attrs={'placeholder': 'Email','class': 'form-control',})
  )
  password = forms.CharField(
    required=True,
    widget=forms.PasswordInput(attrs={
                                'placeholder': 'Password',
                                'class': 'form-control',
                                'data-toggle': 'password',
                                'id': 'password',
                                'name': 'password',
                                })
  )
  remember_me = forms.BooleanField(required=False)

  def __init__(self, *args, **kwargs):
    super(LoginForm, self).__init__(*args, **kwargs)
    # Remove username field

    if 'username' in self.fields:
      del self.fields['username']

  def clean(self):
    email = self.cleaned_data.get('email')
    password = self.cleaned_data.get('password')

    # Authenticate using email and password
    if email and password:
      self.user_cache = authenticate(self.request, email=email, password=password)
      if self.user_cache is None:
        raise forms.ValidationError("Invalid email or password")
      else:
        self.confirm_login_allowed(self.user_cache)
    return self.cleaned_data

  class Meta:
    model = User
    fields = ('email', 'password', 'remember_me')

We’ve created a custom login form that includes the following fields: email, password, and remember_me. The remember_me checkbox allows users to maintain their login session across browser sessions.

Since our form extends the AuthenticationForm, we've overridden some default behaviour:

** __init__ method**: We've removed the default username field from the form to align with our email-based authentication.
clean() method: This method validates the email and password fields. If the credentials are valid, we authenticate the user using Django's built-in authentication mechanism.
confirm_login_allowed() method: This built-in method provides an opportunity for additional verification before login. You can override this method to implement custom checks if needed. Now our tests should pass:

(.venv)$ python3 manage.py test users.tests.test_forms
Found 9 test(s).
Creating test database for alias 'default'...
System check identified no issues (0 silenced).
.........
----------------------------------------------------------------------
Ran 9 tests in 3.334s
OK
Destroying test database for alias 'default'...

2. Create our login view

2.1 Create tests for the login view

Since we do not have the view for the login yet, let's navigate to the users/views.py file and create a new class inheriting from the auth app’s LoginView

# -- other code 
from .forms import CustomUserCreationForm, LoginForm
from django.contrib.auth import get_user_model, views
# -- other code

class CustomLoginView(views.LoginForm):

At the bottom of the users/tests/test_views.py file add these test cases

# users/tests/test_views.py

# -- other code

class LoginTests(TestCase):
  def setUp(self):
    User.objects.create_user(
      full_name= 'Tester User',
      email= 'tester@gmail.com',
      bio= 'new bio for tester',
      password= 'password12345'
    )
    self.valid_credentials = {
      'email': 'tester@gmail.com',
      'password': 'password12345',
      'remember_me': False
    }

  def test_login_url(self):
    """User can navigate to the login page"""
    response = self.client.get(reverse('users:login'))
    self.assertEqual(response.status_code, 200)

  def test_login_template(self):
    """Login page render the correct template"""
    response = self.client.get(reverse('users:login'))
    self.assertTemplateUsed(response, template_name='registration/login.html')
    self.assertContains(response, '<a class="btn btn-outline-dark text-white" href="/users/sign_up/">Sign Up</a>')

  def test_login_with_valid_credentials(self):
    """User should be log in when enter valid credentials"""
    response = self.client.post(reverse('users:login'), self.valid_credentials, follow=True)
    self.assertEqual(response.status_code, 200)
    self.assertRedirects(response, reverse('home'))
    self.assertTrue(response.context['user'].is_authenticated)
    self.assertContains(response, '<button type="submit" class="btn btn-danger"><i class="bi bi-door-open-fill"></i> Log out</button>')

  def test_login_with_wrong_credentials(self):
    """Get error message when enter wrong credentials"""
    credentials = {
      'email': 'tester@gmail.com',
      'password': 'wrongpassword',
      'remember_me': False
    }

    response = self.client.post(reverse('users:login'), credentials, follow=True)
    self.assertEqual(response.status_code, 200)
    self.assertContains(response, 'Invalid email or password')
    self.assertFalse(response.context['user'].is_authenticated)

We need to ensure that these tests are failing at this stage.

2.2 Create a login view

In the users/views.py file at the bottom of the file add the code below:

# -- other code 
from .forms import CustomUserCreationForm, LoginForm
from django.contrib.auth import get_user_model, views
# -- other code

class CustomLoginView(views.LoginView):
  form_class = LoginForm
  redirect_authenticated_user = True
  authentication_form = LoginForm
  template_name = 'registration/login.html'

  def form_valid(self, form):
    remember_me = form.cleaned_data.get('remember_me')

    if not remember_me:
      # set session expiry to 0 seconds. So it will automatically close the session after the browser is closed.
      self.request.session.set_expiry(0)
      # Set session as modified to force data updates/cookie to be saved.
      self.request.session.modified = True
    return super(CustomLoginView, self).form_valid(form)

In the code above, we accomplish the following:

Set the form_class Attribute: We specify our custom LoginForm as the form_class attribute since we are no longer using the default AuthenticationForm.
Override the form_valid Method: We override the form_valid method, which is called when valid form data has been posted. This allows us to implement custom behaviour after the user has successfully logged in.
Handle Session Expiration: If the user does not check the remember_me box, the session will expire automatically when the browser is closed. However, if the remember_me box is checked, the session will last for the duration defined in settings.py. The default session length is two weeks, but we can modify this using the SESSION_COOKIE_AGE variable in settings.py. For example, to set the cookie age to 7 days, we can add the following line to our settings:

# blog_app/settings.py
SESSION_COOKIE_AGE = 60 * 60 * 24 * 7

To connect your custom login functionality and allow users to access the login page, we’ll define URL patterns in the users/urls.py file. This file will map specific URLs (/log_in/ in this case) to the corresponding views (CustomLoginView). Additionally, we'll include a path for the logout functionality using Django's built-in LogoutView.

# users/urls.py

# -- other code
from django.contrib.auth import views as auth_views
from . import views

app_name = 'users'
urlpatterns = [
  path('log_in/', views.CustomLoginView.as_view(), name='login' ), # new line
  path('sign_up/', views.SignUpView.as_view(), name='signup'),
  path('log_out/', auth_views.LogoutView.as_view(), name='logout'),# new line
]

Everything seems to be in order, but we should specify where to redirect users upon successful login and logout. To do this, we will use the LOGIN_REDIRECT_URL and LOGOUT_REDIRECT_URL settings. At the bottom of your blog_app/settings.py file, add the following lines to redirect users to the homepage:

# django_project/settings.py
LOGIN_REDIRECT_URL = '/'
LOGOUT_REDIRECT_URL = '/'

Now that we have the login URL let’s update our SignUpView in the users/views.py file to redirect to the login page when sign-up is successful.

# users/views.py
class SignUpView(CreateView):
  form_class = CustomUserCreationForm
  model = User
  success_url = reverse_lazy('users:login') # Updated line
  template_name = 'registration/signup.html'

We will also update our SignUpTexts, specifically the test_signup_correct_data(self), to reflect the new behaviour and ensure that our changes are properly tested.

# users/tests/test_views.py
  def test_signup_correct_data(self):
    """User should be saved when a correct data is provided"""
    response = self.client.post(reverse('users:signup'), data={
      'full_name': self.full_name,
      'email': self.email,
      'bio': self.bio,
      'password1': self.password,
      'password2': self.password
    })

    self.assertRedirects(response, reverse('users:login')) # Updated line
    users = User.objects.all()
    self.assertEqual(users.count(), 1)
    self.assertNotEqual(users[0].password, self.password)

2.3 Create a template for Login

Then create a users/templates/registration/login.html file with your text editor and include the following code:

{% extends 'layout.html' %}
{% block page %}
  Login
{% endblock %}
{% block content %}
<div class="container mt-3">
  <div class="row justify-content-center">
    <div class="col-lg-5">
      <div class="card shadow-lg border-0 rounded-lg mt-3 mb-3">
        <div class="card-header justify-content-center">
          <h3 class="font-weight-light my-1 text-center">Sign In</h3>
        </div>
        {% if form.errors %}
          {% for field, message in form.errors.items %}
            <div class="alert alert-danger alert-dismissible fade show" role="alert">
              {{message|first}}
              <button type="button" class="btn-close" data-bs-dismiss="alert" aria-label="Close"></button>
            </div>
          {% endfor %}
        {% endif %}
        <form method="POST" class="card-body">
          <div class="mb-3">
            <label for="id_email" class="form-label">Email address</label>
            {{form.email}}
          </div>
          <div class="mb-3">
            <label for="password" class="form-label">Password</label>
            {{form.password}}
          </div>
          <div class="mb-3">
            {{form.remember_me}}
            <label>Remember me</label>
          </div>
          <div class="mb-3">
            <button name="login" class="col-md-12 btn bg-secondary bg-gradient text-white">Sign in</button>
          </div>
        </form>
        <div class="card-footer text-center">
          <div class="small">
            <a href="{% url 'users:signup' %}">Don't have an account yet? Go to signup</a><br>
            <a href="#"><i>Forgot Password?</i></a>
          </div>
        </div>
      </div>
    </div>
  </div>
</div>
{% endblock %}

We will add the Forgot Password functionality later in this series but now it’s just a dead link.

Now, let us update our layout.html template to include the login, sign-up and logout links.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>{% block page %}{% endblock %} | Blog App</title>
  <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-QWTKZyjpPEjISv5WaRU9OFeRpok6YctnYmDr5pNlyT2bRjXh0JMhjY6hW+ALEwIH" crossorigin="anonymous">
  <link href="https://cdn.jsdelivr.net/npm/bootstrap-icons/font/bootstrap-icons.css" rel="stylesheet">
</head>
<body>
  <nav class="navbar navbar-expand navbar-dark bg-primary bg-gradient">
    <div class="container-fluid">
      <a class="navbar-brand" href="{% url 'home' %}">Blog App</a>
      <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbarScroll" aria-controls="navbarScroll" aria-expanded="false" aria-label="Toggle navigation">
        <span class="navbar-toggler-icon"></span>
      </button>
      <div class="collapse navbar-collapse" id="navbarScroll">
        <ul class="navbar-nav me-auto my-2 my-lg-0 navbar-nav-scroll" style="--bs-scroll-height: 100px;">
          <li class="nav-item">
            <a class="nav-link active" aria-current="page" href="{% url 'home' %}">Home</a>
          </li>
          <li class="nav-item">
            <a class="nav-link" href="{% url 'about' %}">About</a>
          </li>
        </ul>
        {% if user.is_authenticated %}
        <ul class="navbar-nav">
          <li class="nav-item me-3" style="cursor: pointer">
            <i class="bi bi-person-circle fs-2 text-white" title="{{user.full_name}}"></i>
          </li>
          <li class="nav-item">
            <form class="mt-1" action="{% url 'users:logout' %}" method="post">
              {% csrf_token %}
              <button type="submit" class="btn btn-danger"><i class="bi bi-door-open-fill"></i> Log out</button>
            </form>
          </li>
        </ul>
        {% else %}
        <ul class="navbar-nav">
          <li class="nav-item me-2">
            <a class="btn btn-outline-dark text-white" href="{% url 'users:signup' %}">Sign Up</a>
          </li>
          <li class="nav-item">
            <a class="btn btn-outline-dark text-white" href="{% url 'users:login' %}">Sign In</a>
          </li>
        </ul>
        {% endif %}
      </div>
    </div>
  </nav>
  {% block content %}
  {% endblock %}
  <footer></footer>
  <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/js/bootstrap.bundle.min.js" integrity="sha384-YvpcrYf0tY3lHB60NNkmXc5s9fDVZLESaAA55NDzOxhy9GkcIdslK1eN7N6jIeHz" crossorigin="anonymous"></script>
</body>
</html>

In our template, we check whether the user is authenticated. If the user is logged in, we display the log-out link and the user's full name. Otherwise, we show the sign-in and sign-up links.
Now let's run all the tests

(.venv)$ python3 manage.py test
Found 22 test(s).
Creating test database for alias 'default'...
System check identified no issues (0 silenced).
......................
----------------------------------------------------------------------
Ran 22 tests in 9.942s
OK
Destroying test database for alias 'default'...

3. Test if everything is working as it should in our browser

Now that we've configured the login and logout functionality, it's time to test everything in our web browser. Let's start the development server

(.venv)$ python3 manage.py runserver

Navigate to the registration page and enter valid credentials. After a successful registration, you should be redirected to the login page. Enter the user information in the login form, and once logged in, click the logout button. You should then be logged out and redirected to the homepage. Finally, verify that you're no longer logged in and that the sign-up and sign-in links are displayed again.
Everything works perfectly, but I noticed that when a user is logged in and visits the registration page at http://127.0.0.1:8000/users/sign_up/, they still have access to the registration form. Ideally, once a user is logged in, they shouldn't be able to access the sign-up page.

This behaviour can introduce several security vulnerabilities into our project. To address this, we need to update the SignUpView to redirect any logged-in user to the home page.
But first, let's update our LoginTest to add a new test that covers the scenario. So in the users/tests/test_views.py add this code.

# users/tests/test_views.py
class LoginTests(TestCase):
  # -- other test cases

  def test_visiting_registration_after_logged_in(self):
    """
    Logged in user should be redirected when visiting the registration page
    """
    response = self.client.post(reverse('users:login'), self.valid_credentials, follow=True)
    self.assertTrue(response.context['user'].is_authenticated)

    sign_up_resp = self.client.get(reverse('users:signup'))
    self.assertRedirects(sign_up_resp, reverse('home'))

Now, we can update our SignUpView

# users/views.py
from django.conf import settings # new line
...

class SignUpView(CreateView):
  form_class = CustomUserCreationForm
  redirect_authenticated_user = True
  model = User
  success_url = reverse_lazy('users:login')
  template_name = 'registration/signup.html'

  def dispatch(self, request, *args, **kwargs):
    # Check if a user is already authenticated
    if request.user.is_authenticated:
      # Redirect the user to the login redirect url
      return redirect(f'{settings.LOGIN_REDIRECT_URL}')
    return super().dispatch(request, *args, **kwargs)

In the code above, we override the dispatch() method of our SignUpView to redirect any user who is already logged in and tries to access the registration page. This redirect will use the LOGIN_REDIRECT_URL set in our settings.py file, which in this case, points to the home page.
Okay! Once again, let's run all our tests to confirm that our updates are working as expected

(.venv)$ python3 manage.py test
Found 23 test(s).
Creating test database for alias 'default'...
System check identified no issues (0 silenced).
.......................
----------------------------------------------------------------------
Ran 23 tests in 11.215s

OK
Destroying test database for alias 'default'...

I know there's much more to accomplish, but let's take a moment to appreciate what we've accomplished so far. Together, we've set up our project environment, connected a PostgreSQL database, and implemented a secure user registration and login system for our Django blog application. In the next part, we'll dive into creating a user profile page, enabling users to edit their information, and password reset! Stay tuned for more exciting developments as we continue our Django blog app journey!

Your feedback is always valued. Please share your thoughts, questions, or suggestions in the comments below. Don't forget to like, leave a comment, and subscribe to stay updated on the latest developments!

Guide to Building a Complete Blog App with Django using TDD Methodology and PostgreSQL (Part 2): User registration

AVLESSI Matchoudi — Thu, 17 Oct 2024 10:23:04 +0000

Welcome back, everyone! This article is a continuation of the guide on building a complete blog app with Django. If you haven’t read the first part of this series yet, I recommend checking it out before proceeding. In this part, we’ll dive into implementing authentication functionality, focusing on setting up secure user registration in Django. Stay tuned for the next part, where we’ll continue building out the app.

In this series, we are building a complete blog application, guided by the following Entity-Relationship Diagram (ERD). For this time, our focus will be on setting up secure user registration. If you find this content helpful, please like, comment, and subscribe to stay updated when the next part is released.

In this article, I’m using Linux. For Mac users, the commands will be the same. If you’re using Windows, I’ll be providing both the Linux/Mac and Windows commands where there are differences, so you can follow along easily regardless of your operating system.

Prerequisites

Have a basic understanding of Django
Have a basic knowledge of Python
PostgreSQL installed on your machine

Okay, let’s get started !!

            ##########

For any authentication system, a User model is essential. That’s why Django’s authentication system includes a default built-in User model. which comes with these primary attributes:

username
password
email
first_name
last_name

However, these attributes might not always align with the specific requirements of a project. As in our case, you can notice that they differ from the User attributes in our application’s ERD.

To address this, Django allows us to override the default User model with a customized one that better suits our application’s needs. This can be achieved through inheritance or by creating a new User model. In this tutorial, we’ll explore the latter approach, where we’ll create a new customised User model that includes attributes specific to our blog application.

While it’s possible to customize Django’s default User model, doing so introduces additional complexity to an already robust system. It’s recommended to stick with the default model whenever possible unless you know what you’re doing or project-specific requirements explicitly demand customization.

Now that we understand what needs to be done, let’s create our first app to implement the custom User model.

1. Create an app named `Users` within our project

Make sure you’re in the same directory as manage.py and type this command:

# macOS/Linux
(.venv)$ python3 manage.py startapp users

# Windows
(.venv)$ python manage.py startapp users

This will create a users directory, which will be structured as follows:

users/
    migrations/
    __init__.py
    admin.py
    apps.py
    models.py
    tests.py
    views.py

Next, we will add the newly created Users app to the project’s INSTALLED_APPS setting located in the blog_app/settings.py file. This will inform Django that our app is active and ready to be used.

# django_project/settings.py
INSTALLED_APPS = [
     # -- other code
    "users.apps.UsersConfig",  # <== new app
]

2. Create test cases for the User model

Django uses the unit test module’s built-in test discovery mechanism to automatically find and run tests within your project. It will locate tests in any file named with the pattern test*.py under the current working directory.

Unlike the first part of this tutorial, we’ll create a separate tests module to house our test code as we promised at the beginning of the series to follow the best practices. This organization help to improve code readability, maintainability, and reusability.

We will now create a tests module in the users directory for our test cases, with separate files for models, views, forms, and any other components that need testing. These files typically follow the naming conventiontest_<component_name>.py. Thus, our test directory structure will look like this:

users/
  /tests/
    __init__.py
    test_models.py
    test_forms.py
    test_views.py

The __init__.py file should be an empty file. In Python, an empty __init__.py file signifies that the directory is a package and can contain modules. Next, we'll remove the users/tests.py file, as we'll be organizing our tests into separate files in the users directory.

Now that we have a solid understanding of the setup, let’s begin writing our tests for the User model using the TDD methodology. Open the users/tests/test_models.py file and add the following test cases.

# users/tests/test_models.py
from django.test import TestCase
from django.contrib.auth import get_user_model
User = get_user_model()

class UserTest(TestCase):

  def setUp(self):
    self.user_test = {
      'full_name': 'Tester',
      'email': 'test@gmail.com',
      'bio': 'Biography of Tester',
      'password': 'user12345',
    }
    self.saved = self.create_user(self.user_test)

  def create_user(self, data):
    return User.objects.create_user(**data)

  def test_user_creation(self):
    """User creation is successful when all the required field are fill"""
    self.assertTrue(isinstance(self.saved, User))
    self.assertEqual(str(self.saved), self.user_test['email'])

  def test_required_fields(self):
    """Create a user with a empty email or password should raise an Error"""
    fake_user = {
      'full_name': 'fake',
      'email': '',
      'bio': 'fake bio',
      'password': 'user12345'
    }

    with self.assertRaises(TypeError):
      User.objects.create_user()
    with self.assertRaises(TypeError):
      User.objects.create_user(email='tester1@gmail.com')
    with self.assertRaises(ValueError) as context:
      self.create_user(fake_user)
    self.assertEqual(str(context.exception), "The Email must be set")

  def test_password_encripted(self):
    """Saved password in the database should be different from from provided password"""
    self.assertNotEqual(self.saved.password, self.user_test['password'])

  def test_creation_superuser(self):
    super_user = User.objects.create_superuser(email='superuser@gmail.com', password='super12345', bio='User admin')
    self.assertTrue(super_user.is_superuser)

In the code above, we import the get_user_model function to retrieve the custom user model that we will define soon. We have also created tests to ensure that a user is created successfully when the correct credentials are provided, check the required fields, verify that the password is encrypted after the user has been saved, and finally, test the creation of a superuser.

DO NOT apply the migrations. Remember: You must create the custom user model before you apply your first migration.

3. Create a custom user model

3.1 Create a Model Manager

To ensure email serves as the unique identifier for user authentication, we’ll create a custom Manager. This can be achieved by subclassing BaseUserManager from Django. The custom Manager will define the logic for creating and interacting with users in our application.

Let's create a new file named managers.py within the users directory and add the following code:

# users/managers.py
from django.contrib.auth.base_user import BaseUserManager
from django.utils.translation import gettext_lazy as _

class CusmtomUserManager(BaseUserManager):
  """
  Use the email field as the unique identifiers for the authentication
  """
  def create_user(self, email, password, **extra_fields):
    if not email:
      raise ValueError(_("The Email must be set"))
    email = self.normalize_email(email)
    user = self.model(email=email, **extra_fields)
    user.set_password(password)
    user.save()
    return user

  def create_superuser(self, email, password, **extra_fields):
    """
    Create a SuperUser with email and password
    """
    extra_fields.setdefault("is_superuser", True)

    if extra_fields.get("is_superuser") is not True:
      raise ValueError(_("Superuser must have is_superuser=True"))

    return self.create_user(email, password, **extra_fields)

In our custom manager model, we have overridden the create_user and create_superuser methods. The create_user method will now accept an email argument instead of a username argument, and the create_superuser method will also use email instead of a username.

3.2 Create a Custom Model

Now, let’s create our User model in the models.py file within the users directory to ensure that our previous tests pass.

# users/models.py
from django.db import models
from django.contrib.auth.models import AbstractBaseUser, PermissionsMixin
from django.utils.translation import gettext_lazy as _
from PIL import Image
from .managers import CustomUserManager

class CustomUser(AbstractBaseUser, PermissionsMixin):
  full_name = models.CharField(_('full name'), blank=False, null=False, max=200, verbose_name='Full Name')
  email = models.EmailField(_('email address'), unique=True, max_length=200)
  photo = models.ImageField(upload_to='profiles', blank=True, null=True, verbose_name='Photo')
  bio = models.TextField(blank=True, null=True, verbose_name='Biography')
  posts_counter = models.PositiveIntegerField(default=0, null=False, verbose_name='Posts Counter')
  updated_at = models.DateTimeField(autho_now=True)
  created_at =  models.DateTimeField(auto_now_add=True)

  USERNAME_FIELD = 'email'
  REQUIRED_FIELDS = []

  objects = CustomUserManager()

  def save(self, *args, **kwargs):
    """
    Overwrite the default method save() to resize the profile picture
    before save using Pillow.
    """
    super().save()

    if self.photo:
      img = Image.open(self.photo.path)

      if img.height > 80 or img.width > 80:
        img_size = (80, 80)
        img.thumbnail(img_size)
        img.save(self.photo.path)

  class Meta:
    """
    Set the table name to follow our ERD
    """
    db_table = 'users'

  def __str__(self):
    return self.email

In the above code, we:

Created a new model called CustomUser that subclasses AbstractBaseUser which allows us to create our own model attributes
Added the users' table attributes to our model
Set the USERNAME_FIELD -- which defines the unique identifier for the User model to email
Specified that all objects for the class come from the CustomUserManager
Resized the profile picture to have 80px as height and 80px as width and saved the pictures in the media/profiles directory which will be soon set up in the setting.
Named our table users to align with the provided ERD.

3.3 Settings

We’ll add the following line to our settings.py file to inform Django to use our custom user model for user authentication instead of the default built-in model.

# blog_app/settings.py
AUTH_USER_MODEL = "users.CustomUser"

This line sets users.CustomUser as the active user model within our project. Additionally, we'll configure Django's media storage by adding these lines to settings.py:

# blog_app/settings.py
import os
...
MEDIA_ROOT = os.path.join(BASE_DIR, 'media')
MEDIA_URL = '/media/'

MEDIA_ROOT specifies the server-side path where uploaded media files in our case our user profile picture will be stored on our computer
MEDIA_URL defines the URL prefix that the browser will use to access uploaded media files over HTTP (e.g., http://yourdomain.com/media/).

Finally, to ensure that uploaded pictures are only saved to the media directory during development, we’ll add some code to our blog_app/urls.py file. This configuration allows the development server to serve media files directly while keeping media serving disabled in production for security and performance reasons.

# blog_app/urls.py
# -- other code
from django.conf import settings               # new line
from django.conf.urls.static import static     # new line

urlpatterns = [
    # --  application paths
]

if settings.DEBUG:
  urlpatterns += static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT) # new line

3.4 Run migrations

Now, we can create and apply the migrations, which will create a new database that uses the custom user model.

# Linux/MacOs
(.venv)$ python3 manage.py makemigrations users

# Windows
(.venv)$ python manage.py makemigrations users

We should see something similar to the following output:

Migrations for 'users':
  users/migrations/0001_initial.py
    + Create model CustomUser

We can run the migration to create a database with the tables but first, let's see what SQL that migration would run.

# Linux/MacOs
(.venv)$ python3 manage.py sqlmigrate users 0001

# Windows
(.venv)$ python manage.py sqlmigrate users 0001

From the output, we can see that Django will create a users table with all the attributes in our ERD.
Our migration file looks like this:

# Generated by Django 5.1.1 on 2024-10-08 22:54

from django.db import migrations, models

class Migration(migrations.Migration):

    initial = True

    dependencies = [
        ('auth', '0012_alter_user_first_name_max_length'),
    ]

    operations = [
        migrations.CreateModel(
            name='CustomUser',
            fields=[
                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
                ('password', models.CharField(max_length=128, verbose_name='password')),
                ('last_login', models.DateTimeField(blank=True, null=True, verbose_name='last login')),
                ('is_superuser', models.BooleanField(default=False, help_text='Designates that this user has all permissions without explicitly assigning them.', verbose_name='superuser status')),
                ('full_name', models.CharField(max_length=200, verbose_name='full name')),
                ('email', models.EmailField(max_length=200, unique=True, verbose_name='email address')),
                ('photo', models.ImageField(blank=True, null=True, upload_to='profiles', verbose_name='Photo')),
                ('bio', models.TextField(blank=True, null=True, verbose_name='Biography')),
                ('posts_counter', models.PositiveIntegerField(default=0, verbose_name='Posts Counter')),
                ('updated_at', models.DateTimeField(auto_now=True)),
                ('created_at', models.DateTimeField(auto_now_add=True)),
                ('groups', models.ManyToManyField(blank=True, help_text='The groups this user belongs to. A user will get all permissions granted to each of their groups.', related_name='user_set', related_query_name='user', to='auth.group', verbose_name='groups')),
                ('user_permissions', models.ManyToManyField(blank=True, help_text='Specific permissions for this user.', related_name='user_set', related_query_name='user', to='auth.permission', verbose_name='user permissions')),
            ],
            options={
                'db_table': 'users',
            },
        ),
    ]

We can now, safely run the migration to create our database

# Linux/MacOs
(.venv)$ python3 manage.py migrate

# windows
(.venv)$ python manage.py migrate

If you encounter any errors at this stage, please make sure you've followed all the steps in the first part of this series.
Now, let's make sure our tests are passing

# Linux/MacOs
(.venv)$ python3 manage.py test

# Windows
(.venv)$ python manage.py test

The output should be similar to the following:

Found 6 test(s).
Creating test database for alias 'default'...
System check identified no issues (0 silenced).
......
----------------------------------------------------------------------
Ran 6 tests in 2.746s

OK
Destroying test database for alias 'default'...

3.5 Remove Django built-in admin application (optional)

When we create a new project, Django automatically adds django.contrib.admin to the INSTALLED_APPS. While the Admin app is very useful for backend administration, it is not a requirement for our project, and we won't be using it. So to adhere to the YAGNI (You Aren't Gonna Need It) principle in software development, I recommend removing it. This will help keep our project lean and focused on the essential features.
First, remove or comment out django.contrib.admin from the INSTALLED_APPS setting in the blog_app/settings.py file.

# blog_app/setting.py
# Application definition

INSTALLED_APPS = [
    # 'django.contrib.admin',
    # -- other codes
    'users.apps.UsersConfig',
]

Next, remove or comment out the URL path in the blog_app/urls.py file

# blog_app/urls.py
# from django.contrib import admin
...

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

4. Create a Custom form for our model

4.1 Create test

Following our TDD approach, let's create tests for the custom form we'll use for user registration. In the tests directory, create a new file named test_forms.py and add these test cases:

# users/tests/test_forms.py
from django.test import TestCase
from users.forms import CustomUserCreationForm

class CustomUserCreationFormTest(TestCase):
  def setUp(self):
    self.full_name = 'First Name'
    self.password = 'test12345'
    self.email = 'test@gmail.com'
    self.bio = 'Tester biography'

  def test_email_validation(self):
    """Form should raise error when email is not a valid email"""
    data = {
      'full_name': self.full_name,
      'password1': self.password,
      'password2': self.password,
      'email': 'testegmail.com',
      'bio': self.bio,
    }
    form = CustomUserCreationForm(data)
    self.assertFalse(form.is_valid())
    self.assertEqual(form.errors['email'], ["Enter a valid email address."])

  def test_name_validation(self):
    """Form should raise error when the full name is not first and last name"""
    data = {
      'full_name': 'Fake',
      'password1': self.password,
      'password2': self.password,
      'email': 'testegmail',
      'bio': self.bio,
    }
    form = CustomUserCreationForm(data)
    self.assertFalse(form.is_valid())
    self.assertEqual(form.errors['full_name'], ["Enter a first and last name."])

  def test_password_confirmation(self):
    """Form should raise error when password do not match"""
    data = {
      'full_name': self.full_name,
      'password1': self.password,
      'password2': 'newowkdkdkd',
      'email': self.email,
      'bio': self.bio,
    }
    form = CustomUserCreationForm(data)
    self.assertFalse(form.is_valid())
    self.assertEqual(form.errors['password2'], ["The two password fields didn't match."])

  def test_bio_validation(self):
    """Form should raise error when the bio is less than 4 characters"""
    data = {
      'full_name': self.full_name,
      'password1': self.password,
      'password2': self.password,
      'email': self.email,
      'bio': 'th',
    }
    form = CustomUserCreationForm(data)
    self.assertFalse(form.is_valid())
    self.assertEqual(form.errors['bio'], ["The bio must be at least 4 characters long. Please provide more details."])

  def test_form_validation(self):
    """Form should be valid"""
    data = {
      'full_name': self.full_name,
      'password1': self.password,
      'password2': self.password,
      'email': self.email,
      'bio': self.bio,
    }
    form = CustomUserCreationForm(data)
    self.assertTrue(form.is_valid())

You may notice a few error flags in your text editor; that's perfectly normal since we haven't created the form yet.

4.2 Create forms

Django provides default forms UserCreationForm and UserChangeForm, for creating and updating user models. Since we're using a custom CustomUser model, we need to create custom forms that specifically work with our model. To achieve this, we'll create subclasses of UserCreationForm and UserChangeForm in a new file called forms.py within the users directory.

# users/forms.py
from django.contrib.auth.forms import UserCreationForm, UserChangeForm
from django.contrib.auth import get_user_model
from .models import CustomUser
from django import forms
User = get_user_model()
import re

class CustomUserCreationForm(UserCreationForm):
  """
  Set the password fields to the default messages
  """
  full_name = forms.CharField(
    widget=forms.TextInput(attrs={'placeholder': 'Enter Full name', 'class': 'form-control'})
  )
  email = forms.CharField(
    widget=forms.TextInput(attrs={'placeholder': 'Enter email', 'class': 'form-control'})
  )
  bio = forms.CharField(
    widget=forms.Textarea(attrs={'placeholder': 'Enter author biography', 'class': 'form-control', 'rows': 5})
  )
  password1 = forms.CharField(
    label='Password', 
    widget=forms.PasswordInput(attrs={'placeholder': 'Enter Password', 'class': 'form-control'})
  )
  password2 = forms.CharField(
    label='Confirm Password', 
    widget=forms.PasswordInput(attrs={'placeholder': 'Confirm Password', 'class': 'form-control'})
  )

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

  def clean_full_name(self):
    full_name = self.cleaned_data.get('full_name')
    regex = r"^[a-zA-Z]{2,}(?:\s[a-zA-Z]{2,}(?:-[a-zA-Z]{2,})*)+$"
    if not re.match(regex, full_name):
      raise forms.ValidationError("Enter a first and last name.")
    return full_name

  def clean_email(self):  
    email = self.cleaned_data.get('email') 
    user = User.objects.filter(email=email)
    if user.exists():  
      raise forms.ValidationError("Email Already Exist")  
    return email

  def clean_bio(self):
    bio = self.cleaned_data.get('bio')
    if not len(bio) >= 4:
      raise forms.ValidationError("The bio must be at least 4 characters long. Please provide more details.")
    return bio

class CustomUserChangeForm(UserChangeForm):
  class Meta:
    model = CustomUser
    fields = ('full_name', 'photo', 'bio',)

In our custom user creation form, we implement several validation checks to ensure data integrity and prevent invalid user data from being entered.
The clean_full_name method verifies that a correct full name with both first and last names is entered.
The clean_bio method ensures that the user's biography is at least 4 characters long.
Finally, the clean_email method checks if the provided email address is not already present in our database to prevent duplicate email addresses from being registered.

Now, When we run our test we should see this:

(.venv)$ python3 manager.py test
Found 11 test(s).
Creating test database for alias 'default'...
System check identified no issues (0 silenced).
...........
----------------------------------------------------------------------
Ran 11 tests in 2.918s

OK
Destroying test database for alias 'default'...

5. Create views for the model

5.1 Create test cases for the views

Navigate to the users/tests directory and create a new file named test_views.py. This file will house the tests for our custom user views.

# users/tests/test_views.py
from django.test import TestCase
from django.urls import reverse
from django.contrib.auth import get_user_model
User = get_user_model()

class SignUpPageTests(TestCase):
  def setUp(self) -> None:
    self.full_name = 'test user'
    self.email = 'testuser@email.com'
    self.bio = 'test user bio'
    self.password = 'fake12345'

  def test_signup_page_view(self):
    """The Signup url should render the 'registration/signup.html' template"""
    response = self.client.get(reverse('users:signup'))
    self.assertEqual(response.status_code, 200)
    self.assertTemplateUsed(response, template_name='registration/signup.html')

  def test_signup_correct_data(self):
    """User should be saved when a correct data is provided"""
    response = self.client.post(reverse('users:signup'), data={
      'name': self.full_name,
      'email': self.email,
      'bio': self.bio,
      'password1': self.password,
      'password2': self.password
    })

    users = User.objects.all()
    self.assertEqual(users.count(), 1)
    self.assertNotEqual(users[0].password, self.password)

  def test_signup_fake_data(self):
    """User shouldn't be save with missing email field"""
    response = self.client.post(reverse('users:signup'), data={
      'name': self.full_name,
      'email': '',
      'bio': self.bio,
      'password1': self.password,
      'password2': self.password
    })

    self.assertEqual(response.status_code, 200)
    users = User.objects.all()
    self.assertEqual(users.count(), 0)

All the tests above will fail; we should see that 14 tests are run, with 3 of them failing.

5.2 Create a view for sign-up

In the users directory open the file named views.py and add this code:

# users/views.py
from django.views.generic import CreateView
from django.urls import reverse_lazy
from .forms import CustomUserCreationForm
from django.contrib.auth import get_user_model
User = get_user_model()

class SignUpView(CreateView):
  form_class = CustomUserCreationForm
  model = User
  success_url = reverse_lazy('home')
  template_name = 'registration/signup.html'

_ Model is to tell our sign-up view to use our custom model
_ Success_url is to redirect after the operation is successful. We set it to the home page for now
_ template_name as you might already guess is to tell which template should be used

6. Create a URL for our view

Create a new file named urls.py in the users directory to define URLs for user-related functionalities. In this file, add the following code:

# users/urls.py
from django.urls import path
from . import views # Import views from the current users app

app_name = 'users'
urlpatterns = [
  path('sign_up/', views.SignUpView.as_view(), name='signup'),
]

This code defines a URL pattern for the signup view (SignUpView). The app_name is set to 'users' for easier namespacing of URLs within our application.
Then, include the users' URLs in the project's main URLs file:

# blog_app/urls.py
from django.urls import path, include # Import the include function

# ... other imports

urlpatterns = [
    # ... other URL patterns
    path('users/', include('users.urls')), # Include users app URLs
]
# ... other code

7. Create a Signup template

First, create a directory called templates in your users directory. Within the templates directory we have just created, create another directory called registration, and within that create a file called signup.html.
In other words, our template should be at users/templates/registration/signup.html and add this code.

{% extends 'layout.html' %}

{% block page %} Register {% endblock page%}
{% block content %}
<div class="container my-3 p-3">
  <div class="row justify-content-center">
    <div class="col-lg-6">
      <div class="card shadow-lg border-0 rounded-lg mt-0 mb-5">
        <div class="card-header">
          <h3 class="font-weight-light my-4 text-center">Create Account</h3>
        </div>
        <form method="POST" class="row g-3 card-body">
          {% csrf_token %}
          {% if form.errors %}
            {% for field, message in form.errors.items %}
              <div class="alert alert-danger alert-dismissible fade show" role="alert">
                <strong>{{field}}:</strong> {{message|first}}
                <button type="button" class="btn-close" data-bs-dismiss="alert" aria-label="Close"></button>
              </div>
            {% endfor %}
          {% endif %}
          <div class="col-md-6">
            <label class="form-label">Email Address</label>
            {{ form.email }}
          </div>
          <div class="col-md-6">
            <label class="form-label">Full Name</label>
            {{ form.full_name }}
          </div>
          <div class="col-12">
            <label class="form-label">Biography</label>
            {{ form.bio }}
          </div>
          <div class="form-group col-md-6">
            <label for="password1">Password</label>
            <div class="input-group mt-2">
              {{ form.password1 }}
              <div class="input-group-append">
                <span class="input-group-text">
                  <i class="bi bi-eye-slash" id="togglePassword1" style="cursor: pointer;"></i>
                </span>
              </div>
            </div>
          </div>
          <div class="form-group col-md-6">
            <label for="password2">Confirm Password</label>
            <div class="input-group mt-2">
              {{ form.password2 }}
              <div class="input-group-append">
                <span class="input-group-text">
                  <i class="bi bi-eye-slash" id="togglePassword2" style="cursor: pointer;"></i>
                </span>
              </div>
            </div>
          </div>
          <div class="form-group mt-4 mb-0">
              <button type="submit" class="col-md-12 btn bg-secondary bg-gradient text-white">Sign Up</button><br><br>
          </div>
        </form>
        <div class="card-footer text-center">
          <a href="#" class="small">Have an account? Go to Sign in</a>
      </div>
      </div>
    </div>
  </div>
</div>
{% endblock content %}

Next, let's add Sign up link to our layout in the templates/layout.html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>{% block page %}{% endblock %} | Blog App</title>
  <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-QWTKZyjpPEjISv5WaRU9OFeRpok6YctnYmDr5pNlyT2bRjXh0JMhjY6hW+ALEwIH" crossorigin="anonymous">
  <link href="https://cdn.jsdelivr.net/npm/bootstrap-icons/font/bootstrap-icons.css" rel="stylesheet">
</head>
<body>
  <nav class="navbar navbar-expand-lg navbar-dark bg-primary">
    <div class="container-fluid">
      <a class="navbar-brand" href="{% url 'home' %}">Blog App</a>
      <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbarScroll" aria-controls="navbarScroll" aria-expanded="false" aria-label="Toggle navigation">
        <span class="navbar-toggler-icon"></span>
      </button>
      <div class="collapse navbar-collapse" id="navbarScroll">
        <ul class="navbar-nav me-auto my-2 my-lg-0 navbar-nav-scroll" style="--bs-scroll-height: 100px;">
          <li class="nav-item">
            <a class="nav-link active" aria-current="page" href="{% url 'home' %}">Home</a>
          </li>
          <li class="nav-item">
            <a class="nav-link" href="{% url 'about' %}">About</a>
          </li>
          <li class="nav-item">
            <a class="nav-link" href="{% url 'users:signup' %}">Register</a>
          </li>
        </ul>
        <form class="d-flex">
          <input class="form-control me-2" type="search" placeholder="Search" aria-label="Search">
          <button class="btn btn-outline-light" type="submit">Search</button>
        </form>
      </div>
    </div>
  </nav>
  {% block content %}
  {% endblock %}
  <footer></footer>
  <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/js/bootstrap.bundle.min.js" integrity="sha384-YvpcrYf0tY3lHB60NNkmXc5s9fDVZLESaAA55NDzOxhy9GkcIdslK1eN7N6jIeHz" crossorigin="anonymous"></script>
</body>
</html>

We include the bootstrap Icon link in the <head></head> tag of our layout.hml file to have the eye icon in our sign-up form.
Now, let's run our tests to make sure their passing

(.venv)$ python3 manager.py test
Found 14 test(s).
Creating test database for alias 'default'...
System check identified no issues (0 silenced).
..............
----------------------------------------------------------------------
Ran 14 tests in 3.644s

OK
Destroying test database for alias 'default'...

Let's run the server to check what our sign-up form looks like.

(.venv)$ python3 manager.py runserver

Now, navigate to the http://127.0.0.1:8000/users/sign_up/

This looks pretty good, right!! Now, when we register a new user, we are successfully redirected to the homepage. However, this behaviour is not very practical, as you typically want to either automatically log in to the user upon registration or redirect them to the login page. We will discover this in the next part of this tutorial, where we'll delve into implementing the login functionality, as I feel this tutorial is becoming a bit too long.

I haven't gone into much detail for some code snippets, as I believe the code is self-explanatory. I've added comments to explain each line where necessary. However, if you need further clarification or have any questions, please don't hesitate to comment. I'm happy to provide more detailed explanations. Your feedback is always appreciated! Don't forget to like and leave a comment.

Guide to Building a Complete Blog App with Django using TDD methodology and PostgreSQL database: Installation and Setup

AVLESSI Matchoudi — Sat, 05 Oct 2024 19:02:25 +0000

One of the reasons that we love Django is because it comes with many built-in modules that make web development faster than other frameworks. Django takes care of much of the hassle of web development, so we can focus on writing our app without reinventing the wheel. However, some project requirements differ from the default model that Django provides. In this project, we’ll explore how to use a customized user model in Django to better fit specific needs while using the TDD(Test-Driven Development) methodology to ensure our code is reliable and bug-free.

In this series, we will build a complete blog application following this ERD. In this tutorial, our focus will be on setting up the development environment and installing the required packages. If you find this content helpful, please like, comment, and subscribe to stay updated when the next part is released.

In this article, I’m using Linux. For Mac users, the commands will be the same. If you’re using Windows, I’ll be providing both the Linux/Mac and Windows commands where there are differences,so you can follow along easily regardless of your operating system.

Prerequisites

Have a basic understanding of Django
Have a basic Knowledge of Python
PostgreSQL installed on your machine

Okay, let’s get started !!

First, let's create a project directory and move to the directory where we want our code to be. I named my directory blog_app_series. You can name yours whatever you want

$ mkdir blog_app_series && cd blog_app_series

I- Create a Virtual Environment

To follow Django's best practices we will create a virtual environment to isolate any dependencies and modules.

Many tools are available to create a virtual environment in Python, such as conda, virtualenv, and Python’s venv module. We will create and activate our virtual environment using ‘venv’ since it’s included in Python’s standard library from Python 3.3; therefore no need to install any external tools.

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

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

In the code above we have created and activated a virtual environment named “.venv”, the naming doesn’t matter it can be named anything (“blog_env”, “myenv”, “venv”); however, there is growing consensus in Python community that “.venv” is the clearest approach.

If you see (.venv) prefixed to your command prompt, the virtual environment is active.

II- Install Django

Now, let's install Django in the virtual environment that we created.

Make sure you have the (.venv) prefixed to your command prompt and enter the command below:

# macOS/Linux
(.venv) $ python3 -m pip install django

# windows
(.venv) $ python -m pip install django

This will install the last version of Django. We can run ‘pip freeze’, to check the Django’s version installed in our virtual environment.

(.venv)$ pip freeze
asgiref==3.8.1
Django==5.1.1
sqlparse==0.5.1

III- Create our project

Now that Django is installed, the next step is to create our project using the management command django-admin startproject <project_name> .. This creates the skeleton of a new Django project.

Including the period ., at the end of the command, it is optional but tells Django to set up the new project in the current directory instead of creating a new one.

(.venv)$ django-admin startproject blog_app .

With the above command, we create a new project called ‘blog_app’. Our file structure will then look like this.

.venv/
blog_app/
    __init__.py
    asgi.py
    settings.py
    urls.py
    wsgi.py
manage.py

To check if everything worked successfully, let’s run the runserver command.

# macOS/Linux
(.venv) $ python3 manage.py runserver
(.venv) $ python manage.py runserver

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

That means we’ve set up everything correctly and can move on to the next step.

IV- Setting up Postgres database

By default, Django uses SQLite as the local database. However, this can be easily switched to any of the supported databases, such as PostgreSQL, MariaDB, MySQL, or Oracle. For this project, we will be using PostgreSQL, though you are welcome to choose any database that suits your needs. Django’s ORM (Object-Relational Mapping) ensures that the code remains consistent across different database backends, offering flexibility without requiring changes to your application code.

1. Create a PostgreSQL database for our project

let's open our Vs Code (VisualStudio Code). You can use any IDE or Text Editor of your desire
Then open the Vs Code terminal, because it’s more convenient to run the code in the same terminal
Activate the virtual environment in Vs Code, if it has not been activated yet.

# macOS/Linux
$ source .venv/bin/activate

# Windows
env/Scripts/activate

let’s create our database on the local machine. For macOS and Linux, you can use the following command:

# macOs/Linux
$ sudo -i -u postgres
postgres@user:~$ psql
postgres=# CREATE DATABSE blog_app_db;
postgres=# \q # to exit or quit the session
postgres@user:~$ exit # to logout from the postgres user```


In the code above, we switch to the Postgres user and connect to the PostgreSQL database to create a new database named `blog_app_db`
![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/pu19sjl9tw16aqvltrtv.png)
for Windows users, you can use pgAdmin to create your database.

### 2. Connect the database to our Django application
- Navigate to the `blog_app/settings.py` file and scroll down to the DATABASE configurations.
![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/c7hayvgoppegd3scebt6.png)
- Replace the default SQLite3 database configuration with PostgreSQL settings.



```DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': 'blog_app_db', 
        'USER': 'postgres',
        'PASSWORD': 'your_db_password',
        'HOST': '127.0.0.1', 
        'PORT': '5432',
    }
}

_NAME: The name of the database we previously created.

_USER: The database username (default is Postgres).

_PASSWORD: The password for the database. This can be omitted if no password is set for your local database.

_ HOST: The database host. This can be omitted on your local machine, as Django will default to localhost or the IP address 127.0.0.1.

_ PORT: The PostgreSQL port. This can also be omitted on your local machine, as Django will default to port 5432 which is the default port for the Postgres database.
Here is my database configuration.

Finally, we will need to install the PostgreSQL database connector library called “**psycopg2**”, which allows Django to establish a connection with the database.

(.venv) $ pip install psycopg2

Start the server to make sure everything is working correctly

Now, let’s start the server using the runserver command to ensure everything is working correctly (please do not run migrations at this stage). If you still see the ‘The install worked successfully! Congratulations!’ page, means everything is set up correctly, and we are good to go.
V- Add a home page and an about page to our application

Create a templates directory to store our templates

Let’s create a templates directory at the root of our project to store our templates.
(.venv) blog_app_series$ mkdir templates

and then tell Django where to find our templates by updating the TEMPLATES configuration in settings.py.

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

Create tests for our templates

As stated at the beginning of this tutorial, we will be following the Test-Driven Development (TDD) methodology to ensure our code is reliable and free of bugs. To get started, let’s create the ‘tests.py’ file within the ‘blog_app’ directory.

# blog_app/tests.py

from django.test import TestCase
from django.urls import reverse

class AppTemplateTests(TestCase):
  def test_home_template(self):
    """Render home.html and response status is 200"""
    response = self.client.get(reverse('home'))
    # Test if response status is ok
    self.assertEqual(response.status_code, 200)
    # Test if the correct template is used
    self.assertTemplateUsed(response, 'home.html')
    # Test if we have an h1 tags with a text
    seff.assertContains(response, '<h1>This the home page</h1>')

  def test_about_template(self):
    """Render about.html and response status is 200"""
    response = self.client.get(reverse('about'))
    # Test if response status is ok
    self.assertEqual(response.status_code, 200)
    # Test if the correct template is used
    self.assertTemplateUsed(response, 'about.html')
    # Test if we have an h1 tags with a text
    self.assertContains(response, '<h1>This the about page</h1>')

let’s run the tests with this command

# macOs/Linux
(.venv) $ python3 manage.py test

# Windows
(.venv) $ python manage.py test

From the terminal output, we can see that all our tests are failing, which is what we are expecting at this stage since we have not created the templates yet.

3. Create the URLS for the home, and about pages

At this stage, we will include both the views and URLs in the blog_app/urls.py file for simplicity. Let's start by importing TemplateView at the top of the file and defining a path that renders the appropriate template.

# blog_app/urls.py
from django.contrib import admin
from django.urls import path
from django.views.generic import TemplateView

urlpatterns = [
    path('admin/', admin.site.urls),
    path('', TemplateView.as_view(template_name='home.html'), name='home'),
    path('about/', TemplateView.as_view(template_name='about.html'), name='about'),
]

Next, we’ll create the home.html and about.html templates as referenced in the code above. However, to adhere to the DRY (Don't Repeat Yourself) principle, we'll first create a layout template to serve as a wrapper for these pages

Create a layout for our application ‘templates/layout.html’ file

<!-- templates/layout.html -->

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>{% block page %}{% endblock %} | Blog App</title>
  <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-QWTKZyjpPEjISv5WaRU9OFeRpok6YctnYmDr5pNlyT2bRjXh0JMhjY6hW+ALEwIH" crossorigin="anonymous">
</head>
<body>
  <nav class="navbar navbar-expand-lg navbar-dark bg-primary">
    <div class="container-fluid">
      <a class="navbar-brand" href="{% url 'home' %}">Blog App</a>
      <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbarScroll" aria-controls="navbarScroll" aria-expanded="false" aria-label="Toggle navigation">
        <span class="navbar-toggler-icon"></span>
      </button>
      <div class="collapse navbar-collapse" id="navbarScroll">
        <ul class="navbar-nav me-auto my-2 my-lg-0 navbar-nav-scroll" style="--bs-scroll-height: 100px;">
          <li class="nav-item">
            <a class="nav-link active" aria-current="page" href="{% url 'home' %}">Home</a>
          </li>
          <li class="nav-item">
            <a class="nav-link" href="{% url 'about' %}">About</a>
          </li>
        </ul>
        <form class="d-flex">
          <input class="form-control me-2" type="search" placeholder="Search" aria-label="Search">
          <button class="btn btn-outline-light" type="submit">Search</button>
        </form>
      </div>
    </div>
  </nav>
  {% block content %}
  {% endblock %}
  <footer></footer>
  <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/js/bootstrap.bundle.min.js" integrity="sha384-YvpcrYf0tY3lHB60NNkmXc5s9fDVZLESaAA55NDzOxhy9GkcIdslK1eN7N6jIeHz" crossorigin="anonymous"></script>
</body>
</html>

This template defines the structure and the styling of our web application. We use Bootstrap for responsive design and include a navigation bar with two navigation links: ‘Home’ and ‘About’. The links are generated dynamically using Django’s {% url 'home' %} and {% url 'about' %} template tags, which refer to the name of the URL patterns defined in the ‘blog_app/urls.py’ file.

The {% block page %}{% endblock %} is a placeholder for the page name of each page that uses the layout, and the {% block content %}{% endblock %} is a placeholder for the main content of each page that extends this layout.

Next, navigate to the ‘templates’ directory and create two new files: ‘home.html’ and ‘about.html’.

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

{% extends 'layout.html' %}

{% block page %}
  Home
{% endblock %}

{% block content %}
  <h1>This the home page</h1>
{% endblock %}

<!-- templates/about.html -->

{% extends 'layout.html' %}

{% block page %}
  About
{% endblock %}

{% block content %}
  <h1>This the about page</h1>
{% endblock %}

Both ‘home.html’, and ‘about.html’ templates inherit from the ‘layout.html’ template and customize only the page title and content block.

Now let’s run the tests we created previously to confirm that all our pages are rendering correctly.

# macOs/Linux
(.venv) $ python3 manage.py test

# Windows
(.venv) $ python manage.py test

All the tests are successful, but we can still check the results in our browser by running our server.

# macOS/Linux
(.venv) $ python manage.py runserver

# Windows
(.venv) $ python manage.py runserver

if you open your browser and navigate to 127.0.0.1:8000, you should see the text “This the home page”

and when you navigate to the About page, you should see the text “This the about page”

This article has covered a lot of ground, so we’ll wrap it up for now to keep things concise. In the next part, we’ll continue by implementing the authentication functionality, where I’ll guide you through setting up secure user login and registration with Django. Stay tuned for the next part.

** If you found this helpful, don’t forget to like and leave a comment. Your feedback is always appreciated!**

READ THE NEXT PART HERE

DEV Community: AVLESSI Matchoudi

Guide to Building a Complete Blog App with Django using TDD Methodology and PostgreSQL (Part 3): Secure User Authentication

1. Create a login form

2. Create our login view

2.1 Create tests for the login view

2.2 Create a login view

2.3 Create a template for Login

3. Test if everything is working as it should in our browser

Guide to Building a Complete Blog App with Django using TDD Methodology and PostgreSQL (Part 2): User registration

Prerequisites

1. Create an app named Users within our project

2. Create test cases for the User model

3. Create a custom user model

3.1 Create a Model Manager

3.2 Create a Custom Model

3.3 Settings

3.4 Run migrations

3.5 Remove Django built-in admin application (optional)

4. Create a Custom form for our model

4.1 Create test

4.2 Create forms

5. Create views for the model

5.1 Create test cases for the views

5.2 Create a view for sign-up

6. Create a URL for our view

7. Create a Signup template

Guide to Building a Complete Blog App with Django using TDD methodology and PostgreSQL database: Installation and Setup

IV- Setting up Postgres database

1. Create a PostgreSQL database for our project

3. Create the URLS for the home, and about pages

1. Create an app named `Users` within our project