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

Backport of f7e91cac68 from master

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.

tests/auth_tests/test_basic.py

@@ -3,10 +3,11 @@ from __future__ import unicode_literals
 
 import warnings
 
-from django.contrib.auth import get_user_model
+from django.contrib.auth import get_user, get_user_model
 from django.contrib.auth.models import AnonymousUser, User
 from django.core.exceptions import ImproperlyConfigured
 from django.db import IntegrityError
+from django.http import HttpRequest
 from django.test import TestCase, override_settings
 from django.utils import translation
 
@@ -158,3 +159,21 @@ class BasicTestCase(TestCase):
         with translation.override('es'):
             self.assertEqual(User._meta.verbose_name, 'usuario')
             self.assertEqual(User._meta.verbose_name_plural, 'usuarios')
+
+
+class TestGetUser(TestCase):
+
+    def test_get_user_anonymous(self):
+        request = HttpRequest()
+        request.session = self.client.session
+        user = get_user(request)
+        self.assertIsInstance(user, AnonymousUser)
+
+    def test_get_user(self):
+        created_user = User.objects.create_user('testuser', 'test@example.com', 'testpw')
+        self.client.login(username='testuser', password='testpw')
+        request = HttpRequest()
+        request.session = self.client.session
+        user = get_user(request)
+        self.assertIsInstance(user, User)
+        self.assertEqual(user.username, created_user.username)