requests-oauthlib

In practice, requests-oauthlib does exactly what you need: it handles OAuth 1.0a and OAuth 2.0 flows with minimal boilerplate. The OAuth2Session class is particularly well-designed, automatically refreshing tokens and managing state parameters. I've used it extensively for integrations with Google, GitHub, and custom OAuth providers without major issues.

From a security perspective, it gets the fundamentals right. Token storage is your responsibility (which is good—it doesn't make assumptions), PKCE is supported for OAuth 2.0, and it properly validates redirect URIs. The library leverages oauthlib under the hood, which has decent CVE response history. However, error messages can leak token details in stack traces if you're not careful with logging configuration, and the documentation could be clearer about secure token persistence patterns.

The main pain point is session management across token refreshes. You need to explicitly handle token updates in callbacks, and there's no built-in encrypted storage. The compliance fixes for provider quirks are helpful but feel bolted-on. Overall, it's the de facto standard for OAuth in Python's requests ecosystem and does the job reliably.

In production, requests-oauthlib delivers what it promises: clean OAuth 1.0/2.0 integration with the familiar requests API. The OAuth2Session object handles token management transparently, and you can pass it anywhere expecting a requests.Session, which is fantastic for connection pooling. The library properly inherits requests' timeout behavior, though you still need to set timeouts explicitly—there are no magical defaults.

The gotchas emerge around token refresh mechanics. Automatic token refresh works but requires careful setup of the token update callback; miss this and you'll silently lose refreshed tokens. Error handling during refresh is adequate but could be more granular—you get generic OAuth2Error exceptions that require digging into response bodies. Under load, be mindful that token refresh isn't thread-safe out of the box; you'll need external locking if multiple threads share a session.

Observability is basic—no built-in hooks for metrics or structured logging. You'll need to wrap calls or monkey-patch for detailed observability. The 2.0.0 release dropped Python 2 support cleanly, but check your oauthlib dependency version as mismatches cause cryptic signature errors.

Using requests-oauthlib day-to-day is generally straightforward once you understand OAuth flows. The library wraps the lower-level OAuthlib with the familiar Requests interface, which feels natural if you're already using Requests. OAuth1Session and OAuth2Session classes handle most common scenarios - I've integrated with Twitter, GitHub, and various enterprise OAuth providers without major issues.

The documentation covers the basic flows adequately with working examples, though you'll often need to reference both this library's docs and OAuthlib's to understand what's happening under the hood. The getting-started examples for OAuth1 and OAuth2 are copy-pasteable and work as advertised, which is appreciated.

The main pain points are Python's lack of comprehensive type hints (you'll be guessing parameter types frequently) and cryptic error messages when token exchange fails. Debugging OAuth issues often requires diving into the source code since exceptions don't always clearly indicate whether the problem is with your config, the provider's response, or network issues. Still, for most OAuth integrations, this is the de facto choice in the Python ecosystem.