Admin Site

INSTALLED_APPS = [
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",
    "catalog",
]

MIDDLEWARE = [
    "django.middleware.security.SecurityMiddleware",
    "django.contrib.sessions.middleware.SessionMiddleware",
    "django.middleware.common.CommonMiddleware",
    "django.middleware.csrf.CsrfViewMiddleware",
    "django.contrib.auth.middleware.AuthenticationMiddleware",
    "django.contrib.messages.middleware.MessageMiddleware",
    "django.middleware.clickjacking.XFrameOptionsMiddleware",
]

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [],
        "APP_DIRS": True,
        "OPTIONS": {
            "context_processors": [
                "django.template.context_processors.request",
                "django.contrib.auth.context_processors.auth",
                "django.contrib.messages.context_processors.messages",
            ],
        },
    },
]

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

urlpatterns = [
    path("admin/", admin.site.urls),
    path("", include("catalog.urls")),
]

$ python manage.py migrate
$ DJANGO_SUPERUSER_PASSWORD=change-me python manage.py createsuperuser \
    --noinput --username admin --email admin@example.com
Superuser created successfully.

$ curl -s -o /dev/null -w "%{http_code} %{redirect_url}\n" http://127.0.0.1:8737/admin/catalog/book/
302 http://127.0.0.1:8737/admin/login/?next=/admin/catalog/book/
$ curl -s -o /dev/null -w "%{http_code}\n" "http://127.0.0.1:8737/admin/login/"
200

from django.conf import settings
from django.core.validators import MaxValueValidator, MinValueValidator
from django.db import models
from django.urls import reverse


class Genre(models.Model):
    name = models.CharField(max_length=60, unique=True)

    class Meta:
        ordering = ["name"]

    def __str__(self):
        return self.name


class Author(models.Model):
    name = models.CharField(max_length=200)
    slug = models.SlugField(unique=True)
    country = models.CharField(max_length=2, blank=True)

    class Meta:
        ordering = ["name"]

    def __str__(self):
        return self.name


class Book(models.Model):
    class Status(models.TextChoices):
        DRAFT = "draft", "Draft"
        PUBLISHED = "published", "Published"
        WITHDRAWN = "withdrawn", "Withdrawn"

    title = models.CharField(max_length=200)
    subtitle = models.CharField(max_length=200, blank=True)
    slug = models.SlugField(unique=True)
    isbn = models.CharField(max_length=13, unique=True)
    author = models.ForeignKey(Author, on_delete=models.PROTECT, related_name="books")
    genres = models.ManyToManyField(Genre, blank=True, related_name="books")
    price = models.DecimalField(max_digits=6, decimal_places=2)
    published = models.DateField()
    status = models.CharField(
        max_length=10, choices=Status, default=Status.DRAFT
    )
    # Set by the server (the admin), never typed by an editor:
    added_by = models.ForeignKey(
        settings.AUTH_USER_MODEL,
        null=True,
        blank=True,
        on_delete=models.SET_NULL,
        related_name="+",
    )
    created_at = models.DateTimeField(auto_now_add=True)

    class Meta:
        ordering = ["title"]
        permissions = [("publish_book", "Can publish or withdraw books")]

    def __str__(self):
        return self.title

    def get_absolute_url(self):
        return reverse("catalog:book-detail", kwargs={"slug": self.slug})


class Review(models.Model):
    book = models.ForeignKey(Book, on_delete=models.CASCADE, related_name="reviews")
    reviewer = models.ForeignKey(
        settings.AUTH_USER_MODEL, on_delete=models.CASCADE, related_name="reviews"
    )
    rating = models.PositiveSmallIntegerField(
        validators=[MinValueValidator(1), MaxValueValidator(5)]
    )
    body = models.TextField(blank=True)

    class Meta:
        ordering = ["id"]
        constraints = [
            models.UniqueConstraint(
                fields=["book", "reviewer"], name="one_review_per_reader_and_book"
            )
        ]

    def __str__(self):
        return f"{self.reviewer} on {self.book}: {self.rating}/5"


class MyBook(Book):
    """Proxy model: same table as Book, its own admin page and permissions."""

    class Meta:
        proxy = True
        verbose_name = "my book"
        verbose_name_plural = "my books"

import csv

from django.contrib import admin, messages
from django.contrib.admin import ActionLocation
from django.contrib.auth import get_permission_codename
from django.db.models import Avg, Count
from django.http import HttpResponse
from django.utils import timezone
from django.utils.html import format_html
from django.utils.translation import ngettext

from .models import Author, Book, Genre, MyBook, Review

