Documentation for PermWrapper is wrong

[Adrien Lemaire]

Doc says at /en/dev/topics/auth/:

The currently logged-in user's permissions are stored in the template variable {{ perms }}. This is an instance of django.contrib.auth.context_processors.PermWrapper, which is a template-friendly proxy of permissions.

Changed in Django 1.3: Prior to version 1.3, PermWrapper was located in django.contrib.auth.context_processors.

That is wrong, PermWrapper was located in django.core.context_processors.

[Adrien Lemaire]

Might also be a good idea to edit the documentation to let the user know that he doesn't need to add django.contrib.auth.context_processors.PermWrapper in his TEMPLATE_CONTEXT_PROCESSORS, because django.contrib.auth.context_processors.auth already includes it.

[Claude Paroz]

Patch marked as needs improvement due to your comment:2.

[Adrien Lemaire]

hmm I don't really know how to improve the doc. In fact, this information is already included in the doc:

.. admonition:: Technicality

   Technically, these variables are only made available in the template context
   if you use :class:`~django.template.context.RequestContext` *and* your
   :setting:`TEMPLATE_CONTEXT_PROCESSORS` setting contains
   ``"django.contrib.auth.context_processors.auth"``, which is default. For
   more, see the :ref:`RequestContext docs <subclassing-context-requestcontext>`.

I was looking for permissions and started to read from the subtitle without seeing the admonition.
Therefore, the doc is correct. My concern is about the time I needed to figure that out without reading the admonition:

Because I started with a bad {{ perms.app_label.can_edit_model }} (when it should be {{ perms.app_label.change_model }} , after reading the PermWrapper code, I though I'd need to call {{ request.perms.app_label.can_edit_model }} , to add the context_processor etc.

What would be nice is to raise a PermissionDoesNotExist or something like that if trying to call {{ perms.app_label.can_edit_model }} when DEBUG=True. If you agree with that, I'll create a new ticket because it's unrelated to the documentation.

[Claude Paroz]

In [17913]:

Fixed #18136 -- Fixed pre-1.3 PermWrapper? location in docs. Thanks Adrien Lemaire for the patch.

(Fixed by dyslectic claudep, s/18316/18136/)

[Claude Paroz]

Replying to Fandekasp:

What would be nice is to raise a PermissionDoesNotExist or something like that if trying to call {{ perms.app_label.can_edit_model }} when DEBUG=True. If you agree with that, I'll create a new ticket because it's unrelated to the documentation.

Yes, this would be another ticket, and the setting would be probably TEMPLATE_DEBUG.