Updated docs and examples

Author: wndhydrnt

CHANGELOG.md

@@ -1,8 +1,10 @@
-## 0.5.0 (unreleased)
+## 0.5.0
 
 Features:
 
   - Added Client Credentials Grant
+  - Renamed `oauth2.AuthorizationController` to `oauth2.Provider`
+  - Added mongodb store
 
 ## 0.4.0
 

README.rst

@@ -1,5 +1,5 @@
 python-oauth2
-###############
+#############
 
 python-oauth2 is a framework that aims at making it easy to provide authentication
 via `OAuth 2.0 <http://tools.ietf.org/html/rfc6749>`_ within an application stack. 
@@ -12,11 +12,7 @@ Status
 .. image:: https://travis-ci.org/wndhydrnt/python-oauth2.png?branch=master
    :target: https://travis-ci.org/wndhydrnt/python-oauth2
 
-python-oauth2 is currently not ready for use in production environments.
-While the basic implementations work already pretty well, some types of
-authorization Grants
-`defined in the RFC <http://tools.ietf.org/html/rfc6749#section-1.3>`_ are
-still missing.
+python-oauth2 has reached its beta phase. All main parts of the `OAuth 2.0 RFC <http://tools.ietf.org/html/rfc6749>`_ such as the various types of Grants, Refresh Token and Scopes have been implemented. However, bugs might occur or implementation details might be wrong.
 
 Installation
 ************
@@ -30,12 +26,11 @@ Usage
 *****
 
 Example Authorization server::
-    
     from wsgiref.simple_server import make_server
     import oauth2
     import oauth2.grant
     import oauth2.error
-    import oauth2.store
+    import oauth2.store.memory
     import oauth2.tokengenerator
     import oauth2.web
 
@@ -61,17 +56,17 @@ Example Authorization server::
             return response
 
     # Create an in-memory storage to store your client apps.
-    client_store = oauth2.store.LocalClientStore()
+    client_store = oauth2.store.memory.ClientStore()
     # Add a client
     client_store.add_client(client_id="abc", client_secret="xyz",
                             redirect_uris=["http://localhost/callback"])
 
     # Create an in-memory storage to store issued tokens.
     # LocalTokenStore can store access and auth tokens
-    token_store = oauth2.store.LocalTokenStore()
+    token_store = oauth2.store.memory.TokenStore()
 
     # Create the controller.
