{"id":3386,"library":"types-python-jose","title":"Typing Stubs for python-jose","description":"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.","status":"active","version":"3.5.0.20260408","language":"en","source_language":"en","source_url":"https://github.com/python/typeshed/tree/main/stubs/python-jose","tags":["typing","stubs","type hints","jose","jwt","jws","jwe"],"install":[{"cmd":"pip install types-python-jose","lang":"bash","label":"Install only stubs"},{"cmd":"pip install python-jose[cryptography] types-python-jose","lang":"bash","label":"Install runtime (recommended backend) and stubs"}],"dependencies":[{"reason":"Provides the runtime functionality for which these are stubs. This stub package aims to provide accurate annotations for `python-jose==3.5.*`.","package":"python-jose","optional":false}],"imports":[{"note":"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.","wrong":"from types_python_jose import jwt","symbol":"jwt","correct":"from jose import jwt"},{"note":"Similar to `jwt`, other JOSE components like JWS are imported from the `jose` runtime package.","wrong":"from types_python_jose import JWS","symbol":"JWS","correct":"from jose import jws"}],"quickstart":{"code":"import os\nfrom jose import jwt\nfrom jose.constants import ALGORITHMS\n\n# In a real application, load a secret from environment variables\n# or a secure configuration management system.\nSECRET_KEY = os.environ.get('JOSE_SECRET_KEY', 'your-secret-key-that-is-at-least-32-bytes-long')\n\n# Encoding a JWT\npayload = {\n    \"sub\": \"user123\",\n    \"name\": \"John Doe\",\n    \"admin\": True\n}\n\n# Use a strong algorithm like HS256 for symmetric keys\n# For asymmetric keys (RS256, ES256), you'd use public/private key pairs.\nalgorithm = ALGORITHMS.HS256\n\n# Ensure your secret is bytes for HS algorithms\nif isinstance(SECRET_KEY, str):\n    # Pad secret if too short for HS256 (requires 32 bytes for 256-bit key)\n    SECRET_KEY_BYTES = SECRET_KEY.encode('utf-8').ljust(32, b'\\0')[:32]\nelse:\n    SECRET_KEY_BYTES = SECRET_KEY\n\nencoded_jwt = jwt.encode(payload, SECRET_KEY_BYTES, algorithm=algorithm)\nprint(f\"Encoded JWT: {encoded_jwt}\")\n\n# Decoding a JWT\ntry:\n    decoded_payload = jwt.decode(encoded_jwt, SECRET_KEY_BYTES, algorithms=[algorithm])\n    print(f\"Decoded payload: {decoded_payload}\")\nexcept jwt.JWTError as e:\n    print(f\"JWT decoding error: {e}\")\n\n# Example with an incorrect key (for demonstration of type safety and error handling)\ntry:\n    wrong_key = b\"wrong-secret\".ljust(32, b'\\0')[:32] # Pad for demonstration\n    jwt.decode(encoded_jwt, wrong_key, algorithms=[algorithm])\nexcept jwt.JWTError as e:\n    print(f\"Expected error with wrong key: {e}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"Attempting to import or run code directly from `types-python-jose` will result in `ImportError` or `AttributeError`.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"This stub package requires the `python-jose` runtime library to be installed and present for your application to actually function.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"deprecated","affected_versions":"python-jose versions < 3.5.0 and potentially current/future versions if maintenance doesn't improve."},{"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`).","message":"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.","severity":"breaking","affected_versions":"All versions, particularly when updating `types-python-jose` across major/minor versions or when `python-jose` itself updates significantly."}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}