Add SimplePathRouter

sevdog · sevdog · commit a4e68d69c287 · 2019-11-21T21:49:10.000+01:00
diff --git a/docs/api-guide/routers.md b/docs/api-guide/routers.md
@@ -173,6 +173,12 @@ The router will match lookup values containing any characters except slashes and
         lookup_field = 'my_model_id'
         lookup_value_regex = '[0-9a-f]{32}'
 
+## SimplePathRouter
+
+This router is similar to `SimpleRouter` as above, but instead of _regexs_ it uses [path converters][path-convertes-topic-reference] to build urls.
+
+**Note**: this router is available only with Django 2.x or above, since this feature was introduced in 2.0. See [release note][simplified-routing-release-note]
+
 ## DefaultRouter
 
 This router is similar to `SimpleRouter` as above, but additionally includes a default API root view, that returns a response containing hyperlinks to all the list views.  It also generates routes for optional `.json` style format suffixes.
@@ -340,3 +346,5 @@ The [`DRF-extensions` package][drf-extensions] provides [routers][drf-extensions
 [drf-extensions-customizable-endpoint-names]: https://chibisov.github.io/drf-extensions/docs/#controller-endpoint-name
 [url-namespace-docs]: https://docs.djangoproject.com/en/1.11/topics/http/urls/#url-namespaces
 [include-api-reference]: https://docs.djangoproject.com/en/2.0/ref/urls/#include
+[simplified-routing-release-note]: https://docs.djangoproject.com/en/2.0/releases/2.0/#simplified-url-routing-syntax
+[path-convertes-topic-reference]: https://docs.djangoproject.com/en/2.0/topics/http/urls/#path-converters
diff --git a/rest_framework/routers.py b/rest_framework/routers.py
@@ -23,6 +23,7 @@
 from django.utils.deprecation import RenameMethodsBase
 
 from rest_framework import RemovedInDRF311Warning, views
+from rest_framework.compat import path
 from rest_framework.response import Response
 from rest_framework.reverse import reverse
 from rest_framework.schemas import SchemaGenerator
@@ -99,50 +100,10 @@ def urls(self):
         return self._urls
 
 
-class SimpleRouter(BaseRouter):
-
-    routes = [
-        # List route.
-        Route(
-            url=r'^{prefix}{trailing_slash}$',
-            mapping={
-                'get': 'list',
-                'post': 'create'
-            },
-            name='{basename}-list',
-            detail=False,
-            initkwargs={'suffix': 'List'}
-        ),
-        # Dynamically generated list routes. Generated using
-        # @action(detail=False) decorator on methods of the viewset.
-        DynamicRoute(
-            url=r'^{prefix}/{url_path}{trailing_slash}$',
-            name='{basename}-{url_name}',
-            detail=False,
-            initkwargs={}
-        ),
-        # Detail route.
-        Route(
-            url=r'^{prefix}/{lookup}{trailing_slash}$',
-            mapping={
-                'get': 'retrieve',
-                'put': 'update',
-                'patch': 'partial_update',
-                'delete': 'destroy'
-            },
-            name='{basename}-detail',
-            detail=True,
-            initkwargs={'suffix': 'Instance'}
-        ),
-        # Dynamically generated detail routes. Generated using
-        # @action(detail=True) decorator on methods of the viewset.
-        DynamicRoute(
-            url=r'^{prefix}/{lookup}/{url_path}{trailing_slash}$',
-            name='{basename}-{url_name}',
-            detail=True,
-            initkwargs={}
-        ),
-    ]
+class AbstractSimpleRouter(BaseRouter):
+    """
+    Base class for SimpleRouter and SimplePathRouter.
+    """
 
     def __init__(self, trailing_slash=True):
         self.trailing_slash = '/' if trailing_slash else ''
@@ -223,6 +184,52 @@ def get_method_map(self, viewset, method_map):
                 bound_methods[method] = action
         return bound_methods
 
+
+class SimpleRouter(AbstractSimpleRouter):
+
+    routes = [
+        # List route.
+        Route(
+            url=r'^{prefix}{trailing_slash}$',
+            mapping={
+                'get': 'list',
+                'post': 'create'
+            },
+            name='{basename}-list',
+            detail=False,
+            initkwargs={'suffix': 'List'}
+        ),
+        # Dynamically generated list routes. Generated using
+        # @action(detail=False) decorator on methods of the viewset.
+        DynamicRoute(
+            url=r'^{prefix}/{url_path}{trailing_slash}$',
+            name='{basename}-{url_name}',
+            detail=False,
+            initkwargs={}
+        ),
+        # Detail route.
+        Route(
+            url=r'^{prefix}/{lookup}{trailing_slash}$',
+            mapping={
+                'get': 'retrieve',
+                'put': 'update',
+                'patch': 'partial_update',
+                'delete': 'destroy'
+            },
+            name='{basename}-detail',
+            detail=True,
+            initkwargs={'suffix': 'Instance'}
+        ),
+        # Dynamically generated detail routes. Generated using
+        # @action(detail=True) decorator on methods of the viewset.
+        DynamicRoute(
+            url=r'^{prefix}/{lookup}/{url_path}{trailing_slash}$',
+            name='{basename}-{url_name}',
+            detail=True,
+            initkwargs={}
+        ),
+    ]
+
     def get_lookup_regex(self, viewset, lookup_prefix=''):
         """
         Given a viewset, return the portion of URL regex that is used
@@ -290,6 +297,122 @@ def get_urls(self):
         return ret
 
 
+class SimplePathRouter(AbstractSimpleRouter):
+    """
+    Router which uses Django 2.x path to build urls
+    """
+
+    routes = [
+        # List route.
+        Route(
+            url='{prefix}{trailing_slash}',
+            mapping={
+                'get': 'list',
+                'post': 'create'
+            },
+            name='{basename}-list',
+            detail=False,
+            initkwargs={'suffix': 'List'}
+        ),
+        # Dynamically generated list routes. Generated using
+        # @action(detail=False) decorator on methods of the viewset.
+        DynamicRoute(
+            url='{prefix}/{url_path}{trailing_slash}',
+            name='{basename}-{url_name}',
+            detail=False,
+            initkwargs={}
+        ),
+        # Detail route.
+        Route(
+            url='{prefix}/{lookup}{trailing_slash}',
+            mapping={
+                'get': 'retrieve',
+                'put': 'update',
+                'patch': 'partial_update',
+                'delete': 'destroy'
+            },
+            name='{basename}-detail',
+            detail=True,
+            initkwargs={'suffix': 'Instance'}
+        ),
+        # Dynamically generated detail routes. Generated using
+        # @action(detail=True) decorator on methods of the viewset.
+        DynamicRoute(
+            url='{prefix}/{lookup}/{url_path}{trailing_slash}',
+            name='{basename}-{url_name}',
+            detail=True,
+            initkwargs={}
+        ),
+    ]
+
+    def get_lookup_path(self, viewset, lookup_prefix=''):
+        """
+        Given a viewset, return the portion of URL path that is used
+        to match against a single instance.
+
+        Note that lookup_prefix is not used directly inside REST rest_framework
+        itself, but is required in order to nicely support nested router
+        implementations, such as drf-nested-routers.
+
+        https://github.com/alanjds/drf-nested-routers
+        """
+        base_converter = '<{lookup_converter}:{lookup_prefix}{lookup_url_kwarg}>'
+        # Use `pk` as default field, unset set.  Default regex should not
+        # consume `.json` style suffixes and should break at '/' boundaries.
+        lookup_field = getattr(viewset, 'lookup_field', 'pk')
+        lookup_url_kwarg = getattr(viewset, 'lookup_url_kwarg', None) or lookup_field
+        lookup_converter = getattr(viewset, 'lookup_converter', 'path')
+        return base_converter.format(
+            lookup_prefix=lookup_prefix,
+            lookup_url_kwarg=lookup_url_kwarg,
+            lookup_converter=lookup_converter
+        )
+
+    def get_urls(self):
+        """
+        Use the registered viewsets to generate a list of URL patterns.
+        """
+        assert path is not None, 'SimplePathRouter requires Django 2.x path'
+        ret = []
+
+        for prefix, viewset, basename in self.registry:
+            lookup = self.get_lookup_path(viewset)
+            routes = self.get_routes(viewset)
+
+            for route in routes:
+
+                # Only actions which actually exist on the viewset will be bound
+                mapping = self.get_method_map(viewset, route.mapping)
+                if not mapping:
+                    continue
+
+                # Build the url pattern
+                url_path = route.url.format(
+                    prefix=prefix,
+                    lookup=lookup,
+                    trailing_slash=self.trailing_slash
+                )
+
+                # If there is no prefix, the first part of the url is probably
+                #   controlled by project's urls.py and the router is in an app,
+                #   so a slash in the beginning will (A) cause Django to give
+                #   warnings and (B) generate URLS that will require using '//'.
+                if not prefix and url_path[0] == '/':
+                    url_path = url_path[1:]
+
+                initkwargs = route.initkwargs.copy()
+                initkwargs.update({
+                    'basename': basename,
+                    'detail': route.detail,
+                })
+
+                view = viewset.as_view(mapping, **initkwargs)
+                name = route.name.format(basename=basename)
+                ret.append(path(url_path, view, name=name))
+
+        return ret
+
+
 class APIRootView(views.APIView):
     """
     The default basic root view for DefaultRouter
diff --git a/tests/test_routers.py b/tests/test_routers.py
@@ -2,6 +2,7 @@
 from collections import namedtuple
 
 import pytest
+import django
 from django.conf.urls import include, url
 from django.core.exceptions import ImproperlyConfigured
 from django.db import models
@@ -11,11 +12,15 @@
 from rest_framework import (
     RemovedInDRF311Warning, permissions, serializers, viewsets
 )
-from rest_framework.compat import get_regex_pattern
+from rest_framework.compat import get_regex_pattern, path
 from rest_framework.decorators import action
 from rest_framework.response import Response
-from rest_framework.routers import DefaultRouter, SimpleRouter
-from rest_framework.test import APIRequestFactory, URLPatternsTestCase
+from rest_framework.routers import (
+    DefaultRouter, SimplePathRouter, SimpleRouter
+)
+from rest_framework.test import (
+    APIClient, APIRequestFactory, URLPatternsTestCase
+)
 from rest_framework.utils import json
 
 factory = APIRequestFactory()
@@ -80,9 +85,25 @@ def regex_url_path_detail(self, request, *args, **kwargs):
         return Response({'pk': pk, 'kwarg': kwarg})
 
 
+class UrlPathViewSet(viewsets.ViewSet):
+    @action(detail=False, url_path='list/<int:kwarg>')
+    def url_path_list(self, request, *args, **kwargs):
+        kwarg = self.kwargs.get('kwarg', '')
+        return Response({'kwarg': kwarg})
+
+    @action(detail=True, url_path='detail/<int:kwarg>')
+    def url_path_detail(self, request, *args, **kwargs):
+        pk = self.kwargs.get('pk', '')
+        kwarg = self.kwargs.get('kwarg', '')
+        return Response({'pk': pk, 'kwarg': kwarg})
+
+
 notes_router = SimpleRouter()
 notes_router.register(r'notes', NoteViewSet)
 
+notes_path_router = SimplePathRouter()
+notes_path_router.register('notes', NoteViewSet)
+
 kwarged_notes_router = SimpleRouter()
 kwarged_notes_router.register(r'notes', KWargedNoteViewSet)
 
@@ -95,6 +116,9 @@ def regex_url_path_detail(self, request, *args, **kwargs):
 regex_url_path_router = SimpleRouter()
 regex_url_path_router.register(r'', RegexUrlPathViewSet, basename='regex')
 
+url_path_router = SimplePathRouter()
+url_path_router.register('', UrlPathViewSet, basename='path')
+
 
 class BasicViewSet(viewsets.ViewSet):
     def list(self, request, *args, **kwargs):
@@ -466,6 +490,69 @@ def test_regex_url_path_detail(self):
         assert json.loads(response.content.decode()) == {'pk': pk, 'kwarg': kwarg}
 
 
+@pytest.mark.skipif(django.VERSION < (2, 0), reason='Django version < 2.0')
+class TestUrlPath(URLPatternsTestCase, TestCase):
+    client_class = APIClient
+    urlpatterns = [
+        path('path/', include(url_path_router.urls)),
+        path('example/', include(notes_path_router.urls))
+    ]
+
+    def setUp(self):
+        RouterTestModel.objects.create(uuid='123', text='foo bar')
+        RouterTestModel.objects.create(uuid='a b', text='baz qux')
+
+    def test_create(self):
+        new_note = {
+            'uuid': 'foo',
+            'text': 'example'
+        }
+        response = self.client.post('/example/notes/', data=new_note)
+        assert response.status_code == 201
+        assert response['location'] == 'http://testserver/example/notes/foo/'
+        assert response.data == {"url": "http://testserver/example/notes/foo/", "uuid": "foo", "text": "example"}
+        assert RouterTestModel.objects.filter(uuid='foo').first() is not None
+
+    def test_retrieve(self):
+        response = self.client.get('/example/notes/123/')
+        assert response.status_code == 200
+        assert response.data == {"url": "http://testserver/example/notes/123/", "uuid": "123", "text": "foo bar"}
+
+    def test_list(self):
+        response = self.client.get('/example/notes/')
+        assert response.status_code == 200
+        assert response.data == [
+            {"url": "http://testserver/example/notes/123/", "uuid": "123", "text": "foo bar"},
+            {"url": "http://testserver/example/notes/a%20b/", "uuid": "a b", "text": "baz qux"},
+        ]
+
+    def test_update(self):
+        updated_note = {
+            'text': 'foo bar example'
+        }
+        response = self.client.patch('/example/notes/123/', data=updated_note)
+        assert response.status_code == 200
+        assert response.data == {"url": "http://testserver/example/notes/123/", "uuid": "123", "text": "foo bar example"}
+
+    def test_delete(self):
+        response = self.client.delete('/example/notes/123/')
+        assert response.status_code == 204
+        assert RouterTestModel.objects.filter(uuid='123').first() is None
+
+    def test_list_extra_action(self):
+        kwarg = 1234
+        response = self.client.get('/path/list/{}/'.format(kwarg))
+        assert response.status_code == 200
+        assert json.loads(response.content.decode()) == {'kwarg': kwarg}
+
+    def test_detail_extra_action(self):
+        pk = '1'
+        kwarg = 1234
+        response = self.client.get('/path/{}/detail/{}/'.format(pk, kwarg))
+        assert response.status_code == 200
+        assert json.loads(response.content.decode()) == {'pk': pk, 'kwarg': kwarg}
+
+
 class TestViewInitkwargs(URLPatternsTestCase, TestCase):
     urlpatterns = [
         url(r'^example/', include(notes_router.urls)),
