[1.10.x] Fixed #27053 -- Documented contrib.auth.get_user().

Backport of f7e91cac689b28fc32ca52cdeac258ec0d58b4fc from master

1 files changed, 23 insertions, 0 deletions

diff --git a/docs/ref/contrib/auth.txt b/docs/ref/contrib/auth.txt
index 5836cb329e..c0e4f5bdc6 100644
--- a/docs/ref/contrib/auth.txt
+++ b/docs/ref/contrib/auth.txt
@@ -645,3 +645,26 @@ The following backends are available in :mod:`django.contrib.auth.backends`:
    Same as :class:`RemoteUserBackend` except that it doesn't reject inactive
    users because :attr:`~RemoteUserBackend.user_can_authenticate` always
    returns ``True``.
+
+Utility functions
+=================
+
+.. currentmodule:: django.contrib.auth
+
+.. function:: get_user(request)
+
+    Returns the user model instance associated with the given ``request``’s
+    session.
+
+    It checks if the authentication backend stored in the session is present in
+    :setting:`AUTHENTICATION_BACKENDS`. If so, it uses the backend's
+    ``get_user()`` method to retrieve the user model instance and then verifies
+    the session by calling the user model's
+    :meth:`~django.contrib.auth.models.AbstractBaseUser.get_session_auth_hash`
+    method.
+
+    Returns an instance of :class:`~django.contrib.auth.models.AnonymousUser`
+    if the authentication backend stored in the session is no longer in
+    :setting:`AUTHENTICATION_BACKENDS`, if a user isn't returned by the
+    backend's ``get_user()`` method, or if the session auth hash doesn't
+    validate.