Opened 15 years ago

Closed 11 years ago

Last modified 11 years ago

#9913 closed New feature (fixed)

authentication method docs wrong or confusing WRT returned value

Reported by: Preston Holmes Owned by: nobody
Component: Documentation Version: dev
Severity: Normal Keywords:
Cc: Triage Stage: Accepted
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

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

Change History (7)

comment:1 by Gary Wilson, 15 years ago

Triage Stage: UnreviewedAccepted

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.

comment:2 by Chris Beaven, 13 years ago

Severity: Normal
Type: New feature

comment:3 by Aymeric Augustin, 12 years ago

UI/UX: unset

Change UI/UX from NULL to False.

comment:4 by Aymeric Augustin, 12 years ago

Easy pickings: unset

Change Easy pickings from NULL to False.

comment:5 by rshea, 11 years ago

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.

comment:6 by Tim Graham <timograham@…>, 11 years ago

Resolution: fixed
Status: newclosed

In ac4d82b94a700214ebb13bcdcbbdd4fd9bdefc0f:

Fixed #9913 - Clarified User.is_authenticated docs.

Thanks rshea for the draft text.

comment:7 by Tim Graham <timograham@…>, 11 years ago

In 930cd8eebb947239c84e8fd1c71294441c5abea3:

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

Thanks rshea for the draft text.

Backport of ac4d82b94a from master

Note: See TracTickets for help on using tickets.
Back to Top