-    auth_controller = oauth2.AuthorizationController(
+    auth_controller = oauth2.Provider(
         access_token_store=token_store,
         auth_code_store=token_store,
         client_store=client_store,
@@ -82,7 +77,7 @@ Example Authorization server::
     # Add Grants you want to support
     auth_controller.add_grant(oauth2.grant.AuthorizationCodeGrant())
     auth_controller.add_grant(oauth2.grant.ImplicitGrant())
-    
+
     # Add refresh token capability and set expiration time of access tokens
     # to 30 days
     auth_controller.add_grant(oauth2.grant.RefreshToken(expires_in=2592000))

docs/oauth2.rst

@@ -1,5 +1,5 @@
-``oauth2`` --- Controller classes
-========================================
+``oauth2`` --- Provider class
+=============================
 
 .. autoclass:: oauth2.Provider
 

docs/store/memcache.rst

@@ -3,4 +3,4 @@
 
 .. automodule:: oauth2.store.memcache
 
-.. autoclass:: MemcacheTokenStore
+.. autoclass:: TokenStore

docs/store/memory.rst

@@ -3,8 +3,8 @@
 
 .. automodule:: oauth2.store.memory
 
-.. autoclass:: MemoryClientStore
+.. autoclass:: ClientStore
    :members:
 
-.. autoclass:: MemoryTokenStore
+.. autoclass:: TokenStore
    :members:

docs/store/mongodb.rst

@@ -5,8 +5,8 @@
 
 .. autoclass:: MongodbStore
 
-.. autoclass:: MongodbAccessTokenStore
+.. autoclass:: AccessTokenStore
 
-.. autoclass:: MongodbAuthCodeStore
+.. autoclass:: AuthCodeStore
 
-.. autoclass:: MongodbClientStore
+.. autoclass:: ClientStore

examples/authorization_code_grant.py

@@ -10,8 +10,9 @@
 
 sys.path.insert(0, os.path.abspath(os.path.realpath(__file__) + '/../../'))
 
-from oauth2 import AuthorizationController
-from oauth2.store import LocalClientStore, LocalTokenStore
+from oauth2 import Provider
+from oauth2.error import UserNotAuthenticated
+from oauth2.store.memory import ClientStore, TokenStore
 from oauth2.tokengenerator import Uuid4
 from oauth2.web import SiteAdapter, Wsgi
 from oauth2.grant import AuthorizationCodeGrant
@@ -64,11 +65,11 @@ def render_auth_page(self, request, response, environ, scopes):
 
         return response
 
-    def authenticate(self, request, environ):
+    def authenticate(self, request, environ, scopes):
         if request.method == "POST":
             if request.post_param("confirm") is "1":
-                return True
-        return None
+                return
+        raise UserNotAuthenticated
 
     def user_has_denied_access(self, request):
         if request.method == "POST":
@@ -174,15 +175,15 @@ def run_app_server():
 
 def run_auth_server():
     try:
-        client_store = LocalClientStore()
+        client_store = ClientStore()
         client_store.add_client(client_id="abc", client_secret="xyz",
                                 redirect_uris=["http://localhost:8081/callback"])
 
-        token_store = LocalTokenStore()
+        token_store = TokenStore()
 
-        auth_controller = AuthorizationController(
+        auth_controller = Provider(
             access_token_store=token_store,
-            auth_token_store=token_store,
+            auth_code_store=token_store,
             client_store=client_store,
             site_adapter=TestSiteAdapter(),
             token_generator=Uuid4())

examples/implicit_grant.py

@@ -7,11 +7,12 @@
 
 sys.path.insert(0, os.path.abspath(os.path.realpath(__file__) + '/../../'))
 
-from oauth2 import AuthorizationController
+from oauth2 import Provider
+from oauth2.error import UserNotAuthenticated
 from oauth2.web import Wsgi, SiteAdapter
 from oauth2.tokengenerator import Uuid4
 from oauth2.grant import ImplicitGrant
-from oauth2.store import LocalClientStore, LocalTokenStore
+from oauth2.store.memory import ClientStore, TokenStore
 
 class TestSiteAdapter(SiteAdapter):
     CONFIRMATION_TEMPLATE = """
@@ -39,11 +40,11 @@ def render_auth_page(self, request, response, environ, scopes):
 
         return response
 
-    def authenticate(self, request, environ):
+    def authenticate(self, request, environ, scopes):
         if request.method == "POST":
             if request.post_param("confirm") is "1":
-                return True
-        return False
+                return
+        raise UserNotAuthenticated
 
     def user_has_denied_access(self, request):
         if request.method == "POST":
@@ -110,15 +111,15 @@ def application(env, start_response):
 
 def run_auth_server():
     try:
-        client_store = LocalClientStore()
+        client_store = ClientStore()
         client_store.add_client(client_id="abc", client_secret="xyz",
                                 redirect_uris=["http://localhost:8081/"])
 
-        token_store = LocalTokenStore()
+        token_store = TokenStore()
 
-        auth_server = AuthorizationController(
+        auth_server = Provider(
             access_token_store=token_store,
-            auth_token_store=token_store,
+            auth_code_store=token_store,
             client_store=client_store,
             site_adapter=TestSiteAdapter(),
             token_generator=Uuid4())

oauth2/__init__.py

@@ -10,25 +10,25 @@
 Usage
 =====
 
-Example Authorization server::
+Example::
     
     from wsgiref.simple_server import make_server
     import oauth2
     import oauth2.grant
     import oauth2.error
-    import oauth2.store
+    import oauth2.store.memory
     import oauth2.tokengenerator
     import oauth2.web
-
+    
     # Create a SiteAdapter to interact with the user.
     # This can be used to display confirmation dialogs and the like.
     class ExampleSiteAdapter(oauth2.web.SiteAdapter):
         def authenticate(self, request, environ, scopes):
             if request.post_param("confirm") == "1":
                 return {}
-
+    
             raise oauth2.error.UserNotAuthenticated
-
+    
         def render_auth_page(self, request, response, environ, scopes):
             response.body = '''
     <html>
@@ -40,17 +40,17 @@ def render_auth_page(self, request, response, environ, scopes):
         </body>
     </html>'''
             return response
-
+    
     # Create an in-memory storage to store your client apps.
-    client_store = oauth2.store.LocalClientStore()
+    client_store = oauth2.store.memory.ClientStore()
     # Add a client
     client_store.add_client(client_id="abc", client_secret="xyz",
                             redirect_uris=["http://localhost/callback"])
-
+    
     # Create an in-memory storage to store issued tokens.
     # LocalTokenStore can store access and auth tokens
-    token_store = oauth2.store.LocalTokenStore()
-
+    token_store = oauth2.store.memory.TokenStore()
+    
     # Create the controller.
     auth_controller = oauth2.Provider(
         access_token_store=token_store,
@@ -59,18 +59,18 @@ def render_auth_page(self, request, response, environ, scopes):
         site_adapter=ExampleSiteAdapter(),
         token_generator=oauth2.tokengenerator.Uuid4()
     )
-
+    
     # Add Grants you want to support
     auth_controller.add_grant(oauth2.grant.AuthorizationCodeGrant())
     auth_controller.add_grant(oauth2.grant.ImplicitGrant())
     
     # Add refresh token capability and set expiration time of access tokens
     # to 30 days
     auth_controller.add_grant(oauth2.grant.RefreshToken(expires_in=2592000))
-
+    
     # Wrap the controller with the Wsgi adapter
     app = oauth2.web.Wsgi(server=auth_controller)
-
+    
     if __name__ == "__main__":
         httpd = make_server('', 8080, app)
         httpd.serve_forever()
@@ -102,7 +102,7 @@ class Provider(object):
     def __init__(self, access_token_store, auth_code_store, client_store,
                  site_adapter, token_generator, response_class=Response):
         """
-        Endpoint of requests to the OAuth 2.0 server.
+        Endpoint of requests to the OAuth 2.0 provider.
         
         :param access_token_store: An object that implements methods defiend by
                                    :class:`oauth2.store.AccessTokenStore`.
@@ -129,7 +129,7 @@ def __init__(self, access_token_store, auth_code_store, client_store,
 
     def add_grant(self, grant):
         """
-        Adds a Grant that the server should support.
+        Adds a Grant that the provider should support.
         """
         if hasattr(grant, "expires_in"):
             self.token_generator.expires_in = grant.expires_in
@@ -167,6 +167,7 @@ def dispatch(self, request, environ):
             response.body = json.dumps(json_body)
             return response
 
+    @property
     def scope_separator(self, separator):
         """
         Sets the separator of values in scope query parameter.

oauth2/store/memcache.py

@@ -4,7 +4,7 @@
 from oauth2.error import AccessTokenNotFound, AuthCodeNotFound
 from oauth2.store import AccessTokenStore, AuthCodeStore
 
-class MemcacheTokenStore(AccessTokenStore, AuthCodeStore):
+class TokenStore(AccessTokenStore, AuthCodeStore):
     """
     Uses memcache to store access tokens and auth tokens.
     
@@ -19,11 +19,11 @@ class MemcacheTokenStore(AccessTokenStore, AuthCodeStore):
         # Somewhere in your application
         mc = memcache.Client(servers=['127.0.0.1:11211'], debug=0)
         # ...
-        token_store = MemcacheTokenStore(mc=mc)
+        token_store = TokenStore(mc=mc)
         
     Initialization using ``python-memcached``::
         
-        token_store = MemcacheTokenStore(servers=['127.0.0.1:11211'], debug=0)
+        token_store = TokenStore(servers=['127.0.0.1:11211'], debug=0)
 
     """
     def __init__(self, mc=None, prefix="oauth2", *args, **kwargs):