# --------------------------------------------------------------- Author
class BookInline(admin.TabularInline):
    model = Book
    fields = ["title", "slug", "isbn", "price", "published", "status"]
    prepopulated_fields = {"slug": ["title"]}
    extra = 0
    show_change_link = True
    ordering = ["-published"]


@admin.register(Author)
class AuthorAdmin(admin.ModelAdmin):
    list_display = ["name", "country", "book_count"]
    list_filter = ["country"]
    ordering = ["name"]  # annotate() with an aggregate ignores Meta.ordering
    search_fields = ["name"]  # required by BookAdmin.autocomplete_fields
    prepopulated_fields = {"slug": ["name"]}
    inlines = [BookInline]

    def get_queryset(self, request):
        return super().get_queryset(request).annotate(_book_count=Count("books"))

    @admin.display(description="Books", ordering="_book_count")
    def book_count(self, obj):
        return obj._book_count

    def save_formset(self, request, form, formset, change):
        # Inlines do not go through save_model(): stamp new books here.
        instances = formset.save(commit=False)
        for obj in formset.deleted_objects:
            obj.delete()
        for instance in instances:
            if isinstance(instance, Book) and instance.added_by_id is None:
                instance.added_by = request.user
            instance.save()
        formset.save_m2m()

class ReviewInline(admin.TabularInline):
    model = Review
    fields = ["reviewer", "rating", "body"]
    raw_id_fields = ["reviewer"]
    extra = 0

    def has_add_permission(self, request, obj):
        return False  # editors moderate reviews, they do not write them

# ---------------------------------------------------------------- Genre
class BookGenreInline(admin.TabularInline):
    """Many-to-many through table edited as an inline on the Genre page."""

    model = Book.genres.through
    extra = 0
    autocomplete_fields = ["book"]
    verbose_name = "book"
    verbose_name_plural = "books"


@admin.register(Genre)
class GenreAdmin(admin.ModelAdmin):
    search_fields = ["name"]  # required by BookAdmin.autocomplete_fields
    inlines = [BookGenreInline]

class ReviewInlineOnChangeAdmin(admin.ModelAdmin):
    """Show the inline only when editing, never on the add form."""

    class ReviewInline(admin.StackedInline):
        model = Review
        fk_name = "book"
        extra = 1
        max_num = 5
        min_num = 0
        can_delete = False
        show_change_link = True
        classes = ["collapse"]

    inlines = [ReviewInline]

    def get_inlines(self, request, obj):
        return self.inlines if obj is not None else []

    # --- actions
    @admin.action(
        description="Publish",
        description_plural="Publish selected %(verbose_name_plural)s",
        permissions=["publish"],
        location=[ActionLocation.CHANGE_LIST, ActionLocation.CHANGE_FORM],
    )
    def publish(self, request, queryset):
        updated = queryset.update(status=Book.Status.PUBLISHED)
        self.message_user(
            request,
            ngettext("%d book was published.", "%d books were published.", updated)
            % updated,
            messages.SUCCESS,
        )

    @admin.action(
        description="Withdraw selected %(verbose_name_plural)s",
        permissions=["publish"],
    )
    def withdraw(self, request, queryset):
        updated = queryset.update(status=Book.Status.WITHDRAWN)
        self.message_user(request, f"{updated} withdrawn.", messages.WARNING)

    @admin.action(description="Export selected books as CSV", permissions=["view"])
    def export_csv(self, request, queryset):
        response = HttpResponse(content_type="text/csv")
        response["Content-Disposition"] = 'attachment; filename="books.csv"'
        writer = csv.writer(response)
        writer.writerow(["isbn", "title", "author", "price", "status"])
        for book in queryset.select_related("author"):
            writer.writerow(
                [book.isbn, _csv_safe(book.title), book.author.name, book.price, book.status]
            )
        return response

def _csv_safe(value):
    """Stop spreadsheets from running a cell that starts like a formula."""
    return f"'{value}" if value[:1] in ("=", "+", "-", "@") else value


# ----------------------------------------------------- scoping a queryset
@admin.register(MyBook)
class MyBookAdmin(BookAdmin):
    def get_queryset(self, request):
        return super().get_queryset(request).filter(added_by=request.user)

# -------------------------------------------------------------- site-wide
@admin.action(description="Export selected objects as JSON")
def export_as_json(modeladmin, request, queryset):
    response = HttpResponse(content_type="application/json")
    serializers.serialize("json", queryset, stream=response)
    return response



@admin.action(description="Say hello", permissions=["view"])
def say_hello(modeladmin, request, queryset):
    modeladmin.message_user(request, f"{queryset.count()} selected", messages.INFO)

site = admin.AdminSite(name="example4")
site.register(Author)
site.add_action(admin_examples.export_as_json, "export_json")
site.add_action(admin_examples.say_hello)

