api: add series versioning updates

Add PUT and PATCH methods to the series detail view, both are handled as
partial updates and the only accepted field for now is 'supersedes'.

To update which series are superseded by the current one the user must
provide the complete list.

Signed-off-by: Victor Accarini <[email protected]>

Author: victor-accarini

patchwork/api/base.py

@@ -96,7 +96,7 @@ def get_paginated_response(self, data):
 
 class PatchworkPermission(permissions.BasePermission):
     """
-    This permission works for Project, Patch, PatchComment
+    This permission works for Project, Patch, Series, PatchComment
     and CoverComment model objects
     """
 

patchwork/api/series.py

@@ -4,11 +4,10 @@
 # SPDX-License-Identifier: GPL-2.0-or-later
 
 from rest_framework.generics import ListAPIView
-from rest_framework.generics import RetrieveAPIView
-from rest_framework.serializers import (
-    SerializerMethodField,
-    HyperlinkedRelatedField,
-)
+from rest_framework.generics import RetrieveUpdateAPIView
+from rest_framework.serializers import SerializerMethodField
+from rest_framework.serializers import HyperlinkedRelatedField
+from rest_framework.serializers import ValidationError
 
 from patchwork.api.base import BaseHyperlinkedModelSerializer
 from patchwork.api.base import PatchworkPermission
@@ -34,8 +33,9 @@ class SeriesSerializer(BaseHyperlinkedModelSerializer):
         read_only=True, view_name='api-series-detail', many=True
     )
     supersedes = HyperlinkedRelatedField(
-        read_only=True,
         view_name='api-series-detail',
+        queryset=Series.objects.all(),
+        required=False,
         many=True,
     )
     superseded = HyperlinkedRelatedField(
@@ -44,6 +44,32 @@ class SeriesSerializer(BaseHyperlinkedModelSerializer):
         many=True,
     )
 
+    def update(self, instance, validated_data, *args, **kwargs):
+        allowed_fields = {'supersedes'}
+        incoming_fields = set(validated_data.keys())
+
+        if not incoming_fields.issubset(allowed_fields):
+            invalid_fields = incoming_fields - allowed_fields
+            raise ValidationError(
+                {
+                    'detail': 'Cannot update fields: '
+                    f"{', '.join(invalid_fields)}. Only 'supersedes' can be "
+                    'updated.'
+                }
+            )
+
+        if 'supersedes' in validated_data:
+            supersedes = validated_data.pop('supersedes', [])
+
+            try:
+                instance.supersedes.set(supersedes)
+            except Series.DoesNotExist:
+                raise ValidationError(
+                    {'detail': 'Unable to find one of the referenced series'}
+                )
+
+        return instance
+
     def get_web_url(self, instance):
         request = self.context.get('request')
         return request.build_absolute_uri(instance.get_absolute_url())
@@ -100,7 +126,6 @@ class Meta:
             'patches',
             'dependencies',
             'dependents',
-            'supersedes',
             'superseded',
         )
         versioned_fields = {
@@ -140,7 +165,40 @@ class SeriesList(SeriesMixin, ListAPIView):
     ordering = 'id'
 
 
-class SeriesDetail(SeriesMixin, RetrieveAPIView):
-    """Show a series."""
+class SeriesDetail(SeriesMixin, RetrieveUpdateAPIView):
+    """Show a series.
+
+    retrieve:
+        Return the details of a series.
+
+    update:
+        Only updates the 'supersedes' field of a series. Replaces the whole set
+        of superseded series.
+
+        ::
+
+        Instance:
+            instance.supersedes = [
+                'http://example.com/api/series/1/',
+                'http://example.com/api/series/2/',
+                'http://example.com/api/series/5/'
+            ]
+
+        Request:
+            PUT/PATCH {
+                "supersedes": [
+                    'http://example.com/api/series/1/',
+                    'http://example.com/api/series/8/'
+                ]
+            }
+
+        Result:
+            instance.supersedes = [
+                'http://example.com/api/series/1/',
+                'http://example.com/api/series/8/'
+            ]
+    """
 
-    pass
+    # PUT operation will behave as a partial update
+    def put(self, request, *args, **kwargs):
+        return self.partial_update(request, *args, **kwargs)