DEV Community: REVSYS

How to Add Django Models to the Wagtail Admin

Lacey Williams Henschel — Tue, 27 Aug 2019 15:57:14 +0000

Versions

Python 3.7
Django 2.2
Wagtail 2.6

When working with Wagtail, you might find that you're using Wagtail Page models for some of your database models, but regular Django models for others.

A built-in example of this is the Django User model. When you log into the Wagtail admin, you can see the Django User model in the Settings submenu. The User model is not a Wagtail model; it's the same User model you see in a Django project that doesn't use Wagtail. Wagtail just exposes it to the Admin for you.

We can do the same thing with our Django models: we can expose them to the Wagtail admin so we don't have to maintain two separate admin interfaces to manage our website content.

For this example, let's assume we're working with these models:

from django.db import models 


class Pizza(models.Model):

    name = models.CharField(max_length=30)
    toppings = models.ManyToManyField("Topping")


class Topping(models.Model):

    name = models.CharField(max_length=30)

Adding a single model

The Wagtail docs are pretty clear on how to accomplish this, but let's walk through the steps.

First, make sure wagtail.contrib.modeladmin is in your INSTALLED_APPS:

# settings.py 

INSTALLED_APPS = [
    ...
    "wagtail.contrib.modeladmin",
]

Next, in the same app as the model you want to expose to the Wagtail admin, add a file called wagtail_hooks.py.

# wagtail_hooks.py

from wagtail.contrib.modeladmin.options import ModelAdmin, modeladmin_register 

from .models import Pizza


class PizzaAdmin(ModelAdmin):
    model = Pizza 
    menu_label = "Pizza"  
    menu_icon = "pick" 
    menu_order = 200 
    add_to_settings_menu = False 
    exclude_from_explorer = False 
    list_display = ("name",)
    list_filter = ("toppings",)
    search_fields = ("name",)


modeladmin_register(PizzaAdmin)

Let's step through these options in the ModelAdmin class:

