Install & Compatibility
Where this runs
tested against v3.3.0.20260724 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 18.2MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.6s · import 0.000s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
WebApplicationClient
✓ from oauthlib_stubs.oauth2 import WebApplicationClient
✗ from oauthlib-stubs.oauth2 import WebApplicationClient
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.
Debug
Known issues
gotchaThe 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.fixUnderstand that stub packages are for type checking only. Any runtime issues reside in the `oauthlib` library itself.
affects: All versions
gotchaFor `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.fixAim 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.
affects: All versions
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.fixAlways consult the `oauthlib` changelog (e.g., on GitHub or Read the Docs) when planning major upgrades to understand API changes and migration paths.
affects: Upgrading `oauthlib` across major versions.
gotchaUsing 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.fixOnly use `OAUTHLIB_INSECURE_TRANSPORT` in controlled development environments. Ensure HTTPS is always used in production.
affects: All versions of `oauthlib` (and thus code type-checked by `types-oauthlib`).
Upgrade
Version history
3.3.0.20260724latest on PyPI · released Jul 24, 2026
Audit
Dependencies
oauthlibrequiredProvides type hints for the `oauthlib` runtime library.