Emit a deprecation warning for unsupported kwargs (#776)

`**kwargs` usages cannot be removed without breaking backwards
compatibility. Unsupported kwargs cannot even be rejected without
breaking compatibility.

However, this does not mean that the library cannot identify and
warn when unsupported arguments are used. The warning behavior simply
has to be separated from any removal of `**kwargs`.

All legitimate `**kwargs` usages have been replaced with explicit
arguments. Any other arguments will be captured under `**kwargs` and
trigger the deprecation warnings. In the cases of
`decode() -> decode_complete()` passthrough, the passthrough has been
removed to avoid duplicate deprecation warnings on a single usage.

This makes a very subtle behavioral change to `**kwargs` *only* for
the case of a subclass of PyJWT or PyJWS. Extra arguments used by a
specialized subclass won't pass through transparently anymore. In
such a case the subclass author has multiple resolutions available,
including reimplementation of the `decode()` method to passthrough
the additional argument. Although technically backwards-incompatible
for a niche subclassing usage, this behavior is very nearly identical
and shouldn't pose an issue for the vast majority of pyjwt users.

The deprecation warning does not cover all deprecated usages. In
particular, several passthrough arguments for claim validation should
probably be made available via `options` and later removed. The
arguments in need of attention now have inline comments in the
signature definitions, but are otherwise left unmodified, leaving
current usages correct and valid.

1 files changed, 52 insertions, 7 deletions

diff --git a/jwt/api_jwt.py b/jwt/api_jwt.py
index a011c0f..b08e950 100644
--- a/jwt/api_jwt.py
+++ b/jwt/api_jwt.py
@@ -15,6 +15,7 @@ from .exceptions import (
     InvalidIssuerError,
     MissingRequiredClaimError,
 )
+from .warnings import RemovedInPyjwt3Warning
 
 
 class PyJWT:
@@ -69,15 +70,32 @@ class PyJWT:
         key: str = "",
         algorithms: Optional[List[str]] = None,
         options: Optional[Dict[str, Any]] = None,
+        # deprecated arg, remove in pyjwt3
+        verify: Optional[bool] = None,
+        # could be used as passthrough to api_jws, consider removal in pyjwt3
+        detached_payload: Optional[bytes] = None,
+        # passthrough arguments to _validate_claims
+        # consider putting in options
+        audience: Optional[str] = None,
+        issuer: Optional[str] = None,
+        leeway: Union[int, float, timedelta] = 0,
+        # kwargs
         **kwargs,
     ) -> Dict[str, Any]:
+        if kwargs:
+            warnings.warn(
+                "passing additional kwargs to decode_complete() is deprecated "
+                "and will be removed in pyjwt version 3. "
+                f"Unsupported kwargs: {tuple(kwargs.keys())}",
+                RemovedInPyjwt3Warning,
+            )
         options = dict(options or {})  # shallow-copy or initialize an empty dict
         options.setdefault("verify_signature", True)
 
         # If the user has set the legacy `verify` argument, and it doesn't match
         # what the relevant `options` entry for the argument is, inform the user
         # that they're likely making a mistake.
-        if "verify" in kwargs and kwargs["verify"] != options["verify_signature"]:
+        if verify is not None and verify != options["verify_signature"]:
             warnings.warn(
                 "The `verify` argument to `decode` does nothing in PyJWT 2.0 and newer. "
                 "The equivalent is setting `verify_signature` to False in the `options` dictionary. "
@@ -102,7 +120,7 @@ class PyJWT:
             key=key,
             algorithms=algorithms,
             options=options,
-            **kwargs,
+            detached_payload=detached_payload,
         )
 
         try:
@@ -113,7 +131,9 @@ class PyJWT:
             raise DecodeError("Invalid payload string: must be a json object")
 
         merged_options = {**self.options, **options}
-        self._validate_claims(payload, merged_options, **kwargs)
+        self._validate_claims(
+            payload, merged_options, audience=audience, issuer=issuer, leeway=leeway
+        )
 
         decoded["payload"] = payload
         return decoded
@@ -124,14 +144,39 @@ class PyJWT:
         key: str = "",
         algorithms: Optional[List[str]] = None,
         options: Optional[Dict[str, Any]] = None,
+        # deprecated arg, remove in pyjwt3
+        verify: Optional[bool] = None,
+        # could be used as passthrough to api_jws, consider removal in pyjwt3
+        detached_payload: Optional[bytes] = None,
+        # passthrough arguments to _validate_claims
+        # consider putting in options
+        audience: Optional[str] = None,
+        issuer: Optional[str] = None,
+        leeway: Union[int, float, timedelta] = 0,
+        # kwargs
         **kwargs,
     ) -> Dict[str, Any]:
-        decoded = self.decode_complete(jwt, key, algorithms, options, **kwargs)
+        if kwargs:
+            warnings.warn(
+                "passing additional kwargs to decode() is deprecated "
+                "and will be removed in pyjwt version 3. "
+                f"Unsupported kwargs: {tuple(kwargs.keys())}",
+                RemovedInPyjwt3Warning,
+            )
+        decoded = self.decode_complete(
+            jwt,
+            key,
+            algorithms,
+            options,
+            verify=verify,
+            detached_payload=detached_payload,
+            audience=audience,
+            issuer=issuer,
+            leeway=leeway,
+        )
         return decoded["payload"]
 
-    def _validate_claims(
-        self, payload, options, audience=None, issuer=None, leeway=0, **kwargs
-    ):
+    def _validate_claims(self, payload, options, audience=None, issuer=None, leeway=0):
         if isinstance(leeway, timedelta):
             leeway = leeway.total_seconds()