Tag: Django

Here we go again for another post of this blog’s irregular column, entitled Django’s Friday Tips. Today let’s address a silent issue, that any of you that have formerly worked with internationalization (i18n) almost certainly already faced.

You add a string that must be translated:

from django.utils.translation import gettext_lazy as _

some_variable = _("A key that needs translation")

You then execute the manage.py makemessages --locale pt command, go to the generated django.po file and edit the translation:

msgid "A key that needs translation"
msgstr "Uma chave que precisa de tradução"

You compile (manage.py compilemessages --locale pt), and proceed with your work.

A few moments later, when checking the results of your hard effort… nothing, the text is showing the key (in English).

Time to double-check the code (did I forgot the gettext stuff?), the translation file, the I18n settings, etc. What the hell?

Don’t waste any more time, most likely the translation is marked as fuzzy, like this:

#: myapp/module.py:3
#, fuzzy
#| msgid "Another key that needed translation"
msgid "A key that needs translation"
msgstr "Uma chave que precisa de tradução"

You see, you didn’t notice that #, fuzzy line and kept it there. The command that compiles those translations ignores the messages marked as fuzzy.

So the solution is to remove those extra 2 lines, or to compile with the --use-fuzzy⁣ flag. That’s it, compile, and you should be able to proceed with the problem solved.

Today, let’s go back to the topic of the first post in this series of Django tips.

At the time, I focused on the python manage.py check --deploy command. In this article, I will explore the feature on which it is built and how it can be quite handy for many other scenarios.

So, the System Check Framework, what is it?

The system check framework is a set of static checks for validating Django projects. It detects common problems and provides hints for how to fix them. The framework is extensible so you can easily add your own checks.

Django documentation

We already have linters, formatters, and static analysis tools that we run on the CI of our projects. Many companies also have strict peer review processes before accepting any changes to the code. However, this framework can still very useful for many projects in situations such as:

• Detect misconfigurations when someone is setting a complex new development environment, and help them correctly resolve the issues.
• Warn developers when project-specific approaches are not being followed.
• Ensure everything is well configured and correctly set up before deploying to production. Otherwise, make the deployment fail.

With the framework, the above points are a bit easier to implement, since “system checks” has access to the real state of the app.

During development, checks are executed on commands such as runserver and migrate, and before deployment a call to manage.py check can be executed before starting the app.

Django itself makes heavy use of this framework. I’m sure you have already seen messages such as the ones shown below, during development.

I’m not going to dig deeper into the details, since the Django documentation is excellent (list of built-in checks). Let’s just build a practical example.

A practical example

Recently, I was watching a talk and the speaker mentioned a situation when a project should block Django’s reverse foreign keys, to prevent accidental data leakages. The precise situation is not relevant for this post, given it is a bit more complex, but let’s assume this is the requirement.

The reverse foreign key feature needs to be disabled on every foreign key field. We can implement a system check to ensure we haven’t forgotten any. It would look very similar to this:

# checks.py
from django.apps import apps
from django.core import checks
from django.db.models import ForeignKey


@checks.register(checks.Tags.models)
def check_foreign_keys(app_configs, **kwargs):
    errors = []

    for app in apps.get_app_configs():
        if "site-packages" in app.path:
            continue

        for model in app.get_models():
            fields = model._meta.get_fields()
            for field in fields:
                errors.extend(check_field(model, field))

    return errors


def check_field(model, field):
    if not isinstance(field, ForeignKey):
        return []

    rel_name = getattr(field, "_related_name", None)
    if rel_name and rel_name.endswith("+"):
        return []

    error = checks.CheckMessage(
        checks.ERROR,
        f'FK "{field.name}" reverse lookups enabled',
        'Add "+" at the end of the "related_name".',
        obj=model,
        id="example.E001",
    )
    return [error]

Then ensure the check is active by loading it on apps.py:

# apps.py
from django.apps import AppConfig


class ExampleConfig(AppConfig):
    name = "example"

    def ready(self):
        super().ready()
        from .checks import check_foreign_keys

This would do the trick and produce the following output when trying to run the development server:

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

...

ERRORS:
example.Order: (example.E001) FK "client" reverse lookups enabled
        HINT: Add "+" at the end of the "related_name".
example.Order: (example.E001) FK "source" reverse lookups enabled
        HINT: Add "+" at the end of the "related_name".
example.OrderRequest: (example.E001) FK "source" reverse lookups enabled
        HINT: Add "+" at the end of the "related_name".

On the other hand, if your test is only important for production, you should use @checks.register(checks.Tags.models, deploy=True). This way, the check will only be executed together with all other security checks when running manage.py check --deploy.

Doing more with the framework

There are also packages on PyPI, such as django-extra-checks, that implement checks for general Django good practices if you wish to enforce them on your project.

To end this post, that is already longer than I initially desired, I will leave a couple of links to other resources if you want to continue exploring:

• https://hakibenita.com/automating-the-boring-stuff-in-django-using-the-check-framework
• https://www.b-list.org/weblog/2023/dec/20/django-system-check/

