Typing Stubs for python-jose

3.5.0.20260408 · active · verified Sat Apr 11

This package provides PEP 561 type stubs for the `python-jose` library, enabling static type checking tools like Mypy and Pyright to analyze code that uses `python-jose`. It allows developers to benefit from type hints for JOSE (JSON Object Signing and Encryption) operations, including JWS, JWE, JWK, and JWT. The current version is 3.5.0.20260408, with releases tied to the typeshed project's daily automated updates.

Warnings

gotcha Attempting to import or run code directly from `types-python-jose` will result in `ImportError` or `AttributeError`.
Fix: Always import functionality from the actual `python-jose` runtime library (e.g., `from jose import jwt`). `types-python-jose` only provides `.pyi` stub files for type checkers and is not meant for runtime execution.
gotcha This stub package requires the `python-jose` runtime library to be installed and present for your application to actually function.
Fix: Ensure `pip install python-jose` is run in your environment. For specific cryptographic backends, consider `pip install python-jose[cryptography]` (recommended) or `python-jose[pycryptodome]` to include necessary cryptographic dependencies.
deprecated The `python-jose` library itself has been noted as 'barely maintained' by some sources as of early 2024, suggesting `PyJWT` or `joserfc` as potentially more secure and actively maintained alternatives for JWT operations.
Fix: Evaluate `python-jose`'s current maintenance status and consider migrating to `PyJWT` or `joserfc` if active development and security patches are critical for your application. If migrating, ensure to update your imports and API calls accordingly.
breaking While typeshed aims for minimal breaking changes, any version bump of `types-python-jose` can introduce changes that might cause your code to fail type checking, especially if the underlying `python-jose` library or typing standards evolve.
Fix: Pin the version of `types-python-jose` to a known compatible version (e.g., `types-python-jose==3.5.0.20260408`) and test thoroughly before updating. Alternatively, use the same version bounds for `types-python-jose` as for `python-jose` (e.g., `types-python-jose~=3.5`).

Install

pip install types-python-jose Install only stubs
pip install python-jose[cryptography] types-python-jose Install runtime (recommended backend) and stubs

Imports

jwt
```
from jose import jwt
```
Users should import functionality directly from the runtime library `jose`. `types-python-jose` is a stub-only package (.pyi files) and does not contain runnable code itself; it's solely for type checkers.
JWS
```
from jose import jws
```
Similar to `jwt`, other JOSE components like JWS are imported from the `jose` runtime package.

Quickstart

This quickstart demonstrates basic JWT (JSON Web Token) encoding and decoding using the `python-jose` library. Installing `types-python-jose` alongside it provides static type checking benefits for these operations. It shows how to encode a payload into a JWT using a symmetric key and then decode it. Remember to manage your `SECRET_KEY` securely in a production environment, ensuring it meets the length requirements for your chosen algorithm (e.g., at least 32 bytes for HS256). The `python-jose` library supports various JOSE specifications including JWS, JWE, and JWK, with different cryptographic backends.

import os
from jose import jwt
from jose.constants import ALGORITHMS

# In a real application, load a secret from environment variables
# or a secure configuration management system.
SECRET_KEY = os.environ.get('JOSE_SECRET_KEY', 'your-secret-key-that-is-at-least-32-bytes-long')

# Encoding a JWT
payload = {
    "sub": "user123",
    "name": "John Doe",
    "admin": True
}

# Use a strong algorithm like HS256 for symmetric keys
# For asymmetric keys (RS256, ES256), you'd use public/private key pairs.
algorithm = ALGORITHMS.HS256

# Ensure your secret is bytes for HS algorithms
if isinstance(SECRET_KEY, str):
    # Pad secret if too short for HS256 (requires 32 bytes for 256-bit key)
    SECRET_KEY_BYTES = SECRET_KEY.encode('utf-8').ljust(32, b'\0')[:32]
else:
    SECRET_KEY_BYTES = SECRET_KEY

encoded_jwt = jwt.encode(payload, SECRET_KEY_BYTES, algorithm=algorithm)
print(f"Encoded JWT: {encoded_jwt}")

# Decoding a JWT
try:
    decoded_payload = jwt.decode(encoded_jwt, SECRET_KEY_BYTES, algorithms=[algorithm])
    print(f"Decoded payload: {decoded_payload}")
except jwt.JWTError as e:
    print(f"JWT decoding error: {e}")

# Example with an incorrect key (for demonstration of type safety and error handling)
try:
    wrong_key = b"wrong-secret".ljust(32, b'\0')[:32] # Pad for demonstration
    jwt.decode(encoded_jwt, wrong_key, algorithms=[algorithm])
except jwt.JWTError as e:
    print(f"Expected error with wrong key: {e}")

view raw JSON →