django-admin-display

Simplifies the use of function attributes (eg. short_description) for the django admin and makes mypy happy :)

Note: Django 3.2+ has @display and @action decorators built-in.

Requirements

• Python 3.10 or newer
• Django 5.2 or newer

The support range follows the upstream support policies: Django 5.2 is the oldest release still receiving security support and Python 3.10 is the oldest Python release supported by Django 5.2. See What Python version can I use with Django? and the Python version status.

Python	Django
3.10	5.2
3.11	5.2
3.12	5.2, 6.0, 6.1
3.13	5.2, 6.0, 6.1
3.14	5.2, 6.0, 6.1

Installation

pip install django-admin-display

Usage

If you want to change the behaviour of how Django displays a read-only value in the admin interface, you can add some special attributes to the corresponding method. Supported values are

short_description
Customize the column’s title of the callable.

empty_value_display
Show this value instead, if the value of a field is None, an empty string, or an iterable without elements.

admin_order_field
Indicate that the value is represented by a certain database field. This can also be a query expression.

boolean
Display a pretty “on” or “off” icon if the method returns a boolean.

The following example shows, how you normally apply these attributes to an AdminModel or a Model method.

class Company(models.Model):
    ...

    def owner(self) -> bool:
        return self.owner.last_name

    owner.short_description = "Company owner"
    owner.admin_order_field = 'owner__last_name'

This module replaces the way of defining these attributes by providing a handy decorator.

from django_admin_display import display


class Company(models.Model):
    ...

    @display(
        description="Company owner",
        ordering='owner__last_name',
    )
    def owner(self) -> bool:
        return self.owner.last_name

The display decorator mirrors the parameter names of Django's built-in django.contrib.admin.display and is fully typed, so mypy keeps the decorated method's signature.

display	sets
boolean	boolean
ordering	admin_order_field
description	short_description
empty_value	empty_value_display

The older admin_display decorator remains available for backwards compatibility. It accepts the original parameter names (boolean, admin_order_field, short_description, empty_value_display) and delegates to display.

Why?

There are mainly two reasons why this module exists.

Usage with @property

It is quite common that a calculated model property is displayed in the admin interface:

class Company(models.Model):
    ...

    @property
    def created_on(self) -> datetime.date:
        return self.created_at.date()

In order to add special attributes, you have to create a protected method, attach the attributes and wrap that method using property():

class Company(models.Model):
    ...

    def _created_on(self) -> datetime.date:
        return self.created_at.date()

    _created_on.short_description = "Created on"
    created_on = property(_created_on)

This is quite cumbersome, hard to read and most people don't know that this is even possible. To overcome these downsides you can achieve the same result using the @display decorator:

from django_admin_display import display


class Company(models.Model):
    ...

    @property
    @display(
        description="Created on",
    )
    def created_on(self) -> datetime.date:
        return self.created_at.date()

mypy

If you are using mypy, you have probably stumbled over an error similar to this one

"Callable[[Any, Any], Any]" has no attribute "short_description"

A common solution is to ignore the type checking by adding # type: ignore to the end of the line:

class CompanyAdmin(admin.ModelAdmin):
    ...

    def created_on(self, company: models.Company) -> datetime.date:
        return company.created_at.date()

    created_on.short_description = "Created on"  # type: ignore

The issue is already known and heavily discussed on github.

This decorator solves the issue by internally using # type: ignore and providing a well-defined signature for setting the attributes. It is not an optimal solution but works well until the issue has been resolved.

Development

This project uses uv for packaging and dependency management, ruff for linting and formatting, mypy for static type checking and pytest for tests.

Clone this repository and run

uv sync

to create a virtual environment containing all dependencies. Afterwards, you can run the test suite using

uv run pytest

The test suite drives a real Django admin project (see tests/) end to end: it logs in through the admin login form, renders the changelist, follows the sortable column headers and submits the add form.

To lint and format the code, run

uv run ruff check --fix .
uv run ruff format .

and to type check the package and tests

uv run mypy django_admin_display tests

pre-commit hooks are configured to run ruff before every commit:

uvx pre-commit install

This repository follows the Conventional Commits style.