Permalink
Browse files

Documentation work in progress

  • Loading branch information...
1 parent 1956590 commit 5ec50640fa3a6aada92f0c73150e4b94e587f9f8 @flashingpumpkin committed Oct 5, 2011
View
@@ -0,0 +1,7 @@
+API
+===
+
+.. toctree::
+ :glob:
+
+ api/*
@@ -0,0 +1,7 @@
+Clients
+=================
+
+.. toctree::
+ :glob:
+
+ clients/*
@@ -0,0 +1,7 @@
+Base
+====
+
+.. currentmodule:: socialregistration.clients
+
+.. automodule:: socialregistration.clients
+ :members:
@@ -0,0 +1,8 @@
+OAuth
+=====
+
+.. currentmodule:: socialregistration.clients.oauth
+
+.. autoclass:: OAuth
+ :members:
+ :inherited-members:
@@ -0,0 +1,8 @@
+OAuth 2
+=======
+
+.. currentmodule:: socialregistration.clients.oauth
+
+.. autoclass:: OAuth2
+ :members:
+ :inherited-members:
View
@@ -0,0 +1,9 @@
+Mixins
+======
+
+.. currentmodule:: socialregistration.mixins
+
+.. automodule:: socialregistration.mixins
+ :members:
+
+.. autoattribute::
View
@@ -0,0 +1,40 @@
+Signals
+=======
+
+Socialregistration comes with two signals that you can subscribe to:
+
+.. currentmodule:: socialregistration.signals
+
+.. attribute:: connect
+
+ The ``connect`` signal is fired every time a *new* social profile of sorts
+ is created. The signal handler should accept four arguments. An additional
+ fifth, the current request object, is passed in too:
+
+ ::
+
+ from socialregistration import signals
+ from socialregistration.contrib.facebook.models import FacebookProfile
+
+ def connect_handler(sender, user, profile, client, request = None):
+ data = client.graph.request('me')
+
+ signals.connect.connect(connect_handler, sender = FacebookProfile,
+ dispatch_uid = 'facebook.connect')
+
+
+.. attribute:: login
+
+ The ``login`` signal is fired every time a user signs into your Django
+ application via a third party API. The signal handler here should also
+ accept four arguments and take an optional fifth argument, being the current
+ request:
+
+ ::
+
+ def login_handler(sender, user, profile, client, request = None):
+ data = client.graph.request('me')
+
+ signals.login.connect(login_handler, sender = FacebookProfile,
+ dispatch_uid = 'facebook.connect')
+
View
@@ -0,0 +1,7 @@
+Tests
+=====
+
+.. currentmodule:: socialregistration.tests
+
+.. automodule:: socialregistration.tests
+ :members:
View
@@ -0,0 +1,7 @@
+Views
+=====
+
+.. currentmodule:: socialregistration.views
+
+.. automodule:: socialregistration.views
+ :members:
View
@@ -2,17 +2,12 @@
.. toctree::
- :maxdepth: 2
+ :maxdepth: 3
installation.rst
services.rst
+ api.rst
settings.rst
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
-
+Proudly sponsored by `Caffeinehit Ltd <http://www.caffeinehit.com/>`_. Hit us
+up if you need stuff done.
View
@@ -1,10 +1,8 @@
Services
--------
-.. include:: contrib/openid.rst
-.. include:: contrib/facebook.rst
-.. include:: contrib/twitter.rst
-.. include:: contrib/github.rst
-.. include:: contrib/linkedin.rst
-.. include:: contrib/foursquare.rst
-.. include:: contrib/tumblr.rst
+.. toctree::
+ :glob:
+
+ contrib/*
+
@@ -4,23 +4,14 @@
class Client(object):
"""
- Base class for OAuth/OpenID clients. Subclasses must implement at least:
-
- * `get_callback_url`
- The URL where the remote service should redirect the user back to
- * `get_redirect_url`
- The url where the user should be redirected to to request permissions
- * `request`
- Do signed requests against the API
- * `get_session_key`
- A unique identifier for storing the client in the user's session
-
+ Base class for OAuth/OpenID clients. Subclasses must implement all the
+ methods.
"""
def is_https(self):
"""
- Check if the site is using HTTPS. This is controlled with the
- `SOCIALREGISTRATION_USE_HTTPS` setting. Default value is `False`.
+ Check if the site is using HTTPS. This is controlled with
+ ``SOCIALREGISTRATION_USE_HTTPS`` setting.
"""
return USE_HTTPS
@@ -35,14 +26,21 @@ def get_callback_url(self):
"""
Returns the URL where the service should redirect the user back to
once permissions/access were granted - or not. This should take in
- account the `SOCIALREGISTRATION_USE_HTTPS` setting.
+ account the value returned by ``self.is_https()``.
"""
raise NotImplementedError
def request(self, url, method="GET", params=None, headers=None, **kwargs):
"""
- Make signed requests against `url`. Signing method depends on the
+ Make signed requests against ``url``. Signing method depends on the
protocol used.
+
+ :param url: The API endpoint to request
+ :param method: The HTTP method to be used
+ :param params: The parameters to be used for the request
+ :type params: dict
+ :param headers: Additional headers to be sent with the request
+ :type headers: dict
"""
raise NotImplementedError
@@ -60,29 +60,35 @@ def inactive_response(self):
def redirect(self, request):
"""
- Redirect the user back to the `next` session/request variable.
+ Redirect the user back to the ``next`` session/request variable.
"""
return HttpResponseRedirect(self.get_next(request))
class ClientMixin(object):
"""
- Views such as `OAuthRedirectView` require a client to work with. This is
+ Views such as ``OAuthRedirectView`` require a client to work with. This is
the interface to it.
+
"""
- # The client class we'll be working with
+ #: The client class we'll be working with
client = None
def get_client(self):
+ """
+ Return the client class or raise an ``AttributeError`` if
+ ``self.client`` is not set.
+ """
if self.client is None:
raise AttributeError('`self.client` is `None`')
return self.client
class ProfileMixin(object):
"""
- Views such as `SetupCallback` require a profile model to work with. This is
+ Views such as ``SetupCallback`` require a profile model to work with. This is
the interface to it.
+
"""
- # The profile model that we'll be working with
+ #: The profile model that we'll be working with
profile = None
def get_lookup_kwargs(self, request, client):
@@ -92,14 +98,29 @@ def get_lookup_kwargs(self, request, client):
raise NotImplementedError
def get_model(self):
+ """
+ Return the profile model or raise an ``AttributeError``
+ if ``self.profile`` is not set.
+ """
if self.profile is None:
raise AttributeError('`self.profile` is `None`')
return self.profile
def create_user(self):
+ """
+ Create and return an empty user model.
+ """
return User()
def create_profile(self, user, save=False, **kwargs):
+ """
+ Create a profile model.
+
+ :param user: A user object
+ :param save: If this is set, the profile will
+ be saved to DB straight away
+ :type save: bool
+ """
profile = self.get_model()(user=user, **kwargs)
if save:
@@ -108,9 +129,19 @@ def create_profile(self, user, save=False, **kwargs):
return profile
def get_profile(self, **kwargs):
+ """
+ Return a profile object
+ """
return self.get_model().objects.get(**kwargs)
def get_or_create_profile(self, user, save=False, **kwargs):
+ """
+ Return a profile from DB or if there is none, create a new one.
+
+ :param user: A user object
+ :param save: If set, a new profile will be saved.
+ :type save: bool
+ """
try:
profile = self.get_model().objects.get(user=user, **kwargs)
return profile, False
@@ -126,21 +157,36 @@ class SessionMixin(object):
"""
def store_profile(self, request, profile):
+ """
+ Store the profile data to the session
+ """
request.session['%sprofile' % SESSION_KEY] = profile
def store_user(self, request, user):
+ """
+ Store the user data to the session
+ """
request.session['%suser' % SESSION_KEY] = user
def store_client(self, request, client):
+ """
+ Store the client to the session
+ """
request.session['%sclient' % SESSION_KEY] = client
def get_session_data(self, request):
+ """
+ Return a tuple ``(user, profile, client)`` from the session.
+ """
user = request.session['%suser' % SESSION_KEY]
profile = request.session['%sprofile' % SESSION_KEY]
client = request.session['%sclient' % SESSION_KEY]
return user, profile, client
def delete_session_data(self, request):
+ """
+ Clear all session data.
+ """
del request.session['%suser' % SESSION_KEY]
del request.session['%sprofile' % SESSION_KEY]
del request.session['%sclient' % SESSION_KEY]
Oops, something went wrong.

0 comments on commit 5ec5064

Please sign in to comment.