model: The name of the model you're adding.
menu_label: Leave this blank to use the verbose_name_plural from your model. Give it a value to specify a new label for the Wagtail menu.
menu_icon: Every menu item in the Wagtail admin has an icon, and you can specify the one you want to use. Here is a list of the available icons.
menu_order: What order you want this model to appear in. 000 is first, 100 is second, etc. Note: if you add multiple models to the admin, you won't get an error if two of them have the same menu_order; Wagtail will just pick for you.
add_to_settings_menu: Whether you want this menu item to appear in the Settings submenu in the Wagtail admin.
exclude_from_explorer: Set to True if you do not want the explorer (the search box in the admin) to return results from this model. Set to False if you do want the explorer to return results from this model. (It's confusing.)
list_display: Same as the Django admin; list the fields you want to display on the listing page for this model in the Wagtail admin.
list_filter: Same as the Django admin; supply the fields you want to use to filter in the sidebar of the Wagtail admin.
search_fields: Same as the Django admin; supply the fields that you want the explorer to use to return search results.

The final step is to register the admin class. Once you've done that and started your server, you'll be able to see your model in the Wagtail admin:

We can do the same thing with our Django models: we can expose them to the Wagtail admin so we don't have to maintain two separate admin interfaces to manage our website content.

For this example, let's assume we're working with these models:

from django.db import models 


class Pizza(models.Model):

    name = models.CharField(max_length=30)
    toppings = models.ManyToManyField("Topping")


class Topping(models.Model):

    name = models.CharField(max_length=30)

Adding a single model

The Wagtail docs are pretty clear on how to accomplish this, but let's walk through the steps.

First, make sure wagtail.contrib.modeladmin is in your INSTALLED_APPS:

# settings.py 

INSTALLED_APPS = [
    ...
    "wagtail.contrib.modeladmin",
]

Next, in the same app as the model you want to expose to the Wagtail admin, add a file called wagtail_hooks.py.

# wagtail_hooks.py

from wagtail.contrib.modeladmin.options import ModelAdmin, modeladmin_register 

from .models import Pizza


class PizzaAdmin(ModelAdmin):
    model = Pizza 
    menu_label = "Pizza"  
    menu_icon = "pick" 
    menu_order = 200 
    add_to_settings_menu = False 
    exclude_from_explorer = False 
    list_display = ("name",)
    list_filter = ("toppings",)
    search_fields = ("name",)


modeladmin_register(PizzaAdmin)

Let's step through these options in the ModelAdmin class:

model: The name of the model you're adding.
menu_label: Leave this blank to use the verbose_name_plural from your model. Give it a value to specify a new label for the Wagtail menu.
menu_icon: Every menu item in the Wagtail admin has an icon, and you can specify the one you want to use. Here is a list of the available icons.
menu_order: What order you want this model to appear in. 000 is first, 100 is second, etc. Note: if you add multiple models to the admin, you won't get an error if two of them have the same menu_order; Wagtail will just pick for you.
add_to_settings_menu: Whether you want this menu item to appear in the Settings submenu in the Wagtail admin.
exclude_from_explorer: Set to True if you do not want the explorer (the search box in the admin) to return results from this model. Set to False if you do want the explorer to return results from this model. (It's confusing.)
list_display: Same as the Django admin; list the fields you want to display on the listing page for this model in the Wagtail admin.
list_filter: Same as the Django admin; supply the fields you want to use to filter in the sidebar of the Wagtail admin.
search_fields: Same as the Django admin; supply the fields that you want the explorer to use to return search results.

The final step is to register the admin class. Once you've done that and started your server, you'll be able to see your model in the Wagtail admin:

Adding related models

In our example models, we have two models: Pizza and Toppings. We could manually add the Topping model to the Wagtail admin and have it appear just below the Pizza model. We just learned how!

But it's so closely related to the Pizza model that it might be nice if we were able to relate those two models together in a submenu, kind of like how Settings is its own submenu in the admin that contains Users, Redirects, Sites, etc.

Go back to wagtail_hooks.py:

# wagtail_hooks.py

from wagtail.contrib.modeladmin.options import (
    ModelAdmin, 
    ModelAdminGroup, 
    modeladmin_register 
)

from .models import Pizza, Topping


class PizzaAdmin(ModelAdmin):
    ...
    menu_order = 000 
    ...


class ToppingAdmin(ModelAdmin):
    model = Topping 
    menu_label = "Toppings"  
    menu_icon = "edit" 
    menu_order = 100 
    add_to_settings_menu = False 
    exclude_from_explorer = False 
    list_display = ("name",)
    search_fields = ("name",)

Relating our two models together starts off in the same way: we create a class that inherits from ModelAdmin for each model and identify the necessary attributes like model and menu_icon to control things like their listing pages and search behavior.

Then, we add a new class that inherits from ModelAdminGroup:

# wagtail_hooks.py

from wagtail.contrib.modeladmin.options import (
    ModelAdmin, 
    ModelAdminGroup, 
    modeladmin_register 
)

from .models import Pizza, Topping


class PizzaAdmin(ModelAdmin):
    ...
    menu_order = 000 
    ...


class ToppingAdmin(ModelAdmin):
    ...
    menu_order = 100 
    ... 

class PizzaGroup(ModelAdminGroup):
    menu_label = "Pizzas" 
    menu_icon = "pick"
    menu_order = 500 
    items = (PizzaAdmin, ToppingAdmin)


modeladmin_register(PizzaGroup)

In the PizzaGroup class, we have some of the same attributes:

menu_label: We set what we want this group of related models to be called in the Wagtail admin menu
menu_icon: Which icon we want to use for this menu
menu_order: Where we want this menu to appear in the sidebar, in relation to the other menu items

We also add a new attribute, items, where we list which ModelAdmin classes we want to be part of this group. In our case, we want PizzaAdmin and ToppingAdmin to be in this group, so we add those.

Note the change we made to menu_order in PizzaAdmin and ToppingAdmin: Now those are set to 000 and 100. When the ModelAdmin classes will be part of a group, set the menu_order how you want them to relate to each other, not to the other menu items in the Wagtail admin. Then set the menu_order for the ModelAdminGroup class to the proper value for the order you want it to appear in the side menu in the admin.

Then we register the whole group, instead of the ModelAdmin classes individually, to the Wagtail admin. When we reload the admin, we see this:

On the far left, there is a new menu item Pizzas that expands a submenu. The submenu contains links to the admin interfaces for Pizzas and Toppings!

Note: If you have the Django admin enabled and have your models already in the Django admin, this doesn't disable them from the regular Django admin. You are free to access your models in both the Wagtail admin and the Django admin, or at this point you can choose to remove your models from the Django admin (or disable the Django admin altogether, if you prefer).

Helpful Links

Special thanks to Jeff Triplett and Jacob Burch for their help with this post.

Dataclasses and attrs: when and why

Flavio Curella — Tue, 20 Aug 2019 16:27:07 +0000

Python 3.7 introduced dataclasses (PEP557). Dataclasses can be a convenient way to generate classes whose primary goal is to contain values.

The design of dataclasses is based on the pre-existing attr.s library. In fact Hynek Schlawack, the very same author of attrs, helped with the writing of PEP557.

Basically dataclasses are a slimmed-down version of attrs. Whether this is an improvement or not really depends on your specific use-case.

I think the addition of dataclasses to the standard library makes attrs even more relevant. The way I see it is that one is a subset of the other, and having both options is a good thing. You should probably use both in your project, according to the level of formality you want in that particular piece of code.

In this article I will show the way I use dataclasses and attrs, why I think you should use both, and why I think attrs is still very relevant.

What do they do

Both the standard library's dataclasses and the attrs library provide a way to define what I'll call "structured data types" (I would put namedtuple, dict and typeddict in the same family)

PS: There's probably some more correct CS term for them, but I didn't go to CS School, so ¯\(ツ)/¯

They are all variations on the same concept: a class representing a data type containing multiple values, each value addressed by some kind of key.

They also do a few more useful things: they provide ordering, serialization, and a nice string representation. But for the most part, the most useful purpose is adding a certain degree of formalization to a group of values that need to be passed around.

An example

I think an example would better illustrate what I use dataclasses and attrs for.
Suppose you want to render a template containing a table. You want to make sure the table has a title, a description, and rows:

def render_document(title: str, caption: str, data: List[Dict[str, Any]]):
    return template.render({
        "title" : title,
        "caption": caption,
        "data": data,
})

Now, suppose you want to render a document, which consists of a title, description, status ("draft", "in review", "approved"), and a list of tables. How would you pass the tables to render_document?

You may choose to represent each table as a dict:

{
    "title": "My Table",
    "caption": "2019 Earnings",
    "data": [
        {"Period": "QT1", "Europe": 500, "USA": 467},
        {"Period": "QT2", "Europe": 345, "USA": 765},
    ]
}

But how would you express the type annotation for the tables argument so that it's correct, explicit and simple to understand?

def render_document(title: str, description: str, status: str, tables: List[Dict[str, Any]]):
    return template.render({
        "title": title,
        "description": description,
        "status": status,
        "tables": tables,
    })

That only gets us to describe the first level if tables. It doesn't tell us that a Table has a title, or caption. Instead, you could use a dataclass:

@dataclass
class Table:
    title: str
    data: List[Dict[str, Any]]
    caption: str = ""

def render_document(title: str, description: str, tables: List[Table]):
    return template.render({
        "title": title,
        "description": description,
        "tables": tables,
    })

This way we have type hinting, helping our IDE helping us.

But we can go one step further, and also provide type validation at runtime. This is where dataclasses stops, and attrs comes in:

@attr.s
class Table(object):
    title: str = attr.ib(validator=attr.validators.instance_of(str))  # don't you pass no bytes!
    data: List[Dict[str, Any]] = attr.ib(validator=...)
    description: str = attr.ib(validator=attr.validators.instance_of(str), default="")


def render_document(title: str, description: str, tables: List[Table]):
    return template.render({
        "title": title,
        "description": description,
        "tables": tables,
    })

Now, suppose we also need to render a "Report", which is a collection of "Document"s. You can probably see where this is going:

@dataclass
class Table:
    title: str
    data: List[Dict[str, Any]]
    caption: str = ""

@attr.s
class Document(object):
    status: str = attr.ib(validators=attr.validators.in_(
        ["draft", "in review", "approved"]
    ))
    tables: List[Table] = attr.ib(default=[])

def render_report(self, title: str, documents: List[Document]):
    return template.render({
        "title": title,
        "documents": documents,
    })

Note how I am validating that Document.status is one of the allowed values. This comes particularly handy when you're building abstractions on top of Django models with a field that uses choices. Dataclasses can't do that.

A couple of patterns I keep finding myself in are the following:

Write a function that accepts some arguments
Group some of the arguments into a tuple
Hm, I want field names -> namedtuple.
Hm, I want types -> dataclass.
Hm, I want validation -> attrs.

Another situation that happens quite often is this:

write a function that accepts some arguments
add typing so my IDE can help me out
oh, by the way, it needs to support a list of those things, not just one at a time!
refactor to use dataclasses
This argument can only be one of those values, or
1. I ask myself: How do I make sure other developers are passing the right type and/or values?
switch to attrs

Sometimes I stop at the dataclasses. Lots of times I get to the attrs step.

And sometimes, this happens:

one half of this legacy codebase uses -1 as special value for False, that other half uses False. Switch to attr.s so I can use converter= to normalize.

Comparison

The two libraries do appear very similar. To get a clearer picture of how they compare, I've made a table of the features I use most:

feature	dataclasses	attrs
frozen	✓	✓
defaults	✓	✓
totuple	✓	✓
todict	✓	✓
validators	✗	✓
converters	✗	✓
slotted classes	✗	✓

As you can see, there's a lot of overlap. But the additional features on attrs provide functionality that I need more often than not.

When to use dataclasses

Dataclasses are just about the "shape" of the data.
Choose dataclasses if:

You don't care about values in the fields, only their type
adding a dependency is not trivial

When to use attrs

attrs is about the shape and the values.
Choose attrs if:

you want to validate values. A common case would be the equivalent of a ChoiceField.
you want to normalize, or sanitize the input
whenever you want more formalization than dataclasses alone can offer
you are concerned about memory and performances. attrs can create slotted classes, which are optimized by CPython.

I often find myself using dataclasses and later switching to attr.s because the requirements changed or I find out I need to guard against some particular value. I think that's a normal aspect of developing software and what I call "continuous refactoring".

Why I like dataclasses

I'm glad dataclasses have been added to the standard library, and I think it's a beneficial addition. It's a very convenient thing to have at your disposal whenever you need.

For one, it will encourage a more structured style of programming from the beginning.

But I think the most compelling case is a practical one. Some high-risk corporate environments (eg: financial institutions) require every package to be vetted (with good reason: we've already had incidents of malicious code in libraries). That means that adding attrs is not as simple as adding a line to your requirements.txt, and will involve waiting on approval from your corpops team. Those developers can use dataclasses right away and their code will immediately benefit from using more formalized data types.

Why I like attrs

Most people don't work in such strictly-controlled environments.

And sure, sometimes you don't need all the features from attrs, but it doesn't hurt having them.

More often than not, I end up needing them anyway, as I formalize more and more of my code's API. Dataclasses only gets half-way of where I want to go.

Conclusion

I think dataclasses encompass only a subset of what attrs has to offer. Admittedly, it is a big subset. But the features that are not covered are important enough and needed often enough that they make attrs not only still relevant and useful, but also necessary.

In my mind, using both allows developers to progressively refactor their code, moving the contracts amongst functions from loosely-defined arguments all the way up to formally described data structures as the requirements of the app stabilize over time.

One nice effect of having dataclasses is that now developers are more incentivized to refactor their code toward more formalization. At some point dataclasses is not going to be enough, and that's when developers will refactor to use attrs. In this way, dataclasses actually acts as an introduction to attrs. I wouldn't be surprised if attrs becomes more popular thanks to dataclasses.

References

Acknowledgments + Thanks

I want to thank the following people for revising drafts and providing input and insights:

Hynek Schlawack
Jacob Kaplan-Moss
Jacob Burch
Jeff Triplett

Using Different Read and Write Serializers in Django REST Framework

Lacey Williams Henschel — Tue, 20 Aug 2019 16:24:38 +0000

Versions:

Python 3.7
Django 2.2
Django REST Framework 3.10

On a recent project, we needed to use different serializers for GET vs. POST/PUT/PATCH requests to our Django REST Framework API. In our case, this was because the GET serializer contained a lot of nested data; for example, it contained expanded fields from other serializers to foreign-key relationships. The requests to update data via the API, though, didn't need these expanded fields.

The first way we approached using different serializers for read and update actions was to override get_serializer_class() on each viewset to decide which serializer to return depending on the action in the request. We returned the "read" serializer for list and retrieve actions, and the "update" serializer for everything else. (The full list of API actions is in the DRF codebase.) But we wound up repeating ourselves across several viewsets, so we wrote a mixin to take care of some of this work for us!

A mixin is a Python class that contains custom attributes and methods (more explanation). It's not very useful on its own, but when it's inherited into a class, that class has access to the mixin's special attributes and methods.

This was our mixin:

class ReadWriteSerializerMixin(object):
    """
    Overrides get_serializer_class to choose the read serializer
    for GET requests and the write serializer for POST requests.

    Set read_serializer_class and write_serializer_class attributes on a
    viewset. 
    """

    read_serializer_class = None
    write_serializer_class = None

    def get_serializer_class(self):        
        if self.action in ["create", "update", "partial_update", "destroy"]:
            return self.get_write_serializer_class()
        return self.get_read_serializer_class()

    def get_read_serializer_class(self):
        assert self.read_serializer_class is not None, (
            "'%s' should either include a `read_serializer_class` attribute,"
            "or override the `get_read_serializer_class()` method."
            % self.__class__.__name__
        )
        return self.read_serializer_class

    def get_write_serializer_class(self):
        assert self.write_serializer_class is not None, (
            "'%s' should either include a `write_serializer_class` attribute,"
            "or override the `get_write_serializer_class()` method."
            % self.__class__.__name__
        )
        return self.write_serializer_class

This mixin defines two new attributes, read_serializer_class and write_serializer_class. Each attribute has a corresponding method to catch the error where the mixin is being used, but those attributes haven't been set. The get_*_serializer_class() methods will raise an AssertionError if your viewset hasn't set the appropriate attribute or overridden the necessary method.

The get_serializer_class method makes the final decision on which serializer to use. For the "update" actions to the API, it returns write_serializer_class; otherwise it returns read_serializer_class.

The mixin gets used in a viewset like this:

from rest_framework import viewsets

from .mixins import ReadWriteSerializerMixin
from .models import MyModel
from .serializers import ModelReadSerializer, ModelWriteSerializer


class MyModelViewSet(ReadWriteSerializerMixin, viewsets.ModelViewSet):
    queryset = MyModel.objects.all() 
    read_serializer_class = ModelReadSerializer 
    write_serializer_class = ModelWriteSerializer

Now the viewset MyModelViewSet has access to the attributes and methods from the mixin ReadWriteSerializerMixin. This means that when a call is made to the API that uses MyModelViewSet, the get_serializer_class() method from ReadWriteSerializerMixin will automatically be called and will decide, based on the kind of API request being made, which serializer to use. If we needed to make even more granular decisions about the serializer returned (maybe we want to use a more limited serializer for a list request and one with more data in a retrieve request), then our viewset can override get_write_serializer_class() to add that logic.

Note: Custom DRF actions will contain actions that aren't part of the DRF list of accepted actions (because they are custom actions you're creating), so when you call get_serializer_class from inside your action method, it will return whatever your "default" serializer class is. In the example above, the "default" serializer is the read_serializer_class because it's what we return when we fall through the other conditional.

Depending on your action, you will want to override get_serializer_class to change your default method or explicitly account for your custom action.

Mixins are a DRY (Don't Repeat Yourself) way to add functionality that you wind up needing to use across several viewsets. We hope you get to experiment with using them soon!

Thanks to Jeff Triplett for his help with this post.