jpadilla / pyjwt

JSON Web Token implementation in Python
https://pyjwt.readthedocs.io
MIT License
5.14k stars 687 forks source link

Emit a deprecation warning for unsupported kwargs #776

Closed sirosen closed 2 years ago

sirosen commented 2 years ago

This is half of #258. It cannot be completed without a breaking release, but the API should be reconsidered at that time because it doesn't make a ton of sense for validation-specific arguments like leeway to be presented as args to decode().


**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.

sirosen commented 2 years ago

The conflict was just changelog lines for the Unreleased section. I've resolved with a rebase.