Remove framework specific decorators. Fix #167.

docs/server2.rst

@@ -2,35 +2,23 @@
 OAuth 2: Creating a Provider
 ============================
 
-Note that OAuth 2 provider is still very much a work in progress, consider it a
-preview of a near future =)
+OAuthLib is a dependency free library that may be used with any web
+framework. That said, there are framework specific helper libraries
+to make your life easier.
 
-**1. Which framework are you using?**
+- For Django there is `django-oauth-toolkit`_.
+- For Flask there is `flask-oauthlib`_.
 
-    OAuthLib is a dependency free library that may be used with any web
-    framework. That said, there are framework specific helper decorator classes
-    to make your life easier. The one we will be using in this example is for
-    Django. For others, and information on how to create one, check out
-    :doc:`decorators`.
+If there is no support for your favourite framework and you are interested
+in providing it then you have come to the right place. OAuthLib can handle
+the OAuth logic and leave you to support a few framework and setup specific
+tasks such as marshalling request objects into URI, headers and body arguments
+as well as provide an interface for a backend to store tokens, clients, etc.
 
-    The main purpose of these decoraters is to help marshall between the
-    framework specific request object and framework agnostic url, headers, body
-    and http method parameters. They may also be useful for making sure common
-    best security practices are followed.
+.. _`django-oauth-toolkit`: https://github.com/evonove/django-oauth-toolkit
+.. _`flask-oauthlib`: https://github.com/lepture/flask-oauthlib
 
-    Their purpose is not to be a full solution to all your needs as a provider,
-    for that you will want to seek out framework specific extensions building
-    upon OAuthLib. See the section on :doc:`decorators` for a list of
-    extensions.
-
-    Relevant sections include:
-
-    .. toctree::
-        :maxdepth: 1
-
-        decorators
-
-**2. Create your datastore models**
+**1. Create your datastore models**
 
     These models will represent various OAuth specific concepts. There are a few
     important links between them that the security of OAuth is based on. Below
@@ -191,7 +179,7 @@ preview of a near future =)
 
                 expires_at = django.db.models.DateTimeField()
 
-**3. Implement a validator**
+**2. Implement a validator**
 
     The majority of the work involved in implementing an OAuth 2 provider
     relates to mapping various validation and persistence methods to a storage
@@ -232,7 +220,7 @@ preview of a near future =)
         security
 
 
-**4. Create your composite endpoint**
+**3. Create your composite endpoint**
 
     Each of the endpoints can function independently from each other, however
     for this example it is easier to consider them as one unit. An example of a
@@ -246,7 +234,6 @@ preview of a near future =)
 
         validator = MyRequestValidator()
         server = WebApplicationServer(validator)
-        provider = OAuth2ProviderDecorator('/error', server)    # See next section
 
     Relevant sections include:
 
@@ -256,55 +243,20 @@ preview of a near future =)
         preconfigured_servers
 
 
-**5. Decorate your endpoint views**
+**4. Create your endpoint views**
 
     We are implementing support for the Authorization Code Grant and will
     therefore need two views for the authorization, pre- and post-authorization
     together with the token view. We also include an error page to redirect
     users to if the client supplied invalid credentials in their redirection,
-    for example an invalid redirect URI::
-
-        @login_required
-        @provider.pre_authorization_view
-        def authorize(request, client_id=None, scopes=None, state=None,
-            redirect_uri=None, response_type=None):
-            # This is the traditional authorization page
-            # Scopes will be the list of scopes client requested access too
-            # You will want to present them in a nice form where the user can
-            # select which scopes they allow the client to access.
-            return render(request, 'authorize.html', {'scopes': scopes})
-
-
-        @login_required
-        @provider.post_authorization_view
-        def authorization_response(request):
-            # This is where the form submitted from authorize should end up
-            # Which scopes user authorized access to + extra credentials you want
-            # appended to the request object passed into the validator methods.
-            # In almost every case, you will want to include the current
-            # user in these extra credentials in order to associate the user with
-            # the authorization code or bearer token.
-            return request.POST.getlist['scopes'], {'user': request.user}
-
-
-        @provider.access_token_view
-        def token_response(request):
-            # Not much too do here for you, return a dict with extra credentials
-            # you want appended to request.credentials passed to the save_bearer_token
-            # method of the validator.
-            return {'extra': 'creds'}
-
-        def error(request):
-            # The /error page users will be redirected to if there was something
-            # wrong with the credentials the client included when redirecting the
-            # user to the authorization form. Mainly if the client was invalid or
-            # included a malformed / invalid redirect url.
-            # Error and description can be found in
-            # GET['error'] and GET['error_description']
-            return HttpResponse('Bad client! Warn user!')
-
-
-**6. Protect your APIs using scopes**
+    for example an invalid redirect URI.
+
+    The rest of this section will come soon.
+
+**5. Protect your APIs using scopes**
+
+    The definition of ``protected_resource_view`` will come soon. Please see
+    the framework specific extensions outlined in the beginning for now.
 
     At this point you are ready to protect your API views with OAuth. Take some
     time to come up with a good set of scopes as they can be very powerful in
@@ -330,7 +282,7 @@ preview of a near future =)
             # A view that has its views functionally set.
             return HttpResponse('pictures of cats')
 
-**7. Let us know how it went!**
+**6. Let us know how it went!**
 
     Drop a line in our `G+ community`_ or open a `GitHub issue`_ =)