* addresing ticket #585

* `prepare_request_body` client_id is deprecated in favor of include_client_id
* a new unit test `test_prepare_request_body` is added to ensure conformity of several use cases
* the docstrings for the `body` param have been consolidated and standardized across multiple functions linked to `prepare_request_body` for clarity

5 files changed, 39 insertions, 14 deletions

diff --git a/oauthlib/oauth2/rfc6749/clients/backend_application.py b/oauthlib/oauth2/rfc6749/clients/backend_application.py
index cbad8b7..99dbfc5 100644
--- a/oauthlib/oauth2/rfc6749/clients/backend_application.py
+++ b/oauthlib/oauth2/rfc6749/clients/backend_application.py
@@ -37,6 +37,8 @@ class BackendApplicationClient(Client):
         following parameters using the "application/x-www-form-urlencoded"
         format per `Appendix B`_ in the HTTP request entity-body:
 
+        :param body: Existing request body (URL encoded string) to embed parameters
+                     into. This may contain extra paramters. Default ''.
         :param scope:   The scope of the access request as described by
                         `Section 3.3`_.
         :param kwargs:  Extra credentials to include in the token request.
diff --git a/oauthlib/oauth2/rfc6749/clients/base.py b/oauthlib/oauth2/rfc6749/clients/base.py
index 406832d..d8ded50 100644
--- a/oauthlib/oauth2/rfc6749/clients/base.py
+++ b/oauthlib/oauth2/rfc6749/clients/base.py
@@ -254,7 +254,8 @@ class Client(object):
         :param redirect_url: The redirect_url supplied with the authorization
         request (if there was one).
 
-        :param body: Request body (URL encoded string).
+        :param body: Existing request body (URL encoded string) to embed parameters
+                     into. This may contain extra paramters. Default ''.
 
         :param kwargs: Additional parameters to included in the request.
 
@@ -286,7 +287,8 @@ class Client(object):
 
         :param refresh_token: Refresh token string.
 
-        :param body: Request body (URL encoded string).
+        :param body: Existing request body (URL encoded string) to embed parameters
+                     into. This may contain extra paramters. Default ''.
 
         :param scope: List of scopes to request. Must be equal to
         or a subset of the scopes granted when obtaining the refresh
diff --git a/oauthlib/oauth2/rfc6749/clients/legacy_application.py b/oauthlib/oauth2/rfc6749/clients/legacy_application.py
index b16fc9f..8f03695 100644
--- a/oauthlib/oauth2/rfc6749/clients/legacy_application.py
+++ b/oauthlib/oauth2/rfc6749/clients/legacy_application.py
@@ -47,6 +47,8 @@ class LegacyApplicationClient(Client):
 
         :param username:    The resource owner username.
         :param password:    The resource owner password.
+        :param body: Existing request body (URL encoded string) to embed parameters
+                     into. This may contain extra paramters. Default ''.
         :param scope:   The scope of the access request as described by
                         `Section 3.3`_.
         :param kwargs:  Extra credentials to include in the token request.
diff --git a/oauthlib/oauth2/rfc6749/clients/service_application.py b/oauthlib/oauth2/rfc6749/clients/service_application.py
index 3045676..6bb784e 100644
--- a/oauthlib/oauth2/rfc6749/clients/service_application.py
+++ b/oauthlib/oauth2/rfc6749/clients/service_application.py
@@ -97,18 +97,19 @@ class ServiceApplicationClient(Client):
         :param issued_at: A unix timestamp of when the JWT was created.
                           Defaults to now, i.e. ``time.time()``.
 
+        :param extra_claims: A dict of additional claims to include in the JWT.
+
+        :param body: Existing request body (URL encoded string) to embed parameters
+                     into. This may contain extra paramters. Default ''.
+
+        :param scope: The scope of the access request.
+
         :param not_before: A unix timestamp after which the JWT may be used.
                            Not included unless provided.
 
         :param jwt_id: A unique JWT token identifier. Not included unless
                        provided.
 
-        :param extra_claims: A dict of additional claims to include in the JWT.
-
-        :param scope: The scope of the access request.
-
-        :param body: Request body (string) with extra parameters.
-
         :param kwargs: Extra credentials to include in the token request.
 
         The "scope" parameter may be used, as defined in the Assertion
diff --git a/oauthlib/oauth2/rfc6749/clients/web_application.py b/oauthlib/oauth2/rfc6749/clients/web_application.py
index c14a5f8..ec59b31 100644
--- a/oauthlib/oauth2/rfc6749/clients/web_application.py
+++ b/oauthlib/oauth2/rfc6749/clients/web_application.py
@@ -8,6 +8,8 @@ for consuming and providing OAuth 2.0 RFC6749.
 """
 from __future__ import absolute_import, unicode_literals
 
+import warnings
+
 from ..parameters import (parse_authorization_code_response,
                           parse_token_response, prepare_grant_uri,
                           prepare_token_request)
@@ -85,17 +87,14 @@ class WebApplicationClient(Client):
         return prepare_grant_uri(uri, self.client_id, 'code',
                                  redirect_uri=redirect_uri, scope=scope, state=state, **kwargs)
 
-    def prepare_request_body(self, client_id=None, code=None, body='',
-                             redirect_uri=None, **kwargs):
+    def prepare_request_body(self, code=None, redirect_uri=None, body='',
+                             include_client_id=True, **kwargs):
         """Prepare the access token request body.
 
         The client makes a request to the token endpoint by adding the
         following parameters using the "application/x-www-form-urlencoded"
         format in the HTTP request entity-body:
 
-        :param client_id:   REQUIRED, if the client is not authenticating with the
-                            authorization server as described in `Section 3.2.1`_.
-
         :param code:    REQUIRED. The authorization code received from the
                         authorization server.
 
@@ -103,6 +102,15 @@ class WebApplicationClient(Client):
                                 authorization request as described in `Section 4.1.1`_, and their
                                 values MUST be identical.
 
+        :param body: Existing request body (URL encoded string) to embed parameters
+                     into. This may contain extra paramters. Default ''.
+
+        :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
+                                  authorization server as described in `Section 3.2.1`_.
+        :type include_client_id: Boolean
+
         :param kwargs: Extra parameters to include in the token request.
 
         In addition OAuthLib will add the ``grant_type`` parameter set to
@@ -124,8 +132,18 @@ class WebApplicationClient(Client):
         .. _`Section 3.2.1`: https://tools.ietf.org/html/rfc6749#section-3.2.1
         """
         code = code or self.code
+        if 'client_id' in kwargs:
+            warnings.warn("`client_id` has been deprecated in favor of "
+                          "`include_client_id`, a boolean value which will "
+                          "include the already configured `self.client_id`.",
+                          DeprecationWarning)
+            if kwargs['client_id'] != self.client_id:
+                raise ValueError("`client_id` was supplied as an argument, but "
+                                 "it does not match `self.client_id`")
+        if include_client_id:
+            kwargs['client_id'] = self.client_id
         return prepare_token_request('authorization_code', code=code, body=body,
-                                     client_id=client_id, redirect_uri=redirect_uri, **kwargs)
+                                     redirect_uri=redirect_uri, **kwargs)
 
     def parse_request_uri_response(self, uri, state=None):
         """Parse the URI query for code and state.