Fixes #921: Add now parameter to decode

[daBrado]

Add a now parameter to the decode functions so that one may manually specify what the current time is.

Also add some tests, though only for exp on the assumption that the same code paths are used for nbf and iat as the non-now tests.

[Copilot]

Pull Request Overview

This PR adds a now parameter to the JWT decode methods to allow manual specification of the current time for token validation. This enables testing time-dependent token validation (expiration, not-before, issued-at) without relying on system time.

• Adds now parameter accepting float, datetime, or None to decode(), decode_complete(), and _validate_claims() methods
• Updates validation logic to use the provided now value instead of always using current system time
• Adds tests to verify the now parameter works correctly with expiration validation using both numeric timestamps and datetime objects

Reviewed Changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
jwt/api_jwt.py	Adds now parameter to decode methods and validation logic, with type checking and conversion for float/datetime inputs
tests/test_api_jwt.py	Adds two test cases verifying the now parameter behavior with both numeric timestamps and datetime objects

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The type check only validates against int and float, but line 393 already handles the datetime case. This condition will always be reached after handling None and datetime, so it could be simplified to just check not isinstance(now, (int, float)) or provide a more specific error message that clarifies the type has already been partially validated.

Suggested change

	raise TypeError("now must be a float, datetime or None")
	raise TypeError("now must be a number (int or float)")

[daBrado]

The TypeError message reflects what the original value coming into the method is allowed to be, not what the value may be by the time we've reached that point in the code. I.e. the initial now value as passed in must be a float, datetime or None. (Or if you prefer, a number, datetime or None.)

[auvipy]

please resolve the merge conflicts

[auvipy]

please fix the failing CI

[daBrado]

I'm afraid I don't understand the Python 3.11 CI failures...

[auvipy]

i got this

CI/job definition context (why it’s failing)

In the workflow (.github/workflows/main.yml at ref 57f119f), the build runs tox, and tox runs the docs build. The docs build explicitly uses Sphinx with -W, so any warning breaks the job. That’s why tests pass but CI still fails.