Merge pull request #9 from PolicyStat/issue_9

Add real documentation about the smart cache.

docs/conf.py

@@ -46,10 +46,10 @@ copyright = u'2009, the django-authority team'
 # built documents.
 #
 # The short X.Y version.
-version = '0.4'
+version = '0.5'
 
 # The full version, including alpha/beta/rc tags.
-release = '0.4dev'
+release = '0.5dev'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/configuration.txt

@@ -32,6 +32,11 @@ context processors::
         'django.core.context_processors.request',
     )
 
+django-authority defaults to using a smart cache when checking permissions.
+This can be disabled by adding the following line to ``settings.py``::
+
+    AUTHORITY_USE_SMART_CACHE = False
+
 urls.py
 =======
 

docs/index.txt

@@ -23,6 +23,11 @@ This application provides three abilities:
    voodoo-code to Django's ``contrib.auth`` system, it keeps your existing
    permission system intact!
 
+django-authority uses a cache that is stored on the user object to help improve
+performance. However, if the ``Permission`` table changes the cache will need
+to be invalidated. More information about this can be found in the tips and
+tricks section.
+
 .. warning:: We have just started with the documentation and it's far from
    being perfect. If you find glitches, errors or just have feedback, please
    contact the team: :ref:`support`.

docs/tips_tricks.txt

@@ -31,3 +31,38 @@ Within a permission class, you can refer to Django's basic permissions::
                 # ...
 
     authority.register(Flatpage, FlagpagePermisson)
+
+If the ``Permission`` table changes during the lifespan of a django-authority
+permission instance and the smart cache is being used, you will need to call
+invalidate_permissions_cache in order to see that changes::
+
+    class UserPermission(permission.BasePermission):
+        label = 'user_permission'
+        checks = ('do_foo',)
+    authority.register(User, UserPermission)
+
+    user_permission = UserPermission(user)
+
+    # can_foo is False here since the permission has not yet been added.
+    can_foo = user_permission.has_user_perms('foo', user)
+
+    Permission.objects.create(
+        content_type=Permission.objects.get_content_type(User),
+        object_id=user.pk,
+        codename='foo',
+        user=user,
+        approved=True,
+    )
+
+    # can_foo is still False because the permission cache has not been
+    invalidated yet.
+    can_foo = user_permission.has_user_perms('foo', user)
+
+    user_permission.invalidate_permissions_cache()
+
+    # can_foo is now True
+    can_foo = user_permission.has_user_perms('foo', user)
+
+This is particularly useful if you are using the permission instances during a
+request, where it is unlikely that the state of the ``Permission`` table will
+change.