Aller au contenu
Makersquad

Django REST Framework 3.8 est sorti

par Makersquad ·

Logo de Django REST framework sur fond dégradé

Date de sortie : 3 avril 2018

Documentation officielle : https://www.django-rest-framework.org/community/release-notes/#38x-series

Cette version de Django REST Framework (DRF) est une version de maintenance : selon l’annonce officielle, elle résout un grand nombre de problèmes ouverts depuis longtemps et pose les bases de changements futurs.

Les nouveautés principales

Nouveau décorateur @action unifié

Les décorateurs @list_route et @detail_route sont fusionnés en un seul décorateur @action. Le paramètre booléen detail indique si l’action s’applique à une instance unique ou à la liste. Les deux anciens décorateurs sont en dépréciation en attente (pending deprecation) : ils seront dépréciés en 3.9 et supprimés en 3.10.

from rest_framework.decorators import action

class UserViewSet(viewsets.ModelViewSet):

    @action(detail=True, methods=['post'])
    def set_password(self, request, pk=None):
        # action sur un objet précis : /users/{pk}/set_password/
        ...

    @action(detail=False)
    def recent_users(self, request):
        # action sur la collection : /users/recent_users/
        ...

Pour migrer, remplacez @detail_route par @action(detail=True) et @list_route par @action(detail=False). Ce changement améliore l’introspection des actions d’un viewset et permettra d’afficher les actions supplémentaires dans la Browsable API dans une version future.

Comportement cohérent des champs en lecture seule

Les champs read_only sont désormais toujours exclus des champs modifiables. C’est un changement de comportement incompatible à connaître : auparavant, un champ read_only doté d’une valeur par défaut utilisait cette valeur lors des créations et des mises à jour.

Pour conserver l’ancien comportement, passez la valeur du champ lors de l’appel à save() dans la vue, ou surchargez save(), create() ou update() sur le serializer.

def perform_create(self, serializer):
    serializer.save(owner=self.request.user)

La version 3.8.0 corrige aussi le comportement de allow_null avec required=False : sans valeur par défaut explicite, allow_null implique une valeur par défaut None à la sérialisation. Les champs concernés, auparavant omis, apparaissent donc dans la représentation sortante, ce qui peut casser du code qui comptait sur leur absence.

Exclusion d’une vue du schéma généré

Pour retirer une vue de la génération de schéma, l’approche recommandée consiste à assigner schema = None directement sur la vue. Cette méthode remplace le paramètre exclude_from_schema, déprécié dès la version 3.7.

class MyView(APIView):
    schema = None  # exclut cette vue du schéma généré

Maintenance et correctifs

DRF 3.8 résout un grand nombre de problèmes restés ouverts. La liste complète figure dans les notes de version de la série 3.8.x, qui comprend aussi les correctifs 3.8.1 et 3.8.2.

À retenir

DRF 3.8 est une version de maintenance. Avant de monter de version, vérifiez les champs read_only qui ont une valeur par défaut et migrez vos @list_route et @detail_route vers @action, dépréciés en 3.9 puis supprimés en 3.10.

Échanger avec un expert Django

De l’idée au marché. Makersquad conçoit des logiciels sur mesure, pensés pour durer, avec de petites équipes d’experts autonomes. Depuis 2018.