class ActionTests(AdminTestBase):
    def post_action(self, action, *books):
        return self.client.post(
            reverse("admin:catalog_book_changelist"),
            {"action": action, ACTION_CHECKBOX_NAME: [b.pk for b in books]},
            follow=True,
        )

    def test_publish_and_withdraw_need_the_custom_permission(self):
        editor = make_user("editor", "view_book", "change_book")
        self.client.force_login(editor)
        page = self.client.get(reverse("admin:catalog_book_changelist"))
        self.assertNotContains(page, 'value="publish"')
        self.assertContains(page, 'value="export_csv"')
        self.post_action("publish", self.draft)
        self.draft.refresh_from_db()
        self.assertEqual(self.draft.status, "draft")  # unknown action: ignored

    def test_publisher_can_publish_in_bulk(self):
        publisher = make_user("publisher", "view_book", "change_book", "publish_book")
        self.client.force_login(publisher)
        response = self.post_action("publish", self.draft)
        self.assertContains(response, "1 book was published.")
        self.draft.refresh_from_db()
        self.assertEqual(self.draft.status, "published")

    def test_change_form_action_for_publishers_only(self):
        url = reverse("admin:catalog_book_change", args=[self.draft.pk])
        self.client.force_login(make_user("editor", "view_book", "change_book"))
        self.assertNotContains(self.client.get(url), 'name="CHANGE_FORM-action"')
        self.client.force_login(
            make_user("publisher", "view_book", "change_book", "publish_book")
        )
        self.assertContains(self.client.get(url), 'name="CHANGE_FORM-action"')
        response = self.client.post(
            url,
            {"CHANGE_FORM-action": "publish", "_selected_action": self.draft.pk,
             "CHANGE_FORM-select_across": "0", "index": "0"},
            follow=True,
        )
        self.assertContains(response, "1 book was published.")
        self.draft.refresh_from_db()
        self.assertEqual(self.draft.status, "published")

    # --- permissions
    def has_publish_permission(self, request):
        codename = get_permission_codename("publish", self.opts)  # "publish_book"
        return request.user.has_perm(f"{self.opts.app_label}.{codename}")

    def has_delete_permission(self, request, obj=None):
        if obj is not None and obj.status == Book.Status.PUBLISHED:
            return False  # withdraw first, then delete
        return super().has_delete_permission(request, obj)

    def get_readonly_fields(self, request, obj=None):
        readonly = [*super().get_readonly_fields(request, obj)]  # a copy
        if not self.has_publish_permission(request):
            readonly.append("status")
        return readonly

    # --- saving
    def save_model(self, request, obj, form, change):
        if not change and obj.added_by_id is None:
            obj.added_by = request.user
        super().save_model(request, obj, form, change)

def make_user(username, *codenames, staff=True):
    """A staff user holding exactly the given catalog permissions."""
    user = User.objects.create_user(username, password=None, is_staff=staff)
    user.user_permissions.add(*Permission.objects.filter(codename__in=codenames))
    return user

