Setting up docs

Author: wndhydrnt

docs/index.rst

@@ -5,7 +5,7 @@
 Contents:
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 3
 
    grant.rst
    store.rst

docs/oauth2.rst

@@ -1,7 +1,7 @@
 ``oauth2`` --- Controller classes
 ========================================
 
-.. autoclass:: oauth2.AuthorizationController
+.. autoclass:: oauth2.Provider
 
-.. automethod:: oauth2.AuthorizationController.add_grant
-.. automethod:: oauth2.AuthorizationController.dispatch
+.. automethod:: oauth2.Provider.add_grant
+.. automethod:: oauth2.Provider.dispatch

docs/store.rst

@@ -6,11 +6,11 @@
 Data types
 ----------
 
-.. autoclass:: oauth2.AccessToken
+.. autoclass:: oauth2.datatype.AccessToken
 
-.. autoclass:: oauth2.AuthorizationCode
+.. autoclass:: oauth2.datatype.AuthorizationCode
 
-.. autoclass:: oauth2.Client
+.. autoclass:: oauth2.datatype.Client
 
 Base classes
 ------------
@@ -24,17 +24,12 @@ Base classes
 .. autoclass:: ClientStore
    :members:
 
-Concrete classes
-----------------
+Implementations
+---------------
 
-.. autoclass:: LocalClientStore
-   :show-inheritance:
-   :members:
-
-.. autoclass:: LocalTokenStore
-   :show-inheritance:
-   :members:
+.. toctree::
+   :maxdepth: 2
 
-.. autoclass:: MemcacheTokenStore
-   :show-inheritance:
-   :members:
+   store/memcache.rst
+   store/memory.rst
+   store/mongodb.rst

docs/store/memcache.rst

@@ -0,0 +1,6 @@
+``oauth2.store.memcache`` --- Memcache store adapters
+=====================================================
+
+.. automodule:: oauth2.store.memcache
+
+.. autoclass:: MemcacheTokenStore

docs/store/memory.rst

@@ -0,0 +1,10 @@
+``oauth2.store.memory`` --- In-memory store adapters
+=====================================================
+
+.. automodule:: oauth2.store.memory
+
+.. autoclass:: MemoryClientStore
+   :members:
+
+.. autoclass:: MemoryTokenStore
+   :members:

docs/store/mongodb.rst

@@ -0,0 +1,12 @@
+``oauth2.store.mongodb`` --- Mongodb store adapters
+=====================================================
+
+.. automodule:: oauth2.store.mongodb
+
+.. autoclass:: MongodbStore
+
+.. autoclass:: MongodbAccessTokenStore
+
+.. autoclass:: MongodbAuthCodeStore
+
+.. autoclass:: MongodbClientStore

oauth2/store/__init__.py

@@ -16,7 +16,7 @@ def save_token(self, access_token):
         """
         Stores an access token and additional data.
         
-        :param access_token: An instance of :class:`oauth2.AccessToken`.
+        :param access_token: An instance of :class:`oauth2.datatype.AccessToken`.
         
         """
         raise NotImplementedError
@@ -40,7 +40,7 @@ def fetch_by_code(self, code):
         Returns an AuthorizationCode fetched from a storage.
         
         :param code: The authorization code.
-        :return: An instance of :class:`oauth2.AuthorizationCode`.
+        :return: An instance of :class:`oauth2.datatype.AuthorizationCode`.
         :raises: :class:`AuthCodeNotFound` if no data could be retrieved for
                  given code.
         

oauth2/store/memory.py

@@ -1,3 +1,10 @@
+"""
+Read or write data from or to local memory.
+
+Though not very valuable in a production setup, these store adapters are great
+for testing purposes.
+"""
+
 from oauth2.store import AccessTokenStore, AuthCodeStore, ClientStore
 from oauth2.error import AccessTokenNotFound, AuthCodeNotFound,\
                          ClientNotFoundError
@@ -57,7 +64,7 @@ def fetch_by_code(self, code):
         Returns an AuthorizationCode.
         
         :param code: The authorization code.
-        :return: An instance of :class:`oauth2.AuthorizationCode`.
+        :return: An instance of :class:`oauth2.datatype.AuthorizationCode`.
         :raises: :class:`AuthCodeNotFound` if no data could be retrieved for
                  given code.
         
@@ -72,7 +79,7 @@ def save_code(self, authorization_code):
         Stores the data belonging to an authorization code token.
         
         :param authorization_code: An instance of
