Fixed #21379 -- Created auth-specific username validators

Thanks Tim Graham for the review.

2 files changed, 65 insertions, 1 deletions

diff --git a/docs/ref/contrib/auth.txt b/docs/ref/contrib/auth.txt
index 6e3b8892cf..5836cb329e 100644
--- a/docs/ref/contrib/auth.txt
+++ b/docs/ref/contrib/auth.txt
@@ -32,6 +32,15 @@ Fields
         ``max_length=191`` because MySQL can only create unique indexes with
         191 characters in that case by default.
 
+        .. admonition:: Usernames and Unicode
+
+            Django originally accepted only ASCII letters in usernames.
+            Although it wasn't a deliberate choice, Unicode characters have
+            always been accepted when using Python 3. Django 1.10 officially
+            added Unicode support in usernames, keeping the ASCII-only behavior
+            on Python 2, with the option to customize the behavior using
+            :attr:`.User.username_validator`.
+
         .. versionchanged:: 1.10
 
             The ``max_length`` increased from 30 to 150 characters.
@@ -146,6 +155,27 @@ Attributes
             In older versions, this was a method. Backwards-compatibility
             support for using it as a method will be removed in Django 2.0.
 
+    .. attribute:: username_validator
+
+        .. versionadded:: 1.10
+
+        Points to a validator instance used to validate usernames. Defaults to
+        :class:`validators.UnicodeUsernameValidator` on Python 3 and
+        :class:`validators.ASCIIUsernameValidator` on Python 2.
+
+        To change the default username validator, you can subclass the ``User``
+        model and set this attribute to a different validator instance. For
+        example, to use ASCII usernames on Python 3::
+
+            from django.contrib.auth.models import User
+            from django.contrib.auth.validators import ASCIIUsernameValidator
+
+            class CustomUser(User):
+                username_validator = ASCIIUsernameValidator()
+
+                class Meta:
+                    proxy = True  # If no new field is added.
+
 Methods
 -------
 
@@ -285,7 +315,6 @@ Manager methods
         Same as :meth:`create_user`, but sets :attr:`~models.User.is_staff` and
         :attr:`~models.User.is_superuser` to ``True``.
 
-
 ``AnonymousUser`` object
 ========================
 
@@ -378,6 +407,25 @@ Fields
             group.permissions.remove(permission, permission, ...)
             group.permissions.clear()
 
+Validators
+==========
+
+.. class:: validators.ASCIIUsernameValidator
+
+    .. versionadded:: 1.10
+
+    A field validator allowing only ASCII letters, in addition to ``@``, ``.``,
+    ``+``, ``-``, and ``_``. The default validator for ``User.username`` on
+    Python 2.
+
+.. class:: validators.UnicodeUsernameValidator
+
+    .. versionadded:: 1.10
+
+    A field validator allowing Unicode letters, in addition to ``@``, ``.``,
+    ``+``, ``-``, and ``_``. The default validator for ``User.username`` on
+    Python 3.
+
 .. _topics-auth-signals:
 
 Login and logout signals
diff --git a/docs/releases/1.10.txt b/docs/releases/1.10.txt
index 35cf1d42c3..fa5d3ff108 100644
--- a/docs/releases/1.10.txt
+++ b/docs/releases/1.10.txt
@@ -37,6 +37,22 @@ It also now includes trigram support, using the :lookup:`trigram_similar`
 lookup, and the :class:`~django.contrib.postgres.search.TrigramSimilarity` and
 :class:`~django.contrib.postgres.search.TrigramDistance` expressions.
 
+Official support for Unicode usernames
+--------------------------------------
+
+The :class:`~django.contrib.auth.models.User` model in ``django.contrib.auth``
+originally only accepted ASCII letters in usernames. Although it wasn't a
+deliberate choice, Unicode characters have always been accepted when using
+Python 3.
+
+The username validator now explicitly accepts Unicode letters by
+default on Python 3 only. This default behavior can be overridden by changing
+the :attr:`~django.contrib.auth.models.User.username_validator` attribute of
+the ``User`` model, or to any proxy of that model, using either
+:class:`~django.contrib.auth.validators.ASCIIUsernameValidator` or
+:class:`~django.contrib.auth.validators.UnicodeUsernameValidator`. Custom user
+models may also use those validators.
+
 Minor features
 --------------