0
# OAuth2
1
2
A comprehensive Python library for OAuth 1.0 authentication that provides consumer management, token handling, request signing, HTTP client functionality, and server-side verification. This library is fully compatible with Python 2.6, 2.7, 3.3, and 3.4, offering a clean API design that extends beyond basic OAuth to include specialized clients for SMTP and IMAP protocols.
3
4
## Package Information
5
6
- **Package Name**: oauth2
7
- **Language**: Python
8
- **Installation**: `pip install oauth2`
9
- **Dependencies**: httplib2
10
11
## Core Imports
12
13
```python
14
import oauth2
15
```
16
17
Common patterns:
18
19
```python
20
from oauth2 import Consumer, Token, Request, Client, Server
21
from oauth2 import SignatureMethod_HMAC_SHA1, SignatureMethod_PLAINTEXT
22
```
23
24
For protocol-specific clients:
25
26
```python
27
from oauth2.clients.imap import IMAP4_SSL
28
from oauth2.clients.smtp import SMTP
29
```
30
31
## Basic Usage
32
33
```python
34
import oauth2
35
36
# 1. Create consumer with your app credentials
37
consumer = oauth2.Consumer(
38
key="your_consumer_key",
39
secret="your_consumer_secret"
40
)
41
42
# 2. Create access token (obtained from OAuth flow)
43
token = oauth2.Token(
44
key="user_access_token",
45
secret="user_access_token_secret"
46
)
47
48
# 3. Make authenticated HTTP requests
49
client = oauth2.Client(consumer, token)
50
response, content = client.request(
51
uri="https://api.example.com/protected_resource",
52
method="GET"
53
)
54
55
# 4. Or manually sign requests
56
request = oauth2.Request.from_consumer_and_token(
57
consumer=consumer,
58
token=token,
59
http_method="GET",
60
http_url="https://api.example.com/protected_resource"
61
)
62
63
# Sign with HMAC-SHA1 (default)
64
signature_method = oauth2.SignatureMethod_HMAC_SHA1()
65
request.sign_request(signature_method, consumer, token)
66
67
# Get signed authorization header
68
auth_header = request.to_header()
69
```
70
71
## Architecture
72
73
The library follows a modular design with distinct responsibilities:
74
75
- **Consumer/Token**: Credential management and OAuth parameter handling
76
- **Request**: Parameter collection, normalization, and signing coordination
77
- **Signature Methods**: Pluggable signing algorithms (HMAC-SHA1, PLAINTEXT)
78
- **Client**: HTTP wrapper with automatic request signing via httplib2
79
- **Server**: Request verification for service providers
80
- **Protocol Extensions**: Specialized clients for SMTP/IMAP with XOAUTH support
81
82
## Capabilities
83
84
### Core OAuth Operations
85
86
Essential OAuth 1.0 functionality including consumer and token management, request construction, parameter normalization, and signature generation using HMAC-SHA1 or PLAINTEXT methods.
87
88
```python { .api }
89
class Consumer:
90
def __init__(self, key: str, secret: str): ...
91
92
class Token:
93
def __init__(self, key: str, secret: str): ...
94
def set_callback(self, callback: str): ...
95
def set_verifier(self, verifier: str = None): ...
96
97
class Request(dict):
98
def __init__(self, method: str = 'GET', url: str = None, parameters: dict = None, body: bytes = b'', is_form_encoded: bool = False): ...
99
def sign_request(self, signature_method, consumer, token): ...
100
```
101
102
[Core OAuth Operations](./oauth-core.md)
103
104
### HTTP Client
105
106
Automated OAuth-enabled HTTP client that extends httplib2 to handle request signing transparently, supporting all HTTP methods with proper OAuth authorization headers.
107
108
```python { .api }
109
class Client:
110
def __init__(self, consumer, token=None, **kwargs): ...
111
def request(self, uri: str, method: str = "GET", body: bytes = b'', headers: dict = None) -> tuple: ...
112
```
113
114
[HTTP Client](./http-client.md)
115
116
### Server Verification
117
118
Server-side OAuth request verification for service providers, including signature validation, timestamp checking, and parameter extraction with support for multiple signature methods.
119
120
```python { .api }
121
class Server:
122
def __init__(self, signature_methods: dict = None): ...
123
def verify_request(self, request, consumer, token) -> dict: ...
124
def add_signature_method(self, signature_method): ...
125
```
126
127
[Server Verification](./server-verification.md)
128
129
### Client Extensions
130
131
Protocol-specific OAuth clients for SMTP and IMAP that provide XOAUTH authentication support, extending standard Python email clients with OAuth capabilities.
132
133
```python { .api }
134
class IMAP4_SSL:
135
def authenticate(self, url: str, consumer, token): ...
136
137
class SMTP:
138
def authenticate(self, url: str, consumer, token): ...
139
```
140
141
[Client Extensions](./client-extensions.md)
142
143
## Exception Handling
144
145
```python { .api }
146
class Error(RuntimeError):
147
def __init__(self, message: str = 'OAuth error occurred.'): ...
148
149
class MissingSignature(Error):
150
pass
151
```
152
153
Common exceptions include signature validation failures, missing required parameters, expired timestamps, and invalid consumer/token credentials.
154
155
## Constants and Version Information
156
157
```python { .api }
158
OAUTH_VERSION = '1.0' # OAuth protocol version
159
HTTP_METHOD = 'GET' # Default HTTP method
160
SIGNATURE_METHOD = 'PLAINTEXT' # Default signature method
161
162
__version__ # Package version information
163
```
164
165
## String Handling Utilities
166
167
```python { .api }
168
def to_unicode(s) -> str:
169
"""Convert string to unicode, handling encoding properly."""
170
171
def to_utf8(s) -> bytes:
172
"""Convert string to UTF-8 bytes."""
173
174
def to_unicode_if_string(s):
175
"""Convert to unicode if string, otherwise return unchanged."""
176
177
def to_utf8_if_string(s):
178
"""Convert to UTF-8 if string, otherwise return unchanged."""
179
```