Allow permission classes to customize the failure message.

docs/api-guide/permissions.md

@@ -205,6 +205,16 @@ If you need to test if a request is a read operation or a write operation, you s
 
 ---
 
+Custom permissions will raise a `PermissionDenied` exception if the test fails. To change the error message associated with the exception, implement a `message` attribute directly on your custom permission. Otherwise the `default_detail` attribute from `PermissionDenied` will be used.
+
+    from rest_framework import permissions
+
+    class CustomerAccessPermission(permissions.BasePermission):
+        message = 'Adding customers not allowed.'
+
+        def has_permission(self, request, view):
+             ...
+
 ## Examples
 
 The following is an example of a permission class that checks the incoming request's IP address against a blacklist, and denies the request if the IP has been blacklisted.

rest_framework/views.py

@@ -134,12 +134,14 @@ def http_method_not_allowed(self, request, *args, **kwargs):
         """
         raise exceptions.MethodNotAllowed(request.method)
 
-    def permission_denied(self, request):
+    def permission_denied(self, request, message=None):
         """
         If request is not permitted, determine what kind of exception to raise.
         """
         if not request.successful_authenticator:
             raise exceptions.NotAuthenticated()
+        if message is not None:
+            raise exceptions.PermissionDenied(message)
         raise exceptions.PermissionDenied()
 
     def throttled(self, request, wait):
@@ -280,6 +282,8 @@ def check_permissions(self, request):
         """
         for permission in self.get_permissions():
             if not permission.has_permission(request, self):
+                if hasattr(permission, 'message'):
+                    self.permission_denied(request, permission.message)
                 self.permission_denied(request)
 
     def check_object_permissions(self, request, obj):
@@ -289,6 +293,8 @@ def check_object_permissions(self, request, obj):
         """
         for permission in self.get_permissions():
             if not permission.has_object_permission(request, self, obj):
+                if hasattr(permission, 'message'):
+                    self.permission_denied(request, permission.message)
                 self.permission_denied(request)
 
     def check_throttles(self, request):

tests/test_permissions.py

@@ -310,3 +310,89 @@ def test_cannot_read_list_permissions(self):
         response = object_permissions_list_view(request)
         self.assertEqual(response.status_code, status.HTTP_200_OK)
         self.assertListEqual(response.data, [])
+
+
+class BasicPerm(permissions.BasePermission):
+    def has_permission(self, request, view):
+        return False
+
+
+class BasicPermWithDetail(permissions.BasePermission):
+    message = 'Custom: You cannot post to this resource'
+
+    def has_permission(self, request, view):
+        return False
+
+
+class BasicObjectPerm(permissions.BasePermission):
+    def has_object_permission(self, request, view, obj):
+        return False
+
+
+class BasicObjectPermWithDetail(permissions.BasePermission):
+    message = 'Custom: You cannot post to this resource'
+
+    def has_object_permission(self, request, view, obj):
+        return False
+
+
+class PermissionInstanceView(generics.RetrieveUpdateDestroyAPIView):
+    queryset = BasicModel.objects.all()
+    serializer_class = BasicSerializer
+
+
+class DeniedView(PermissionInstanceView):
+    permission_classes = (BasicPerm,)
+
+
+class DeniedViewWithDetail(PermissionInstanceView):
+    permission_classes = (BasicPermWithDetail,)
+
+
+class DeniedObjectView(PermissionInstanceView):
+    permission_classes = (BasicObjectPerm,)
+
+
+class DeniedObjectViewWithDetail(PermissionInstanceView):
+    permission_classes = (BasicObjectPermWithDetail,)
+
+denied_view = DeniedView.as_view()
+
+denied_view_with_detail = DeniedViewWithDetail.as_view()
+
+denied_object_view = DeniedObjectView.as_view()
+
+denied_object_view_with_detail = DeniedObjectViewWithDetail.as_view()
+
+
+class CustomPermissionsTests(TestCase):
+    def setUp(self):
+        BasicModel(text='foo').save()
+        User.objects.create_user('username', '[email protected]', 'password')
+        credentials = basic_auth_header('username', 'password')
+        self.request = factory.get('/1', format='json', HTTP_AUTHORIZATION=credentials)
+        self.custom_message = 'Custom: You cannot post to this resource'
+
+    def test_permission_denied(self):
+            response = denied_view(self.request, pk=1)
+            detail = response.data.get('detail')
+            self.assertEqual(response.status_code, status.HTTP_403_FORBIDDEN)
+            self.assertNotEqual(detail, self.custom_message)
+
+    def test_permission_denied_with_custom_detail(self):
+            response = denied_view_with_detail(self.request, pk=1)
+            detail = response.data.get('detail')
+            self.assertEqual(response.status_code, status.HTTP_403_FORBIDDEN)
+            self.assertEqual(detail, self.custom_message)
+
+    def test_permission_denied_for_object(self):
+            response = denied_object_view(self.request, pk=1)
+            detail = response.data.get('detail')
+            self.assertEqual(response.status_code, status.HTTP_403_FORBIDDEN)
+            self.assertNotEqual(detail, self.custom_message)
+
+    def test_permission_denied_for_object_with_custom_detail(self):
+            response = denied_object_view_with_detail(self.request, pk=1)
+            detail = response.data.get('detail')
+            self.assertEqual(response.status_code, status.HTTP_403_FORBIDDEN)
+            self.assertEqual(detail, self.custom_message)