Commits

Tim Savage  committed f3ddb2b

Updated decorators to follow Django 1.4 style. Added initial work on documentation.

- Documentation covers django_extras.contrib.auth.decorators.

  • Participants
  • Parent commits 454683b

Comments (0)

Files changed (7)

 *.py[co]
 *.egg-info
 build*
+docs/*.html
 
 # IDE cruft
 .idea/*
 *.py[co]
 *.egg-info
 build*
+docs/*.html
 
 # IDE cruft
 .idea/*

File .idea/dictionaries/tims.xml

+<component name="ProjectDictionaryState">
+  <dictionary name="tims" />
+</component>

File .idea/django-extras.iml

     <orderEntry type="jdk" jdkName="Python 2.7.1 virtualenv at ~/Projects/ve" jdkType="Python SDK" />
     <orderEntry type="sourceFolder" forTests="false" />
   </component>
+  <component name="TemplatesService">
+    <option name="templateLanguage" value="Django" />
+    <option name="TEMPLATE_CONFIGURATION" value="Django" />
+  </component>
 </module>
 

File django_extras/contrib/auth/decorators.py

 from django.contrib.auth.decorators import *
+from django.core.exceptions import PermissionDenied
 
 
-def superuser_required(function=None, redirect_field_name=REDIRECT_FIELD_NAME, login_url=None):
+def superuser_required(login_url=None, raise_exception=False):
     """
     Decorator for views that checks that the user is a superuser, redirecting to
     the log-in page if necessary.
     """
-    actual_decorator = user_passes_test(
-        lambda u: u.is_superuser,
-        login_url=login_url,
-        redirect_field_name=redirect_field_name
-    )
-    if function:
-        return actual_decorator(function)
-    return actual_decorator
+    def check_permission(user):
+        if user.is_superuser:
+            return True
+        if raise_exception:
+            raise PermissionDenied
+        return False
+    return user_passes_test(check_permission, login_url=login_url)
 
-def staff_required(function=None, redirect_field_name=REDIRECT_FIELD_NAME, login_url=None):
+def staff_required(include_superusers=True, login_url=None, raise_exception=False):
     """
     Decorator for views that checks that the user is a staff member, redirecting
     to the log-in page if necessary.
     """
-    actual_decorator = user_passes_test(
-        lambda u: u.is_staff,
-        login_url=login_url,
-        redirect_field_name=redirect_field_name
-    )
-    if function:
-        return actual_decorator(function)
-    return actual_decorator
+    def check_permission(user):
+        if user.is_staff or (include_superusers and user.is_superuser):
+            return True
+        if raise_exception:
+            raise PermissionDenied
+        return False
+    return user_passes_test(check_permission, login_url=login_url)

File docs/index.txt

+.. _index:
+
+===========================
+Django Extras documentation
+===========================
+
+Getting help
+============
+
+* Report bugs with Django Extras with the `issue tracker`_.
+
+.. _issue tracker: https://bitbucket.org/timsavage/django-extras/issues
+
+What's in Django Extras
+=======================
+
+Django Extras is a project that provides extensions for Django_ to solve common
+development situations not (or not yet) covered by the core Django framework.
+
+Examples of this include:
+
+* additional decorators
+* model mixins to easily assign owners to a model
+* additional model and form fields
+* greatly expanded collection of default response classes
+
+First steps
+===========
+
+If you are new to Django it is recommended you visit the `Django documentation`_
+as they have excellent documentation to get you up and running.
+
+.. _Django: https://www.djangoproject.com/
+.. _Django documentation: https://docs.djangoproject.com/
+
+Other batteries included
+========================
+
+* :doc:`Authentication <topics/auth>`

File docs/topics/auth.txt

+==============================
+User authentication extensions
+==============================
+
+.. module:: django_extras.contrib.auth
+   :synopsis: Extensions to django.contrib.auth
+
+While Django comes with a built in user authentication system it leaves a
+couple of common use-cases incomplete. Django Extras fills in the missing
+pieces.
+
+
+Installation
+============
+
+No installation is required, this extension does not require additional
+database models.
+
+Convenience decorators
+======================
+
+.. currentmodule:: django_extras.contib.auth.decorators
+
+The staff_required decorator
+----------------------------
+
+.. function:: staff_required([include_superusers=True, login_url=None, raise_exception=False])
+
+    This decorator provides a simple way to restrict access to a particular
+    view to only users who have the *is_staff* set. Rather than using the
+    `~django.contrib.auth.decorators.user_passes_test()` decorator
+    restricting a view to staff only can be written as::
+
+        from django_extras.contrib.auth.decorators import staff_required
+        @staff_required
+        def my_view(request):
+            ...
+
+    By default this decorator also includes users with the *is_superuser* flag
+    set, these users can be excluded with the optional ``include_superuser``
+    parameter. Example::
+
+        from django_extras.contrib.auth.decorators import staff_required
+        @staff_required(include_superusers=False)
+        def my_view(request):
+            ...
+
+    As in the :func:`~decorators.login_required`, ``login_url`` defaults to
+    :setting:`settings.LOGIN_URL <LOGIN_URL>`.
+
+    Following from the change in Django 1.4 this decorator also includes the
+    ``raise_exception`` parameter, If given, the decorator will raise
+    :exe:`~django.core.exceptions.PermissionDenied`.
+
+The superuser_required decorator
+--------------------------------
+
+.. function:: superuser_required([login_url=None, raise_exception=False])
+
+    This decorator provides a simple way to restrict access to a particular
+    view to only users who have the *is_superuser* set. Rather than using
+    the `~django.contrib.auth.decorators.user_passes_test()` decorator
+    restricting a view to staff only can be written as::
+
+        from django_extras.contrib.auth.decorators import staff_required
+        @staff_required
+        def my_view(request):
+            ...
+
+    As in the :func:`~decorators.login_required`, ``login_url`` defaults to
+    :setting:`settings.LOGIN_URL <LOGIN_URL>`.
+
+    Following from the change in Django 1.4 this decorator also includes the
+    ``raise_exception`` parameter, If given, the decorator will raise
+    :exe:`~django.core.exceptions.PermissionDenied`.
+