Typing stubs for oauthlib

Warnings

• gotcha 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.
  Fix: Understand that stub packages are for type checking only. Any runtime issues reside in the `oauthlib` library itself.
• gotcha 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.
  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.
• breaking `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.
  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.
• gotcha 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.
  Fix: Only use `OAUTHLIB_INSECURE_TRANSPORT` in controlled development environments. Ensure HTTPS is always used in production.

Install

• pip install types-oauthlib Install types-oauthlib

Imports

• WebApplicationClient

  from oauthlib.oauth2 import WebApplicationClient

  Common client for OAuth 2.0 authorization code flow.
• Client

  from oauthlib.oauth1 import Client

  Common client for OAuth 1.0.
• Request

  from oauthlib.oauth2.rfc6749.request_validator import RequestValidator

  For implementing custom request validation on an OAuth 2.0 provider.

Quickstart

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.

import os
from typing import Dict, Any
from oauthlib.oauth2 import WebApplicationClient

# --- Configuration (replace with your actual values) ---
CLIENT_ID: str = os.environ.get('OAUTH_CLIENT_ID', 'your_client_id')
AUTHORIZATION_BASE_URL: str = os.environ.get('OAUTH_AUTH_URL', 'https://example.com/oauth/authorize')
REDIRECT_URI: str = os.environ.get('OAUTH_REDIRECT_URI', 'https://example.com/callback')

# 1. Create a client instance
client: WebApplicationClient = WebApplicationClient(CLIENT_ID)

# 2. Prepare the authorization request URL
scope: str = "read write profile"
request_uri: str = client.prepare_request_uri(
    AUTHORIZATION_BASE_URL,
    redirect_uri=REDIRECT_URI,
    scope=scope
)

print(f"Visit this URL to authorize: {request_uri}")

# Simulate receiving an authorization response from the OAuth provider
# In a real web application, this URL would be received by your REDIRECT_URI endpoint
simulated_auth_response_url: str = f"{REDIRECT_URI}?code=AUTHORIZATION_CODE_EXAMPLE&state=STATE_EXAMPLE"

# 3. Parse the authorization response for the code
# The state parameter is crucial for CSRF protection and should be validated against a stored value.
response_params: Dict[str, Any] = client.parse_request_uri(
    uri=simulated_auth_response_url,
    state='STATE_EXAMPLE' # This should match the state generated in prepare_request_uri and stored in session/database
)

auth_code: str = response_params['code']
print(f"Successfully received authorization code: {auth_code}")

# Further steps would involve exchanging the code for an access token
# using client.prepare_token_request and sending it to the token endpoint.