Commits

Thomas Johansson committed 872108f

Improve store API documentation and clarify API semantics and expectations.

  • Participants
  • Parent commits c7aa341

Comments (0)

Files changed (1)

piston/authentication/oauth/store/__init__.py

 
 
 class InvalidConsumer(RuntimeError):
-    pass
+    """Invalid consumer."""
 
 
 class InvalidToken(RuntimeError):
-    pass
+    """Invalid token."""
 
 
 class InvalidRequestToken(InvalidToken):
-    pass
+    """Invalid request token."""
 
 
 class InvalidAccessToken(InvalidToken):
-    pass
+    """Invalid access token."""
 
 
 class Store(object):
+    """
+    The Store class is the backbone of piston's OAuth implementation. It is used
+    by the views and the authentication backend to get consumers and tokens, and
+    to create tokens. The following terms are used in the documentation of the
+    API:
+    
+    Consumer:
+        A class defining at minimum a `key` and a `secret` property. Both of
+        these properties must be either str or unicode.
+                
+    Token:
+        A class defining at minimum a `key` and a `secret` property. Both of
+        these properties must be either str or unicode.
+        
+    User:
+        A `django.contrib.auth.models.User` instance.
+             
+    Any API that takes a consumer or token will be passed a Consumer or Token
+    instance it itself returned at an earlier stage from one of the methods that
+    take a key and return a Consumer or Token. This means if your store
+    implementation uses tokens that keep a reference to its Consumer on the
+    Token itself, `get_consumer_from_request_token` can simply return
+    `request_token.consumer`.
+    """
     def get_consumer(self, request, oauth_request, consumer_key):
         """
-        Return an `oauth2.Consumer` (or compatible) instance for `consumer_key`
-        or raise `InvalidConsumer`.
+        Return the Consumer for `consumer_key` or raise `InvalidConsumer`.
         
         `request`: The Django request object.
         `oauth_request`: The `oauth2.Request` object.
     
     def get_consumer_from_request_token(self, request, oauth_request, request_token):
         """
-        Return the `oauth2.Consumer` (or compatible) instance associated with
-        the `request_token` request token, or raise `InvalidConsumer`.
+        Return the Consumer associated with the `request_token` Token, or raise
+        `InvalidConsumer`.
         
         `request`: The Django request object.
         `oauth_request`: The `oauth2.Request` object.
     
     def get_consumer_from_access_token(self, request, oauth_request, access_token):
         """
-        Return the `oauth2.Consumer` (or compatible) instance associated with
-        the `access_token` access token, or raise `InvalidConsumer`.
+        Return the Consumer associated with the `access_token` Token, or raise
+        `InvalidConsumer`.
         
         `request`: The Django request object.
         `oauth_request`: The `oauth2.Request` object.
-        `access_token`: The access token to get the consumer for.
+        `access_token`: The access Token to get the consumer for.
         """
         raise NotImplementedError
         
     def create_request_token(self, request, oauth_request, consumer, callback):
         """
-        Generate and return an `oauth2.Token` (or compatible) instance.
+        Generate and return a Token.
 
         `request`: The Django request object.
         `oauth_request`: The `oauth2.Request` object.
-        `consumer`: The consumer that made the request.
+        `consumer`: The Consumer that made the request.
         """
         raise NotImplementedError
 
     def get_request_token(self, request, oauth_request, request_token_key):
         """
-        Return an `oauth2.Token` (or compatible) instance for
-        `request_token_key` or raise `InvalidRequestToken`.
+        Return the Token for `request_token_key` or raise `InvalidRequestToken`.
         
         `request`: The Django request object.
         `oauth_request`: The `oauth2.Request` object.
-        `consumer`: The consumer that made the request.
+        `consumer`: The Consumer that made the request.
         `request_token_key`: The request token key.
         """
         raise NotImplementedError
 
     def authorize_request_token(self, request, oauth_request, request_token):
         """ 
-        Authorize the request token and return it, or raise
+        Authorize the `request_token` Token and return it, or raise
         `InvalidRequestToken`.
         
         `request`: The Django request object.
         `oauth_request`: The `oauth2.Request` object.
-        `request_token`: The request token.
+        `request_token`: The request token to authorize.
         """
         raise NotImplementedError
 
     def create_access_token(self, request, oauth_request, consumer, request_token):
         """
-        Generate and return a `oauth2.Token` (or compatible) instance.
+        Generate and return a Token.
         
         `request`: The Django request object.
         `oauth_request`: The `oauth2.Request` object.
-        `consumer`: The consumer that made the request.
-        `request_token`: The request token used to request the access token.
+        `consumer`: The Consumer that made the request.
+        `request_token`: The Token used to make the request.
         """
         raise NotImplementedError
 
     def get_access_token(self, request, oauth_request, consumer, access_token_key):
         """
-        Return the appropriate `oauth2.Token` (or compatible) instance for
-        `access_token_key` or raise `InvalidAccessToken`.
+        Return the Token for `access_token_key` or raise `InvalidAccessToken`.
         
         `request`: The Django request object.
         `oauth_request`: The `oauth2.Request` object.
-        `consumer`: The consumer that made the request.
-        `access_token_key`: The access token key used to make the request.
+        `consumer`: The Consumer that made the request.
+        `access_token_key`: The token key used to make the request.
+        """
+        raise NotImplementedError
+
+    def get_user_from_access_token(self, request, oauth_request, access_token):
+        """
+        Return the associated User for `access_token`.
+        
+        `request`: The Django request object.
+        `oauth_request`: The `oauth2.Request` object.
+        `consumer`: The Consumer that made the request.
+        `access_token`: The Token used to make the request.
         """
         raise NotImplementedError
 
     def check_nonce(self, request, oauth_request, nonce):
         """
-        Return `True` if the nonce has not yet been used.
+        Return `True` if the nonce has not yet been used, `False` otherwise.
         
         `request`: The Django request object.
         `oauth_request`: The `oauth2.Request` object.