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
```