-                                   :class:`oauth2.AuthorizationCode`.
+                                   :class:`oauth2.datatype.AuthorizationCode`.
         
         """
         self.auth_codes[authorization_code.code] = authorization_code
@@ -83,7 +90,7 @@ def save_token(self, access_token):
         """
         Stores an access token and additional data in memory.
         
-        :param client_id: An instance of :class:`oauth2.AccessToken`.
+        :param access_token: An instance of :class:`oauth2.datatype.AccessToken`.
         """
         self.access_tokens[access_token.token] = access_token
 
@@ -98,7 +105,7 @@ def fetch_by_refresh_token(self, refresh_token):
         
         :param refresh_token: The refresh token that was assigned to an
                               ``AccessToken``.
-        :return: The :class:`oauth2.AccessToken`.
+        :return: The :class:`oauth2.datatype.AccessToken`.
         :raises: :class:`oauth2.error.AccessTokenNotFound`
         """
         if refresh_token not in self.refresh_tokens:
@@ -115,7 +122,7 @@ def fetch_by_token(self, token):
         read again.
 
         :param token: A access token code.
-        :return: An instance of :class:`oauth2.AccessToken`.
+        :return: An instance of :class:`oauth2.datatype.AccessToken`.
         """
         if token not in self.access_tokens:
             raise AccessTokenNotFound

oauth2/store/mongodb.py

@@ -1,17 +1,37 @@
+"""
+Store adapters to read/write data to from/to mongodb using pymongo.
+"""
+
 from oauth2.store import AccessTokenStore, AuthCodeStore, ClientStore
 from oauth2.datatype import AccessToken, AuthorizationCode, Client
 from oauth2.error import AccessTokenNotFound, AuthCodeNotFound,\
     ClientNotFoundError
 
 class MongodbStore(object):
-    def __init__(self, collection, db):
+    """
+    Base class extended by all concrete store adapters.
+    """
+    
+    def __init__(self, collection):
         self.collection = collection
-        self.db = db
 
 class MongodbAccessTokenStore(AccessTokenStore, MongodbStore):
+    """
+    Create a new instance like this::
+    
+        from pymongo import MongoClient
+        
+        client = MongoClient('localhost', 27017)
+        
+        db = client.test_database
+        
+        access_token_store = MongodbAccessTokenStore(collection=db["access_tokens"])
+    
+    """
+    
     def fetch_by_refresh_token(self, refresh_token):
-        data = self.db[self.collection].\
-            find_one({"refresh_token": refresh_token})
+        
+        data = self.collection.find_one({"refresh_token": refresh_token})
 
         if data is None:
             raise AccessTokenNotFound
@@ -24,7 +44,7 @@ def fetch_by_refresh_token(self, refresh_token):
                            scopes=data["scopes"])
 
     def save_token(self, access_token):
-        self.db[self.collection].insert({
+        self.collection.insert({
             "client_id": access_token.client_id,
             "grant_type": access_token.grant_type,
             "token": access_token.token,
@@ -36,8 +56,21 @@ def save_token(self, access_token):
         return True
 
 class MongodbAuthCodeStore(AuthCodeStore, MongodbStore):
+    """
+    Create a new instance like this::
+    
+        from pymongo import MongoClient
+        
+        client = MongoClient('localhost', 27017)
+        
+        db = client.test_database
+        
+        access_token_store = MongodbAuthCodeStore(collection=db["auth_codes"])
+    
+    """
+    
     def fetch_by_code(self, code):
-        code_data = self.db[self.collection].find_one({"code": code})
+        code_data = self.collection.find_one({"code": code})
 
         if code_data is None:
             raise AuthCodeNotFound
@@ -50,7 +83,7 @@ def fetch_by_code(self, code):
                                  data=code_data["data"])
 
     def save_code(self, authorization_code):
-        self.db[self.collection].insert({
+        self.collection.insert({
             "client_id": authorization_code.client_id,
             "code": authorization_code.code,
             "expires_at": authorization_code.expires_at,
@@ -61,8 +94,21 @@ def save_code(self, authorization_code):
         return True
 
 class MongodbClientStore(ClientStore, MongodbStore):
+    """
+    Create a new instance like this::
+    
+        from pymongo import MongoClient
+        
+        client = MongoClient('localhost', 27017)
+        
+        db = client.test_database
+        
+        access_token_store = MongodbClientStore(collection=db["clients"])
+    
+    """
+    
     def fetch_by_client_id(self, client_id):
-        client_data = self.db[self.collection].find_one(
+        client_data = self.collection.find_one(
             {"identifier": client_id})
 
         if client_data is None:

oauth2/test/store/test_mongodb.py

@@ -5,7 +5,6 @@
 from oauth2.datatype import AccessToken, AuthorizationCode, Client
 from oauth2.error import AccessTokenNotFound, AuthCodeNotFound,\
     ClientNotFoundError
-from oauth2.store import ClientStore
 
 class MongodbAccessTokenStoreTestCase(unittest.TestCase):
     def setUp(self):
@@ -25,10 +24,7 @@ def test_fetch_by_refresh_token(self):
         collection_mock = Mock(spec=["find_one"])
         collection_mock.find_one.return_value = self.access_token_data
 
-        db_mock = {"access_tokens": collection_mock}
-        
-        store = MongodbAccessTokenStore(collection="access_tokens",
-                                        db=db_mock)
+        store = MongodbAccessTokenStore(collection=collection_mock)
         token = store.fetch_by_refresh_token(refresh_token=refresh_token)
 
         collection_mock.find_one.assert_called_with(
@@ -40,10 +36,7 @@ def test_fetch_by_refresh_token_no_data(self):
         collection_mock = Mock(spec=["find_one"])
         collection_mock.find_one.return_value = None
 
-        db_mock = {"access_tokens": collection_mock}
-        
-        store = MongodbAccessTokenStore(collection="access_tokens",
-                                        db=db_mock)
+        store = MongodbAccessTokenStore(collection=collection_mock)
 
         with self.assertRaises(AccessTokenNotFound):
             store.fetch_by_refresh_token(refresh_token="abcd")
@@ -53,10 +46,7 @@ def test_save_token(self):
 
         collection_mock = Mock(spec=["insert"])
 
-        db_mock = {"access_tokens": collection_mock}
-        
-        store = MongodbAccessTokenStore(collection="access_tokens",
-                                        db=db_mock)
+        store = MongodbAccessTokenStore(collection=collection_mock)
         store.save_token(access_token)
 
         collection_mock.insert.assert_called_with(self.access_token_data)
@@ -69,19 +59,14 @@ def setUp(self):
 
         self.collection_mock = Mock(spec=["find_one", "insert", "remove"])
 
-        self.collection_name = "auth_codes"
-        
-        self.db_mock = {self.collection_name: self.collection_mock}
-    
     def test_fetch_by_code(self):
         code = "abcd"
 
         self.collection_mock.find_one.return_value = self.auth_code_data
 
         self.auth_code_data["code"] = "abcd"
 
-        store = MongodbAuthCodeStore(collection=self.collection_name,
-                                     db=self.db_mock)
+        store = MongodbAuthCodeStore(collection=self.collection_mock)
         auth_code = store.fetch_by_code(code=code)
 
         self.collection_mock.find_one.assert_called_with({"code": "abcd"})
@@ -91,8 +76,7 @@ def test_fetch_by_code(self):
     def test_fetch_by_code_no_data(self):
         self.collection_mock.find_one.return_value = None
 
-        store = MongodbAuthCodeStore(collection=self.collection_name,
-                                     db=self.db_mock)
+        store = MongodbAuthCodeStore(collection=self.collection_mock)
 
         with self.assertRaises(AuthCodeNotFound):
             store.fetch_by_code(code="abcd")
@@ -102,8 +86,7 @@ def test_save_code(self):
 
         auth_code = AuthorizationCode(**self.auth_code_data)
 
-        store = MongodbAuthCodeStore(collection=self.collection_name,
-                                     db=self.db_mock)
+        store = MongodbAuthCodeStore(collection=self.collection_mock)
         store.save_code(auth_code)
 
         self.collection_mock.insert.assert_called_with(self.auth_code_data)
@@ -116,9 +99,7 @@ def test_fetch_by_client_id(self):
         collection_mock = Mock(spec=["find_one"])
         collection_mock.find_one.return_value = client_data
 
-        db_mock = {"clients": collection_mock}
-        
-        store = MongodbClientStore(collection="clients", db=db_mock)
+        store = MongodbClientStore(collection=collection_mock)
         client = store.fetch_by_client_id(client_id=client_data["identifier"])
 
         collection_mock.find_one.assert_called_with({
@@ -130,9 +111,7 @@ def test_fetch_by_client_id_no_data(self):
         collection_mock = Mock(spec=["find_one"])
         collection_mock.find_one.return_value = None
 
-        db_mock = {"clients": collection_mock}
-        
-        store = MongodbClientStore(collection="clients", db=db_mock)
+        store = MongodbClientStore(collection=collection_mock)
 
         with self.assertRaises(ClientNotFoundError):
             store.fetch_by_client_id(client_id="testclient")