One of the great builtin features of Django is the admin app. It lets you, among other things, execute the usual CRUD operations on your data, search, filter and execute bulk actions on many records.

However the interface is a bit rigid, by default you have the “dashboard” with the list of models, the page listing your records for each model and the details page for each individual item.

What if you want to display other information to the admins? Such an overview of the system, aggregate data, some statistics, etc.

In this post I will address the steps required to add custom pages to the admin and include them in the main menu of the administration.

The starting point will be the website I used in a previous tip/post:

1. Add a custom Admin Site

The first step is to create a new custom admin website, so we can easily modify its contents and functionality.

from django.contrib import admin

class YourCustomAdminSite(admin.AdminSite):
    pass

Now we will have to use this admin site across your project, which means changing your current admin settings to use this “site” (such as your ModelAdmins and your urls.py.

If the above is too much trouble and requires to many changes, this small “hack” before including the admin URLs will also work:

# urls.py

admin.site.__class__ = YourCustomAdminSite

2. Add a new view

In our new admin site we can now create views as methods, to handle different requests. Like this:

from django.contrib import admin
from django.template.response import TemplateResponse

class YourCustomAdminSite(admin.AdminSite):
    def custom_page(self, request):
        context = {"text": "Hello Admin", 
                   "page_name": "Custom Page"}
        return TemplateResponse(request,
                                "admin/custom_page.html", 
                                context)

3. Add a new template

As you can see in the above python snippet, we are using a template that doesn’t exist yet, so lets create it:

{# templates/admin/custom_page.html #}

{% extends 'admin/change_list.html' %}

{% block pagination %}{% endblock %}
{% block filters %}{% endblock filters %}
{% block object-tools %}{% endblock object-tools %}
{% block search %}{% endblock %}

{% block breadcrumbs %}
<div class="breadcrumbs">
  <a href="{% url 'admin:index' %}">Home</a>
  {% if page_name %} &rsaquo; {{ page_name }}{% endif %}
</div>
{% endblock %}

{% block result_list %}
{{text}}
{% endblock result_list %}

(I chose to extend admin/change_list.html, but the content of this template is up to you, no restrictions here. If you decide to not extend any existing admin template, the last steps of 5. will not apply to your case)

4. Extend the admin URLs

To make this new endpoint accessible, we now have to edit the method that returns all existing URLs of the administration and append our new page.

from django.urls import path
...

class YourCustomAdminSite(admin.AdminSite):
    ...

    def get_urls(
        self,
    ):
        return [
            path(
                "custom_page/",
                self.admin_view(self.custom_page),
                name="custom_page",
            ),
        ] + super().get_urls()

At this point the custom page should be available at /admin/custom_page/, but users will not be able to find it, since no other link or button points to it.

5. Extend the menu items

The final step is to include a link to the new page in the existing menu, in order for it to be easily accessible. First we need to replace the current index_template:

...

class YourCustomAdminSite(admin.AdminSite):
    index_template = "admin/custom_index.html"
    ...

And add the following content to your new template:

{% extends "admin/index.html" %}

{% block content %}
<div id="content-main">
  {% include "admin/custom_app_list.html" with app_list=app_list show_changelinks=True %}
</div>
{% endblock %}

The included custom_app_list.html should look like this:

<div id="extra_links_wrapper" class="module">
    <table>
        <caption>
            <a class="section" title="Custom Pages">Custom Pages</a>
        </caption>
        <tr>
            <th scope="row">
                <a href="{% url 'admin:custom_page' %}">
                    Custom Page
                </a>
            </th>
            <td></td>
        </tr>
    </table>
</div>

{% include 'admin/app_list.html' %}

Basically we added a new section to the list containing a link to our new page.

Looking good, the page is there with our content and is accessible through the index page. However many traditional elements on the page are missing (side menu, logout button, etc). To add them we just need some small changes to our view:

...

class YourCustomAdminSite(admin.AdminSite):
    ...

    def custom_page(self, request):
        context = {
            "text": "Hello Admin",
            "page_name": "Custom Page",
            "app_list": self.get_app_list(request),
            **self.each_context(request),
        }
        return TemplateResponse(request, "admin/custom_page.html", context)

Now it looks a lot better:

But something is still missing. Where are the links to our custom pages?

It seems the standard app_list.html is being used. Lets replace it with our custom one by overriding nav_sidebar.html:

{# templates/admin/nav_sidebar.html #}

{% load i18n %}
<button class="sticky toggle-nav-sidebar" id="toggle-nav-sidebar"
  aria-label="{% translate 'Toggle navigation' %}"></button>
<nav class="sticky" id="nav-sidebar">
  {% include 'admin/custom_app_list.html' with app_list=available_apps show_changelinks=False %}
</nav>

Note: The app where you put the above template must be placed before the “admin” app in your “INSTALLED_APPS” list, otherwise the default template will be used anyway.

And for today, this is it. With the above changes you can add as many custom pages to your admin as you need and have full controls over their functionality.