Document how user permission caching works

[Giggaflop]

Could it be mentioned on the ​API Methods for Django authentication that it may be required that the User object is reobtained if dynamically adding permissions. This is due to them being cached by Django.

This was not made clear by the documentation and has wasted considerable amount of time tracking down until i hit upon this ​Stack Overflow.

[Tim Graham]

Yes, this seems like a good thing to mention. Do you think you could write up a patch or simply some text about what you would say?

[Giggaflop]

I would do something along the lines of.

It may be required that the User object is reobtained if dynamically adding permissions. This is due to them being cached by Django.

def user_gains_perms(request, user_id):
    user = get_object_or_404(pk=user_id)
    permission = Permission.objects.get(codename="all_the_things")
    user.user_permissions.add(permission)

    # Note the user object has not gained the permission
    user.has_perms('all_the_things') # False

    # Request new instance of User
    user = get_object_or_404(pk=user_id)
    
    # Now note how the permissions have been updated
    user.has_perms('all_the_things') # True

    return HttpResponseRedirect(reverse('index'))

[Daniele Procida]

I've marked this ticket as especially suitable for first-time committers or people following the ​Don't be afraid to commit tutorial. If you're tackling this ticket, please don't hesitate to ask me for guidance if you'd like any, either here or on the Django IRC channels, where I can be found as EvilDMP.

[Jennifer]

I notice that the documentation referred to in the original report is for django 1.3 here is the link for the latest documentation version: ​https://docs.djangoproject.com/en/dev/ref/contrib/auth/#methods

[Jennifer]

I have made pull request for review ​https://github.com/django/django/pull/1754

[Tim Graham]

I left some comments for improvement on the pull request.

[Tim Graham]

Here's a ​PR for review.

[Tim Graham <timograham@…>]

In 5f9790072d52443aff9a0e04f1552f1e29489521:

Fixed #20834 -- Described how caching of user permissions works.

Thanks Giggaflop and Jennifer Casavantes.

[Tim Graham <timograham@…>]

In 8eca53f0bef783e5c11877fe18a6651543605af1:

[1.6.x] Fixed #20834 -- Described how caching of user permissions works.

Thanks Giggaflop and Jennifer Casavantes.

Backport of 5f9790072d from master