From b78872b7dbb55f1aa2d21f15fbb952f0c7156326 Mon Sep 17 00:00:00 2001
From: Tom Christie
Date: Wed, 17 Oct 2012 15:23:36 +0100
Subject: Use two seperate exceptions - `AuthenticationFailed`, and
 `NotAuthenticated`

Cleaner seperation of exception and resulting HTTP response.
Should result in more obvious error messages.
---
 docs/api-guide/authentication.md |  4 ++--
 docs/api-guide/exceptions.md     | 16 ++++++++++++----
 2 files changed, 14 insertions(+), 6 deletions(-)

(limited to 'docs/api-guide')

diff --git a/docs/api-guide/authentication.md b/docs/api-guide/authentication.md
index 06f428c0..3ace6519 100644
--- a/docs/api-guide/authentication.md
+++ b/docs/api-guide/authentication.md
@@ -156,12 +156,12 @@ Unauthenticated responses that are denied permission will result in an `HTTP 403
 
 To implement a custom authentication scheme, subclass `BaseAuthentication` and override the `.authenticate(self, request)` method.  The method should return a two-tuple of `(user, auth)` if authentication succeeds, or `None` otherwise.
 
-In some circumstances instead of returning `None`, you may want to raise an `Unauthenticated` exception from the `.authenticate()` method.
+In some circumstances instead of returning `None`, you may want to raise an `AuthenticationFailed` exception from the `.authenticate()` method.
 
 Typically the approach you should take is:
 
 * If authentication is not attempted, return `None`.  Any other authentication schemes also in use will still be checked.
-* If authentication is attempted but fails, raise an `Unauthenticated` exception.  An error response will be returned immediately, without checking any other authentication schemes.
+* If authentication is attempted but fails, raise a `AuthenticationFailed` exception.  An error response will be returned immediately, without checking any other authentication schemes.
 
 You *may* also override the `.authentication_header(self, request)` method.  If implemented, it should return a string that will be used as the value of the `WWW-Authenticate` header in a `HTTP 401 Unauthorized` response.
 
diff --git a/docs/api-guide/exceptions.md b/docs/api-guide/exceptions.md
index f5dff94a..c30f586a 100644
--- a/docs/api-guide/exceptions.md
+++ b/docs/api-guide/exceptions.md
@@ -49,11 +49,19 @@ Raised if the request contains malformed data when accessing `request.DATA` or `
 
 By default this exception results in a response with the HTTP status code "400 Bad Request".
 
-## Unauthenticated
+## AuthenticationFailed
 
-**Signature:** `Unauthenticated(detail=None)`
+**Signature:** `AuthenticationFailed(detail=None)`
 
-Raised when an unauthenticated incoming request fails the permission checks.
+Raised when an incoming request includes incorrect authentication.
+
+By default this exception results in a response with the HTTP status code "401 Unauthenticated", but it may also result in a "403 Forbidden" response, depending on the authentication scheme in use.  See the [authentication documentation][authentication] for more details.
+
+## NotAuthenticated
+
+**Signature:** `NotAuthenticated(detail=None)`
+
+Raised when an unauthenticated request fails the permission checks.
 
 By default this exception results in a response with the HTTP status code "401 Unauthenticated", but it may also result in a "403 Forbidden" response, depending on the authentication scheme in use.  See the [authentication documentation][authentication] for more details.
 
@@ -61,7 +69,7 @@ By default this exception results in a response with the HTTP status code "401 U
 
 **Signature:** `PermissionDenied(detail=None)`
 
-Raised when an authenticated incoming request fails the permission checks.
+Raised when an authenticated request fails the permission checks.
 
 By default this exception results in a response with the HTTP status code "403 Forbidden".
 
-- 
cgit v1.2.3