From 44f755035d323e9c8817ec57b9879ab683b9f0d4 Mon Sep 17 00:00:00 2001 From: Mariusz Felisiak Date: Mon, 28 Nov 2022 08:13:51 +0100 Subject: [PATCH] [4.1.x] Doc's check_password()'s setter and preferred arguments. Follow up to 90e05aaeac612a4251640564aa65f103ac635e12. Backport of 662497cece5480b39d1d0c7f68c7b0ca395be923 from main --- docs/topics/auth/passwords.txt | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/docs/topics/auth/passwords.txt b/docs/topics/auth/passwords.txt index 37ce8514b037f..504766f7d0efc 100644 --- a/docs/topics/auth/passwords.txt +++ b/docs/topics/auth/passwords.txt @@ -485,14 +485,18 @@ The :mod:`django.contrib.auth.hashers` module provides a set of functions to create and validate hashed passwords. You can use them independently from the ``User`` model. -.. function:: check_password(password, encoded) +.. function:: check_password(password, encoded, setter=None, preferred="default") If you'd like to manually authenticate a user by comparing a plain-text password to the hashed password in the database, use the convenience - function :func:`check_password`. It takes two arguments: the plain-text - password to check, and the full value of a user's ``password`` field in the - database to check against, and returns ``True`` if they match, ``False`` - otherwise. + function :func:`check_password`. It takes two mandatory arguments: the + plain-text password to check, and the full value of a user's ``password`` + field in the database to check against. It returns ``True`` if they match, + ``False`` otherwise. Optionally, you can pass a callable ``setter`` that + takes the password and will be called when you need to regenerate it. You + can also pass ``preferred`` to change a hashing algorithm if you don't want + to use the default (first entry of ``PASSWORD_HASHERS`` setting). See + :ref:`auth-included-hashers` for the algorithm name of each hasher. .. function:: make_password(password, salt=None, hasher='default')