{"id":3843,"library":"types-oauthlib","title":"Typing stubs for oauthlib","description":"types-oauthlib provides typing stubs for the `oauthlib` library, a generic, spec-compliant OAuth framework for Python. It enables static type checkers like MyPy and Pyright to validate code that uses `oauthlib`, enhancing code quality and helping prevent runtime errors. This package is part of the `typeshed` project, which automatically releases stub updates (up to once a day) to keep pace with `oauthlib` and other third-party packages.","status":"active","version":"3.3.0.20260408","language":"en","source_language":"en","source_url":"https://github.com/python/typeshed","tags":["typing","stubs","oauth","security","type-checking"],"install":[{"cmd":"pip install types-oauthlib","lang":"bash","label":"Install types-oauthlib"}],"dependencies":[{"reason":"Provides type hints for the `oauthlib` runtime library.","package":"oauthlib","optional":false}],"imports":[{"note":"Common client for OAuth 2.0 authorization code flow.","symbol":"WebApplicationClient","correct":"from oauthlib.oauth2 import WebApplicationClient"},{"note":"Common client for OAuth 1.0.","symbol":"Client","correct":"from oauthlib.oauth1 import Client"},{"note":"For implementing custom request validation on an OAuth 2.0 provider.","symbol":"Request","correct":"from oauthlib.oauth2.rfc6749.request_validator import RequestValidator"}],"quickstart":{"code":"import os\nfrom typing import Dict, Any\nfrom oauthlib.oauth2 import WebApplicationClient\n\n# --- Configuration (replace with your actual values) ---\nCLIENT_ID: str = os.environ.get('OAUTH_CLIENT_ID', 'your_client_id')\nAUTHORIZATION_BASE_URL: str = os.environ.get('OAUTH_AUTH_URL', 'https://example.com/oauth/authorize')\nREDIRECT_URI: str = os.environ.get('OAUTH_REDIRECT_URI', 'https://example.com/callback')\n\n# 1. Create a client instance\nclient: WebApplicationClient = WebApplicationClient(CLIENT_ID)\n\n# 2. Prepare the authorization request URL\nscope: str = \"read write profile\"\nrequest_uri: str = client.prepare_request_uri(\n    AUTHORIZATION_BASE_URL,\n    redirect_uri=REDIRECT_URI,\n    scope=scope\n)\n\nprint(f\"Visit this URL to authorize: {request_uri}\")\n\n# Simulate receiving an authorization response from the OAuth provider\n# In a real web application, this URL would be received by your REDIRECT_URI endpoint\nsimulated_auth_response_url: str = f\"{REDIRECT_URI}?code=AUTHORIZATION_CODE_EXAMPLE&state=STATE_EXAMPLE\"\n\n# 3. Parse the authorization response for the code\n# The state parameter is crucial for CSRF protection and should be validated against a stored value.\nresponse_params: Dict[str, Any] = client.parse_request_uri(\n    uri=simulated_auth_response_url,\n    state='STATE_EXAMPLE' # This should match the state generated in prepare_request_uri and stored in session/database\n)\n\nauth_code: str = response_params['code']\nprint(f\"Successfully received authorization code: {auth_code}\")\n\n# Further steps would involve exchanging the code for an access token\n# using client.prepare_token_request and sending it to the token endpoint.","lang":"python","description":"This quickstart demonstrates how to use `oauthlib` with `types-oauthlib` for static type checking. It illustrates the initial steps of an OAuth 2.0 Authorization Code flow: initializing a `WebApplicationClient` and preparing/parsing an authorization request URI. The type hints provided by `types-oauthlib` ensure that methods and their arguments are used correctly."},"warnings":[{"fix":"Understand that stub packages are for type checking only. Any runtime issues reside in the `oauthlib` library itself.","message":"The primary purpose of `types-oauthlib` is to provide static type hints for `oauthlib`. It does not add runtime functionality, fix bugs in `oauthlib`, or alter its behavior. Expecting it to resolve runtime issues is a common misunderstanding.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Aim to keep `types-oauthlib` and `oauthlib` in sync (e.g., `oauthlib==3.3.*` with `types-oauthlib==3.3.0.*`). Consult the `types-oauthlib` PyPI page for the `oauthlib` version it targets.","message":"For `types-oauthlib` to be effective, its version should ideally align with the major and minor versions of the `oauthlib` library you are using. Mismatched versions can lead to incorrect type checking results or errors, as API signatures might differ between versions.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always consult the `oauthlib` changelog (e.g., on GitHub or Read the Docs) when planning major upgrades to understand API changes and migration paths.","message":"`oauthlib` has undergone significant API changes across major versions (e.g., 0.x to 1.x, 2.x to 3.x). While `types-oauthlib` will reflect the types for the targeted `oauthlib` version, upgrading `oauthlib` itself can introduce runtime breaking changes that will manifest as type checking errors.","severity":"breaking","affected_versions":"Upgrading `oauthlib` across major versions."},{"fix":"Only use `OAUTHLIB_INSECURE_TRANSPORT` in controlled development environments. Ensure HTTPS is always used in production.","message":"Using the `OAUTHLIB_INSECURE_TRANSPORT` environment variable disables critical security checks (like requiring HTTPS) in `oauthlib`. While useful for local development, *never* use this in production environments as it exposes your application to severe security vulnerabilities.","severity":"gotcha","affected_versions":"All versions of `oauthlib` (and thus code type-checked by `types-oauthlib`)."}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}