Updating oauth1 parameters.prepare_headers in order to apply more of the spec language to documentation.

1 files changed, 55 insertions, 13 deletions

diff --git a/oauthlib/oauth1/rfc5849/parameters.py b/oauthlib/oauth1/rfc5849/parameters.py
index c809a39..8b485e5 100644
--- a/oauthlib/oauth1/rfc5849/parameters.py
+++ b/oauthlib/oauth1/rfc5849/parameters.py
@@ -50,31 +50,73 @@ def order_oauth_parameters(params):
 
 
 @utils.filter_params
-def prepare_headers(params, headers, realm=None):
-    """Prepare the Authorization header.
-
+def prepare_headers(params, headers=None, realm=None):
+    """**Prepare the Authorization header.**
     Per `section 3.5.1`_ of the spec.
 
-    .. _`section 3.5.1`: http://tools.ietf.org/html/rfc5849#section-3.5.1
+    Protocol parameters can be transmitted using the HTTP "Authorization"
+    header field as defined by `RFC2617`_ with the auth-scheme name set to
+    "OAuth" (case insensitive).
+
+    For example::
+
+        Authorization: OAuth realm="Example",
+            oauth_consumer_key="0685bd9184jfhq22",
+            oauth_token="ad180jjd733klru7",
+            oauth_signature_method="HMAC-SHA1",
+            oauth_signature="wOJIO9A2W5mFwDgiDvZbTSMK%2FPY%3D",
+            oauth_timestamp="137131200",
+            oauth_nonce="4572616e48616d6d65724c61686176",
+            oauth_version="1.0"
 
+
+    .. _`section 3.5.1`: http://tools.ietf.org/html/rfc5849#section-3.5.1
+    .. _`RFC2617`: http://tools.ietf.org/html/rfc2617
     """
+
     headers = headers or {}
 
-    # TODO: Realm should always be the first parameter, right?
-    # Doesn't seem to be specified.
-    full_params = []
+    # Protocol parameters SHALL be included in the "Authorization" header
+    # field as follows:
+    authorization_header_parameters_parts = []
+    for oauth_parameter_name, value in params:
+        # 1.  Parameter names and values are encoded per Parameter Encoding
+        #     (`Section 3.6`_)
+        #
+        # .. _`Section 3.6`: http://tools.ietf.org/html/rfc5849#section-3.6
+        escaped_name = utils.escape(oauth_parameter_name)
+        escaped_value = utils.escape(value)
+
+        # 2.  Each parameter's name is immediately followed by an "=" character
+        #     (ASCII code 61), a """ character (ASCII code 34), the parameter
+        #     value (MAY be empty), and another """ character (ASCII code 34).
+        part = u'{0}="{1}"'.format(escaped_name, escaped_value)
+
+        authorization_header_parameters_parts.append(part)
+
+    # 3.  Parameters are separated by a "," character (ASCII code 44) and
+    #     OPTIONAL linear whitespace per `RFC2617`_.
+    #
+    # .. _`RFC2617`: http://tools.ietf.org/html/rfc2617
+    authorization_header_parameters = ', '.join(
+        authorization_header_parameters_parts)
+
+    # 4.  The OPTIONAL "realm" parameter MAY be added and interpreted per
+    #     `RFC2617 section 1.2`_.
+    #
+    # .. _`RFC2617 section 1.2`: http://tools.ietf.org/html/rfc2617#section-1.2
     if realm:
-        full_params.append((u"realm", realm))
-    full_params.extend(params)
+        # NOTE: realm should *not* be escaped
+        authorization_header_parameters = (u'realm="%s", ' % realm +
+            authorization_header_parameters)
 
-    # Only oauth_ and realm parameters should remain by this point.
-    authorization_header = 'OAuth ' + ', '.join(
-        ['{0}="{1}"'.format(utils.escape(k), utils.escape(v)) for k, v in full_params])
+    # the auth-scheme name set to "OAuth" (case insensitive).
+    authorization_header = u'OAuth %s' % authorization_header_parameters
 
     # contribute the Authorization header to the given headers
     full_headers = {}
     full_headers.update(headers)
-    full_headers['Authorization'] = authorization_header
+    full_headers[u'Authorization'] = authorization_header
     return full_headers