0
# Common Utilities
1

2
Shared utilities for parameter handling, token generation, URI validation, and cryptographic operations. Includes request/response handling and OAuth-specific data structures used across all OAuth implementations.
3

4
## Capabilities
5

6
### Request Object
7

8
Core request object representing HTTP requests with OAuth-specific attributes and parameter extraction capabilities.
9

10
```python { .api }
11
class Request:
12
    def __init__(
13
        self,
14
        uri: str,
15
        http_method: str = "GET",
16
        body: str | dict[str, str] | list[tuple[str, str]] | None = None,
17
        headers: dict[str, str] | None = None,
18
        encoding: str = "utf-8",
19
    ):
20
        """
21
        OAuth request object.
22
        
23
        Parameters:
24
        - uri: Request URI
25
        - http_method: HTTP method
26
        - body: Request body (various formats)
27
        - headers: Request headers
28
        - encoding: String encoding
29
        """
30
    
31
    @property
32
    def uri_query(self) -> str:
33
        """Query portion of URI."""
34
    
35
    @property
36
    def uri_query_params(self) -> list[tuple[str, str]]:
37
        """Parsed query parameters as list of tuples."""
38
    
39
    @property
40
    def duplicate_params(self) -> list[str]:
41
        """Parameter names that appear multiple times."""
42
    
43
    def __getattr__(self, name: str) -> str | None:
44
        """Get OAuth parameter values by name."""
45
```
46

47
### Parameter Utilities
48

49
Functions for parameter encoding, decoding, and manipulation in OAuth contexts.
50

51
```python { .api }
52
def quote(s: str | bytes, safe: bytes = b"/") -> str:
53
    """URL-encode string with OAuth-safe characters."""
54

55
def unquote(s: str | bytes) -> str:
56
    """URL-decode string."""
57

58
def urlencode(params: list[tuple[str | bytes, str | bytes]]) -> str:
59
    """Encode parameters as URL query string."""
60

61
def urldecode(query: str | bytes) -> list[tuple[str, str]]:
62
    """Decode URL query string to parameter list."""
63

64
def encode_params_utf8(params: list[tuple[str | bytes, str | bytes]]) -> list[tuple[bytes, bytes]]:
65
    """Encode parameters as UTF-8 bytes."""
66

67
def decode_params_utf8(params: list[tuple[str | bytes, str | bytes]]) -> list[tuple[str, str]]:
68
    """Decode UTF-8 parameters to strings."""
69

70
def extract_params(raw: str | bytes | dict[str, str] | list[tuple[str, str]]) -> list[tuple[str, str]] | None:
71
    """Extract parameters from various formats."""
72

73
def add_params_to_qs(query: str, params: dict[str, str] | list[tuple[str, str]]) -> str:
74
    """Add parameters to existing query string."""
75

76
def add_params_to_uri(uri: str, params: dict[str, str] | list[tuple[str, str]], fragment: bool = False) -> str:
77
    """Add parameters to URI query or fragment."""
78
```
79

80
### Token Generation
81

82
Cryptographically secure token and key generation functions.
83

84
```python { .api }
85
def generate_nonce() -> str:
86
    """Generate cryptographic nonce for OAuth requests."""
87

88
def generate_timestamp() -> str:
89
    """Generate OAuth timestamp (seconds since epoch)."""
90

91
def generate_token(length: int = 30, chars: str = ...) -> str:
92
    """Generate random token with specified length and character set."""
93

94
def generate_client_id(length: int = 30, chars: str = ...) -> str:
95
    """Generate client identifier."""
96

97
def generate_signed_token(private_pem: str, request: Request) -> str:
98
    """Generate signed JWT token using RSA private key."""
99

100
def verify_signed_token(public_pem: str, token: str) -> bool:
101
    """Verify signed JWT token using RSA public key."""
102
```
103

104
### String Utilities
105

106
Secure string handling and Unicode conversion functions.
107

108
```python { .api }
109
def safe_string_equals(a: str, b: str) -> bool:
110
    """Constant-time string comparison to prevent timing attacks."""
111

112
def to_unicode(data: str | bytes | dict, encoding: str = "UTF-8") -> str | dict:
113
    """Convert data to Unicode with proper encoding handling."""
114
```
115

116
### Case Insensitive Dictionary
117

118
Dictionary implementation for HTTP headers that ignores case.
119

120
```python { .api }
121
class CaseInsensitiveDict(dict[str, str]):
122
    def __init__(self, data: dict[str, str]) -> None: ...
123
    def __contains__(self, k: str) -> bool: ...
124
    def __getitem__(self, k: str) -> str: ...
125
    def get(self, k: str, default=None) -> str: ...
126
    def __setitem__(self, k: str, v: str) -> None: ...
127
    def update(self, *args, **kwargs) -> None: ...
128
```
129

130
## Usage Examples
131

132
```python
133
from oauthlib.common import Request, generate_token, safe_string_equals
134

135
# Create OAuth request
136
request = Request(
137
    'https://api.example.com/data?param=value',
138
    http_method='POST',
139
    body='data=test',
140
    headers={'Authorization': 'Bearer token123'}
141
)
142

143
# Access request properties
144
print(request.uri_query)  # 'param=value'
145
print(request.uri_query_params)  # [('param', 'value')]
146

147
# Generate secure tokens
148
client_id = generate_token(16)
149
access_token = generate_token(32)
150
nonce = generate_nonce()
151

152
# Secure string comparison
153
is_valid = safe_string_equals(provided_token, stored_token)
154
```