Commits

Cmed Technology committed efe7b39 Draft

tidied docs

Comments (0)

Files changed (3)

restapiblueprint/features/steps/rest.py

+"""Reasonably complete set of BDD steps for testing a REST API.
+
+Some state is set-up and shared between steps using the context variable. It is
+reset at the start of every scenario by
+:func:`restapiblueprint.features.environment.before_scenario`
+
+"""
 from nose.tools import assert_equal
 import behave
 import jinja2

restapiblueprint/lib/__init__.py

 
 
 def document_using(doc_url):
-    """Decorator to redirect to documentation at given url.
+    """Decorator to redirect to HTML documentation at given url.
 
-    This is only done for http GET's which express a preference for HTML over
-    JSON in the Accept header.
+    This is only done for HTTP GET's which express a preference for HTML over
+    JSON in the Accept header. Otherwise there is no redirection.
 
     """
     @decorator
 def validate_json(validate_function, default=None):
     """Decorator to validate and marshal the incoming JSON.
 
-    Set request.json to the value returned from calling validate_function on
+    Sets request.json to the value returned from calling validate_function on
     request.json (or default() if request.json is None). If this raises
     an exception then the call stack is terminated early with a
     :func:`make_error` from the contents of the exception stack trace and a 400.
 
     If request.json is None then default() is used. Note that
-      1) it is a callable which must create the default value
+      1) default is a callable which must create the default value
          (to avoid accidental re-use of mutables)
       2) the result is still passed through the validate_function
          (to ensure the invariant holds)
 
     Otherwise return None.
 
-    Intended to be used with :func:`lib.check`.
+    Intended to be used with :func:`check`.
 
     """
     if len(request.data.strip()) > 0:

restapiblueprint/lib/oauth.py

-"""2-legged oauth 1.0 utilities.
+"""2-legged OAuth 1.0 utilities.
 
-Simplify usage down to essentially two functions:
+Simplifies usage to signing and verifying.
 
-    1) sign
-    2) verify
+The signature parameters can be carried either in the URL or in the HTTP
+Authorization header (two functions provided). The Verify function looks in both
+places. No support is provided for carrying or verifing the OAuth parameters in
+the body.
 
-We do NOT include the body in the signature or create a body hash. Therefore
+The body is NOT included in the signature. Also, no body hash is created and so
 there is no oauth_body_hash parameter. This is because it is not part of the
 specification and because it has a performance impact with large messages. We
 trick the oauth2 library into not hashing the body by setting
-is_form_encoded=True. See
-
-    http://oauth.googlecode.com/svn/spec/ext/body_hash/1.0/oauth-bodyhash.html
-
-Note that we also assume that the body does NOT contain any of the oauth
-parameters. They must be in the Authorization HTTP header or in the URL.
+is_form_encoded=True.
 
 See
     http://tools.ietf.org/html/rfc5849
     http://oauth.net
+    http://oauth.googlecode.com/svn/spec/ext/body_hash/1.0/oauth-bodyhash.html
 
 """
 import oauth2