Added doc warning about imports when using pre_update signal and custom user model...

diff --git a/README.rst b/README.rst
index 291490d40379e8348b98b8eea1d2dca50f7c983b..58499065a516e47a1c2dae4b930c7583617f8848 100644 (file)
--- a/README.rst
+++ b/README.rst
@@ -49,7 +49,7 @@ credentials, some features are:
 ------------
 Dependencies
 ------------
-Dependencies that must be meet to use the app:
+Dependencies that *must* be meet to use the application:
 
 - OpenId_ support depends on python-openid_
 
@@ -114,7 +114,7 @@ Configuration
   because the backend string stored in session (like backends.TwitterBackend)
   won't match the new paths.
 
-- The app will try to import custom backends from the sources defined in::
+- The application will try to import custom backends from the sources defined in::
 
     SOCIAL_AUTH_IMPORT_BACKENDS = (
         'myproy.social_auth_extra_services',
@@ -123,7 +123,7 @@ Configuration
   This way it's easier to add new providers, check the already defined ones
   in social_auth.backends for examples.
 
-  Take into account that backends must be defined in AUTHENTICATION_BACKENDS_
+  Take into account that backends *must* be defined in AUTHENTICATION_BACKENDS_
   or Django won't pick them when trying to authenticate the user.
 
 - Setup Twitter, Facebook, Orkut and Google OAuth keys (see OAuth_ section
@@ -217,18 +217,20 @@ for example, to store user gender, location, etc. Example::
     from social_auth.signals import pre_update
     from social_auth.backends.facebook import FacebookBackend
 
-    def facebook_extra_values(sender, user, response, details):
+    def facebook_extra_values(sender, user, response, details, **kwargs):
         user.gender = response.get('gender')
         return True
 
     pre_update.connect(facebook_extra_values, sender=FacebookBackend)
 
 New data updating is made automatically but could be disabled and left only to
-signal handler if this setting value::
+signal handler if this setting value is set to True::
 
     SOCIAL_AUTH_CHANGE_SIGNAL_ONLY = False
 
-is set to True.
+Take into account that when defining a custom User model and declaring signal
+handler in models.py, the imports and handler definition *must* be made after
+the custom User model is defined or circular imports issues will be raised.
 
 
 ------
@@ -245,7 +247,7 @@ OAuth
 OAuth_ communication demands a set of keys exchange to validate the client
 authenticity prior to user approbation. Twitter, Facebook and Orkut
 facilitates these keys by application registration, Google works the same,
-but provides the option for unregisterd applications.
+but provides the option for unregistered applications.
 
 Check next sections for details.
 

diff --git a/example/app/models.py b/example/app/models.py
index 8c28f48f6f58114dfbd0343ad6a69480852ee7f7..583fa1418d24b0e454ffa157d8ff3f6c08d731d2 100644 (file)
--- a/example/app/models.py
+++ b/example/app/models.py
@@ -15,3 +15,12 @@ class CustomUser(models.Model):
 
     def is_authenticated(self):
         return True
+
+
+from social_auth.signals import pre_update
+from social_auth.backends.facebook import FacebookBackend
+
+def facebook_extra_values(sender, user, response, details, **kwargs):
+    return False
+
+pre_update.connect(facebook_extra_values, sender=FacebookBackend)

diff --git a/example/app/views.py b/example/app/views.py
index 50f3b3ea9fb71641a4d0b1cffde95a5b7181b182..849d8981f7394a436905c9172dec9957afd5b77f 100644 (file)
--- a/example/app/views.py
+++ b/example/app/views.py
@@ -4,26 +4,29 @@ from django.contrib.auth.decorators import login_required
 from django.template import RequestContext
 from django.shortcuts import render_to_response
 
+from social_auth import __version__ as version
+
 
 def home(request):
     """Home view, displays login mechanism"""
     if request.user.is_authenticated():
         return HttpResponseRedirect('done')
     else:
-        return render_to_response('home.html', None, RequestContext(request))
+        return render_to_response('home.html', {'version': version},
+                                  RequestContext(request))
 
 @login_required
 def done(request):
     """Login complete view, displays user data"""
     names = request.user.social_auth.values_list('provider', flat=True)
-    return render_to_response('done.html',
-                              dict((name.lower().replace('-', '_'), True)
-                                        for name in names),
-                              RequestContext(request))
+    ctx = dict((name.lower().replace('-', '_'), True) for name in names)
+    ctx['version'] = version
+    return render_to_response('done.html', ctx, RequestContext(request))
 
 def error(request):
     """Error view"""
-    return render_to_response('error.html', None, RequestContext(request))
+    return render_to_response('error.html', {'version': version},
+                              RequestContext(request))
 
 def logout(request):
     """Logs out user"""

diff --git a/example/templates/base.html b/example/templates/base.html
index b449d535dfb7aa136ffc51dde8ddcba5193ce564..6dc7003f8b768c66ebb226b6708abbe78cbf3724 100644 (file)
--- a/example/templates/base.html
+++ b/example/templates/base.html
@@ -31,7 +31,7 @@
     </style>
   </head>
   <body>
-    <h1>Django Social Auth</h1>
+    <h1>Django Social Auth (v{{ version }})</h1>
     <p class="description">
       Django Social Auth is an easy to setup social authentication/registration mechanism for Django projects.
       Check the documentation on <a href="https://github.com/omab/django-social-auth#readme" title="docs">Github</a>