authentication method docs wrong or confusing WRT returned value

[Preston Holmes]

The two methods listed below use the phrasing "Always returns [boolean]" Though I am new enough not to have used this in a project directly , nor facile enough to whip up a test, it seems that the return value would depend on the anon/auth status of the user and that the appropriate boolean would be returned.

is_anonymous()
Always returns False. This is a way of differentiating User and AnonymousUser objects. Generally, you should prefer using is_authenticated() to this method.

is_authenticated()
Always returns True. This is a way to tell if the user has been authenticated. This does not imply any permissions, and doesn't check if the user is active - it only indicates that the user has provided a valid username and password.

-P

[Gary Wilson]

The documentation you are looking at is for the User model, in which case the "Always returns True/False" statements are correct. In the AnonymousUser's methods these values are opposite. I do agree however, that the documentation for is_authenticated could be clearer and also mention the fact that it's really only there to distinguish between a User and an AnonymousUser. The mention of "it only indicates that the user has provided a valid username and password" should also be clarified because the is_authenticated method itself does not check this either. We should mention the AuthenticationMiddleware here.

[Aymeric Augustin]

Change UI/UX from NULL to False.

[Aymeric Augustin]

Change Easy pickings from NULL to False.

[rshea]

How about leaving is_anonymous() in its current form:

is_anonymous()

Always returns False. This is a way of differentiating User and AnonymousUser objects. Generally, you should prefer using is_authenticated() to this method.

and revising is_authenticated() to emphasize that it simply checks the type of object inserted into request.user within views by the AuthenticationMiddleware as recommended by gwilson. Perhaps:

is_authenticated()

Always returns True. Contrast this with AnonymousUser.is_authenticated(), which always returns False. This is a way to tell if the user has been authenticated. This does not imply any permissions, and doesn't check if the user is active - it only indicates that the request.user object within the view has been populated by the AuthenticationMiddleware with a User object representing the currently logged- in user.

I'm not completely happy with this revised definition of is_authenticated() due to the verbose phrasing around request.user, but I do think this is a more precise definition of what the function is doing.

[Tim Graham <timograham@…>]

In ac4d82b94a700214ebb13bcdcbbdd4fd9bdefc0f:

Fixed #9913 - Clarified User.is_authenticated docs.

Thanks rshea for the draft text.

[Tim Graham <timograham@…>]

In 930cd8eebb947239c84e8fd1c71294441c5abea3:

[1.5.x] Fixed #9913 - Clarified User.is_authenticated docs.

Thanks rshea for the draft text.

Backport of ac4d82b94a from master