added documentation for "passlib.ext.django" django app that upgrades Django to support pbkdf2

* docs & module currently hidden since it hasn't had much testing yet (and may split out into separate package anyway)

1 files changed, 51 insertions, 4 deletions

diff --git a/passlib/ext/django/utils.py b/passlib/ext/django/utils.py
index 9285f16..41d4196 100644
--- a/passlib/ext/django/utils.py
+++ b/passlib/ext/django/utils.py
@@ -10,7 +10,6 @@
 #imports
 #===================================================================
 #site
-from django.contrib.auth.models import User
 #pkg
 from passlib.utils import is_crypt_context, bytes
 #local
@@ -20,6 +19,45 @@ __all__ = [
 ]
 
 #===================================================================
+#lazy import
+#===================================================================
+#NOTE: doing this lazily so sphinx can crawl module without
+#      having django import problems.
+
+User = None #imported from django.contrib.auth.models 
+
+def _lazy_import():
+    global User    
+    if User is None:
+        from django.contrib.auth.models import User
+
+#===================================================================
+#constants
+#===================================================================
+
+#: default context used by app
+DEFAULT_CTX = """
+[passlib]
+schemes =
+    pbkdf2_sha256,
+    django_salted_sha1, django_salted_md5,
+    django_des_crypt, hex_md5,
+    django_disabled
+
+default = pbkdf2_sha256
+
+deprecated =
+    django_salted_sha1, django_salted_md5,
+    django_des_crypt, hex_md5
+
+all__vary_rounds = 5%%
+
+pbkdf2_sha256__default_rounds = 4000
+staff__pbkdf2_sha256__default_rounds = 8000
+superuser__pbkdf2_sha256__default_rounds = 10000
+"""
+
+#===================================================================
 #monkeypatch framework
 #===================================================================
 
@@ -31,7 +69,15 @@ __all__ = [
 _django_patch_state = None
 
 def get_category(user):
-    "default get_category() implementation used by set_django_password_context"
+    """default get_category() implementation used by set_django_password_context
+    
+    this is the function used if ``settings.PASSLIB_GET_CONTEXT`` is not
+    specified.
+    
+    it maps superusers to the ``"superuser"`` category,
+    staff to the ``"staff"`` category,
+    and all others to the default category.
+    """
     if user.is_superuser:
         return "superuser"
     if user.is_staff:
@@ -43,7 +89,7 @@ def um(func):
     return func.im_func
 
 def set_django_password_context(context=None, get_category=get_category):
-    """monkeypatches django.contrib.auth to use specified password context
+    """monkeypatches :mod:`!django.contrib.auth` to use specified password context.
 
     :arg context:
         Passlib context to use for Django password hashing.
@@ -64,8 +110,9 @@ def set_django_password_context(context=None, get_category=get_category):
         By default, uses a function which returns ``"superuser"``
         for superusers, and ``"staff"`` for staff.
     """
-    global _django_patch_state
+    global _django_patch_state, User
     state = _django_patch_state
+    _lazy_import()
 
     # issue warning if something else monkeypatched User
     # while our patch was applied.