class PermissionTests(AdminTestBase):
    def test_non_staff_is_redirected_to_login(self):
        self.client.force_login(self.reader)
        response = self.client.get(reverse("admin:catalog_book_changelist"))
        self.assertEqual(response.status_code, 302)
        self.assertIn("/admin/login/", response["Location"])

    def test_staff_without_model_permission_gets_403(self):
        self.client.force_login(make_user("nobody"))
        self.assertEqual(self.client.get(reverse("admin:catalog_book_changelist")).status_code, 403)

    def test_view_permission_is_read_only(self):
        self.client.force_login(make_user("auditor", "view_book"))
        url = reverse("admin:catalog_book_change", args=[self.draft.pk])
        response = self.client.get(url)
        self.assertNotContains(response, 'name="_save"')
        self.assertEqual(self.client.post(url, {"title": "x"}).status_code, 403)

    def test_status_is_read_only_without_publish_permission(self):
        self.client.force_login(make_user("editor", "view_book", "change_book"))
        response = self.client.get(reverse("admin:catalog_book_change", args=[self.draft.pk]))
        self.assertNotContains(response, 'name="status"')
        self.client.force_login(make_user("publisher", "view_book", "change_book", "publish_book"))
        response = self.client.get(reverse("admin:catalog_book_change", args=[self.draft.pk]))
        self.assertContains(response, 'name="status"')

    def test_published_books_have_no_delete_button(self):
        self.client.force_login(make_user("deleter", "view_book", "change_book", "delete_book"))
        live = self.client.get(reverse("admin:catalog_book_change", args=[self.live.pk]))
        draft = self.client.get(reverse("admin:catalog_book_change", args=[self.draft.pk]))
        self.assertNotContains(live, "deletelink")
        self.assertContains(draft, "deletelink")
        self.assertEqual(
            self.client.post(reverse("admin:catalog_book_delete", args=[self.live.pk]), {"post": "yes"}).status_code,
            403,
        )

    def test_inline_add_permission_is_removed(self):
        self.client.force_login(self.superuser)
        other = User.objects.create_user("other", password=None)
        data = {
            "title": "Engines", "subtitle": "An essay", "slug": "engines",
            "author": self.author.pk, "price": "20.00", "isbn": "9780000000002",
            "published": "2023-01-01", "status": "published",
            "reviews-TOTAL_FORMS": "2", "reviews-INITIAL_FORMS": "1",
            "reviews-MIN_NUM_FORMS": "0", "reviews-MAX_NUM_FORMS": "1000",
            "reviews-0-id": Review.objects.get().pk, "reviews-0-book": self.live.pk,
            "reviews-0-reviewer": self.reader.pk, "reviews-0-rating": "5",
            "reviews-1-book": self.live.pk, "reviews-1-reviewer": other.pk,
            "reviews-1-rating": "1",
        }
        self.client.post(reverse("admin:catalog_book_change", args=[self.live.pk]), data)
        self.assertEqual(Review.objects.count(), 1)  # the extra form was ignored

    def test_group_permissions(self):
        group = Group.objects.create(name="Editors")
        group.permissions.set(Permission.objects.filter(codename__in=["view_book", "change_book"]))
        user = User.objects.create_user("grouped", password=None, is_staff=True)
        user.groups.add(group)
        self.client.force_login(user)
        self.assertEqual(self.client.get(reverse("admin:catalog_book_changelist")).status_code, 200)

    def test_autocomplete_needs_view_or_change_on_related_model(self):
        self.client.force_login(make_user("limited", "view_book"))
        url = reverse("admin:autocomplete")
        params = {"term": "ada", "app_label": "catalog", "model_name": "book", "field_name": "author"}
        self.assertEqual(self.client.get(url, params).status_code, 403)
        self.client.force_login(make_user("limited2", "view_book", "view_author"))
        response = self.client.get(url, params)
        self.assertEqual(response.status_code, 200)
        self.assertEqual(response.json()["results"][0]["text"], "Ada Lovelace")

    def test_my_books_scopes_rows(self):
        Book.objects.filter(pk=self.draft.pk).update(added_by=self.superuser)
        user = make_user("mine", "view_mybook", "change_mybook")
        Book.objects.filter(pk=self.live.pk).update(added_by=user)
        self.client.force_login(user)
        response = self.client.get(reverse("admin:catalog_mybook_changelist"))
        self.assertEqual([b.title for b in response.context["cl"].result_list], ["Engines"])
        other = reverse("admin:catalog_mybook_change", args=[self.draft.pk])
        self.assertEqual(self.client.get(other).status_code, 302)  # "doesn't exist" redirect

$ uvicorn config.asgi:application --port 8737 &
$ curl -s -o /dev/null -w "login page %{http_code}\n" http://127.0.0.1:8737/admin/login/
login page 200
$ curl -s -b cookies.txt -o /dev/null -w "changelist %{http_code}\n" http://127.0.0.1:8737/admin/catalog/book/
changelist 200
$ curl -s -o /dev/null -w "static css %{http_code}\n" http://127.0.0.1:8737/static/admin/css/base.css
static css 404

bad = admin.AdminSite(name="bad")

class Broken(admin.ModelAdmin):
    list_display = ["title", "pages"]          # no such attribute
    list_editable = ["title"]                  # first column, no links
    autocomplete_fields = ["author"]           # AuthorAdmin has no search_fields
    readonly_fields = ["nope"]
    list_filter = ["nada"]
    fieldsets = [(None, {"fields": ["title", "title"]})]

bad.register(Book, Broken)

admin.E040 ModelAdmin must define "search_fields", because it's referenced by Broken.autocomplete_fields.
admin.E012 There are duplicate field(s) in 'fieldsets[0][1]'.
admin.E035 The value of 'readonly_fields[0]' refers to 'nope', which is not a callable, an attribute of 'Broken', or an attribute of 'catalog.Book'.
admin.E108 The value of 'list_display[1]' refers to 'pages', which is not a callable or attribute of 'Broken', or an attribute, method, or field on 'catalog.Book'.
admin.E116 The value of 'list_filter[0]' refers to 'nada', which does not refer to a Field.
admin.E124 The value of 'list_editable[0]' refers to the first field in 'list_display' ('title'), which cannot be used unless 'list_display_links' is set.