Code

Opened 6 years ago

Closed 16 months ago

Last modified 16 months ago

#9913 closed New feature (fixed)

authentication method docs wrong or confusing WRT returned value

Reported by: ptone Owned by: nobody
Component: Documentation Version: master
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

Attachments (0)

Change History (7)

comment:1 Changed 5 years ago by gwilson

  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset
  • Triage Stage changed from Unreviewed to Accepted

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 Changed 3 years ago by SmileyChris

  • Severity set to Normal
  • Type set to New feature

comment:3 Changed 2 years ago by aaugustin

  • UI/UX unset

Change UI/UX from NULL to False.

comment:4 Changed 2 years ago by aaugustin

  • Easy pickings unset

Change Easy pickings from NULL to False.

comment:5 Changed 21 months ago by 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.

comment:6 Changed 16 months ago by Tim Graham <timograham@…>

  • Resolution set to fixed
  • Status changed from new to closed

In ac4d82b94a700214ebb13bcdcbbdd4fd9bdefc0f:

Fixed #9913 - Clarified User.is_authenticated docs.

Thanks rshea for the draft text.

comment:7 Changed 16 months ago by 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

Add Comment

Modify Ticket

Change Properties
<Author field>
Action
as closed
as The resolution will be set. Next status will be 'closed'
The resolution will be deleted. Next status will be 'new'
Author


E-mail address and user name can be saved in the Preferences.

 
Note: See TracTickets for help on using tickets.