From 6c6eb8a6917a538968201267f943ef581db1c22d Mon Sep 17 00:00:00 2001
From: Tim Graham <timograham@gmail.com>
Date: Thu, 20 Aug 2015 10:16:09 -0400
Subject: [PATCH] Refs #24914 -- Added docs for more auth mixin methods.
---
docs/topics/auth/default.txt | 59 ++++++++++++++++++++++++++----------
1 file changed, 43 insertions(+), 16 deletions(-)
diff --git a/docs/topics/auth/default.txt b/docs/topics/auth/default.txt
index bffd61588e..e0bbb6eb64 100644
--- a/docs/topics/auth/default.txt
+++ b/docs/topics/auth/default.txt
@@ -607,17 +607,25 @@ redirects to the login page::
When using :doc:`class-based views </topics/class-based-views/index>`, you
can use the ``UserPassesTestMixin`` to do this.
- You have to override the ``test_func()`` method of the class to provide
- the test that is performed. Furthermore, you can set any of the parameters
- of :class:`~django.contrib.auth.mixins.AccessMixin` to customize the
- handling of unauthorized users::
+ .. method:: test_func()
- from django.contrib.auth.mixins import UserPassesTestMixin
+ You have to override the ``test_func()`` method of the class to
+ provide the test that is performed. Furthermore, you can set any of the
+ parameters of :class:`~django.contrib.auth.mixins.AccessMixin` to
+ customize the handling of unauthorized users::
- class MyView(UserPassesTestMixin, View):
+ from django.contrib.auth.mixins import UserPassesTestMixin
- def test_func(self):
- return self.request.user.email.endswith('@example.com')
+ class MyView(UserPassesTestMixin, View):
+
+ def test_func(self):
+ return self.request.user.email.endswith('@example.com')
+
+ .. method:: get_test_func()
+
+ You can also override the ``get_test_func()`` method to have the mixin
+ use a differently named function for its checks (instead of
+ :meth:`test_func`).
.. admonition:: Stacking ``UserPassesTestMixin``
@@ -741,20 +749,19 @@ user to the login page or issue an HTTP 403 Forbidden response.
.. attribute:: login_url
- The URL that users who don't pass the test will be redirected to.
- Defaults to :setting:`settings.LOGIN_URL <LOGIN_URL>`.
+ Default return value for :meth:`get_login_url`. Defaults to ``None``
+ in which case :meth:`get_login_url` falls back to
+ :setting:`settings.LOGIN_URL <LOGIN_URL>`.
.. attribute:: permission_denied_message
- When ``raise_exception`` is ``True``, this attribute can be used to
- control the error message passed to the error handler for display to
- the user. Defaults to an empty string.
+ Default return value for :meth:`get_permission_denied_message`.
+ Defaults to an empty string.
.. attribute:: redirect_field_name
- The name of the query parameter that will contain the URL the user
- should be redirected to after a successful login. If you set this to
- ``None``, a query parameter won't be added. Defaults to ``"next"``.
+ Default return value for :meth:`get_redirect_field_name`. Defaults to
+ ``"next"``.
.. attribute:: raise_exception
@@ -762,6 +769,26 @@ user to the login page or issue an HTTP 403 Forbidden response.
:class:`~django.core.exceptions.PermissionDenied` exception will be
raised instead of the redirect. Defaults to ``False``.
+ .. method:: get_login_url()
+
+ Returns the URL that users who don't pass the test will be redirected
+ to. Returns :attr:`login_url` if set, or :setting:`settings.LOGIN_URL
+ <LOGIN_URL>` otherwise.
+
+ .. method:: get_permission_denied_message()
+
+ When :attr:`raise_exception` is ``True``, this method can be used to
+ control the error message passed to the error handler for display to
+ the user. Returns the :attr:`permission_denied_message` attribute by
+ default.
+
+ .. method:: get_redirect_field_name()
+
+ Returns the name of the query parameter that will contain the URL the
+ user should be redirected to after a successful login. If you set this
+ to ``None``, a query parameter won't be added. Returns the
+ :attr:`redirect_field_name` attribute by default.
+
.. method:: handle_no_permission()
Depending on the value of ``raise_exception``, the method either raises