* changed "function definition" to "function signature" in two docstrings

* fixed some formatting issues in `prepare_token_request` docstring
* slightly altered `prepare_token_request` in handling nontruthy values for `client_secret`.

3 files changed, 21 insertions, 15 deletions

diff --git a/oauthlib/oauth2/rfc6749/clients/service_application.py b/oauthlib/oauth2/rfc6749/clients/service_application.py
index 759e0d2..35333d8 100644
--- a/oauthlib/oauth2/rfc6749/clients/service_application.py
+++ b/oauthlib/oauth2/rfc6749/clients/service_application.py
@@ -121,7 +121,7 @@ class ServiceApplicationClient(Client):
         :param kwargs: Extra credentials to include in the token request.
 
         Parameters marked with a `*` above are not explicit arguments in the
-        function definition, but are specially documented arguments for items
+        function signature, but are specially documented arguments for items
         appearing in the generic `**kwargs` keyworded input.
 
         The "scope" parameter may be used, as defined in the Assertion
diff --git a/oauthlib/oauth2/rfc6749/parameters.py b/oauthlib/oauth2/rfc6749/parameters.py
index 21c8605..4d0baee 100644
--- a/oauthlib/oauth2/rfc6749/parameters.py
+++ b/oauthlib/oauth2/rfc6749/parameters.py
@@ -100,13 +100,6 @@ def prepare_token_request(grant_type, body='', include_client_id=True, **kwargs)
     :param body: Existing request body (URL encoded string) to embed parameters
                  into. This may contain extra paramters. Default ''.
 
-    :param code: If using authorization_code grant, pass the previously
-                 obtained authorization code as the ``code`` argument. 
-
-    :param redirect_uri: If the "redirect_uri" parameter was included in the
-                         authorization request as described in
-                         `Section 4.1.1`_, and their values MUST be identical. *
-
     :param include_client_id: `True` (default) to send the `client_id` in the
                               body of the upstream request. This is required
                               if the client is not authenticating with the
@@ -117,10 +110,22 @@ def prepare_token_request(grant_type, body='', include_client_id=True, **kwargs)
     :param client_id: Unicode client identifier. Will only appear if
                       `include_client_id` is True. *
 
+    :param client_secret: Unicode client secret. Will only appear if set to a
+                          value that is not `None`. Invoking this function with
+                          an empty string will send an empty `client_secret`
+                          value to the server. *
+
+    :param code: If using authorization_code grant, pass the previously
+                 obtained authorization code as the ``code`` argument. *
+
+    :param redirect_uri: If the "redirect_uri" parameter was included in the
+                         authorization request as described in
+                         `Section 4.1.1`_, and their values MUST be identical. *
+
     :param kwargs: Extra arguments to embed in the request body.
 
     Parameters marked with a `*` above are not explicit arguments in the
-    function definition, but are specially documented arguments for items
+    function signature, but are specially documented arguments for items
     appearing in the generic `**kwargs` keyworded input.
 
     An example of an authorization code token request body:
@@ -143,15 +148,17 @@ def prepare_token_request(grant_type, body='', include_client_id=True, **kwargs)
         if client_id is not None:
             params.append((unicode_type('client_id'), client_id))
 
+    # the kwargs iteration below only supports including boolean truth (truthy)
+    # values, but some servers may require an empty string for `client_secret`
+    client_secret = kwargs.pop('client_secret', None)
+    if client_secret is not None:
+        params.append((unicode_type('client_secret'), client_secret))
+
+    # this handles: `code`, `redirect_uri`, and other undocumented params
     for k in kwargs:
-        # this handles: `code`, `redirect_uri`, or undocumented params
         if kwargs[k]:
             params.append((unicode_type(k), kwargs[k]))
 
-    if ('client_secret' in kwargs) and ('client_secret' not in params):
-        if kwargs['client_secret'] == '':
-            params.append((unicode_type('client_secret'), kwargs['client_secret']))
-
     return add_params_to_qs(body, params)
 
 
diff --git a/tests/oauth2/rfc6749/clients/test_web_application.py b/tests/oauth2/rfc6749/clients/test_web_application.py
index 3d9c188..092f93e 100644
--- a/tests/oauth2/rfc6749/clients/test_web_application.py
+++ b/tests/oauth2/rfc6749/clients/test_web_application.py
@@ -234,7 +234,6 @@ class WebApplicationClientTest(TestCase):
         self.assertEqual(r4_params['client_id'], self.client_id)
         self.assertEqual(r4_params['client_secret'], '')
 
-
         # scenario 4b, `client_secret` is `None`
         r4b = client.prepare_request_body(include_client_id=True, client_secret=None)
         r4b_params = dict(urlparse.parse_qsl(r4b, keep_blank_values=True))