0
# MSRest
1

2
Microsoft AutoRest Swagger generator Python client runtime that provides comprehensive support for building REST API clients from OpenAPI/Swagger specifications. It offers serialization and deserialization capabilities, authentication mechanisms, paging support for large result sets, long-running operation (LRO) polling with retry strategies, and comprehensive error handling with configurable HTTP pipelines.
3

4
## Package Information
5

6
- **Package Name**: msrest
7
- **Language**: Python
8
- **Installation**: `pip install msrest`
9

10
## Core Imports
11

12
```python
13
from msrest import ServiceClient, Configuration
14
from msrest import Serializer, Deserializer
15
```
16

17
For authentication:
18

19
```python
20
from msrest.authentication import BasicAuthentication, ApiKeyCredentials
21
```
22

23
For version information:
24

25
```python
26
from msrest import __version__
27
print(__version__)  # "0.7.1"
28

29
# Alternative access
30
import msrest
31
print(msrest.__version__)  # "0.7.1"
32
```
33

34
## Basic Usage
35

36
```python
37
from msrest import ServiceClient, Configuration
38
from msrest.authentication import BasicAuthentication
39

40
# Configure client
41
config = Configuration(base_url='https://api.example.com')
42
auth = BasicAuthentication('username', 'password')
43
config.credentials = auth
44

45
# Create service client
46
with ServiceClient(None, config) as client:
47
    # Create and send HTTP request
48
    request = client.get('/users')
49
    response = client.send(request)
50
    
51
    # Process response
52
    print(response.status_code)
53
    print(response.text)
54
```
55

56
## Architecture
57

58
MSRest implements a layered architecture designed for maximum reusability across Azure SDK clients and other REST API consumers:
59

60
- **Service Client Layer**: High-level client interface with HTTP verb methods (GET, POST, etc.)
61
- **Pipeline System**: Configurable request/response processing with policies for authentication, logging, and custom behavior
62
- **Universal HTTP Layer**: Abstraction over HTTP libraries (requests, aiohttp) enabling both sync and async operations
63
- **Serialization Layer**: Handles conversion between Python objects and REST API formats (JSON/XML)
64
- **Authentication Layer**: Pluggable authentication mechanisms supporting OAuth, API keys, basic auth, and custom schemes
65

66
This design enables easy customization while maintaining compatibility across different API requirements and provides built-in support for Azure service patterns like long-running operations and result paging.
67

68
## Capabilities
69

70
### Service Client
71

72
Core REST client functionality providing HTTP request creation, pipeline processing, URL formatting, streaming support, and context management for session lifecycle.
73

74
```python { .api }
75
class ServiceClient:
76
    def __init__(self, creds, config: Configuration): ...
77
    def get(self, url: str, params=None, headers=None, content=None, form_content=None): ...
78
    def post(self, url: str, params=None, headers=None, content=None, form_content=None): ...
79
    def put(self, url: str, params=None, headers=None, content=None, form_content=None): ...
80
    def delete(self, url: str, params=None, headers=None, content=None, form_content=None): ...
81
    def send(self, request, headers=None, content=None, **kwargs): ...
82
```
83

84
[Service Client](./service-client.md)
85

86
### Configuration
87

88
Client configuration management including base URL settings, authentication credentials, HTTP policies, pipeline configuration, and connection parameters.
89

90
```python { .api }
91
class Configuration:
92
    def __init__(self, base_url: str, filepath=None): ...
93
    def add_user_agent(self, value: str): ...
94
    @property
95
    def user_agent(self) -> str: ...
96
    @property
97
    def enable_http_logger(self) -> bool: ...
98
```
99

100
[Configuration](./configuration.md)
101

102
### Authentication
103

104
Comprehensive authentication system supporting multiple authentication schemes including Basic, Bearer token, OAuth2, API keys, Kerberos, and Azure service-specific credentials.
105

106
```python { .api }
107
class Authentication:
108
    def signed_session(self, session=None): ...
109

110
class BasicAuthentication(Authentication):
111
    def __init__(self, username: str, password: str): ...
112

113
class ApiKeyCredentials(Authentication):
114
    def __init__(self, in_headers=None, in_query=None): ...
115
```
116

117
[Authentication](./authentication.md)
118

119
### Serialization
120

121
Robust serialization and deserialization system supporting complex data types, XML/JSON formats, date/time handling, custom model classes, and comprehensive validation.
122

123
```python { .api }
124
class Serializer:
125
    def __init__(self, classes=None): ...
126
    def body(self, data, data_type: str, **kwargs): ...
127
    def url(self, name: str, data, data_type: str, **kwargs) -> str: ...
128
    def query(self, name: str, data, data_type: str, **kwargs) -> str: ...
129

130
class Deserializer:
131
    def __init__(self, classes=None): ...
132
    def __call__(self, target_obj: str, response_data, content_type=None): ...
133
```
134

135
[Serialization](./serialization.md)
136

137
### Paging
138

139
Iterator-based paging support for REST APIs that return large result sets, providing automatic page traversal, reset capability, and raw response access.
140

141
```python { .api }
142
class Paged:
143
    def __init__(self, command, classes, raw_headers=None, **kwargs): ...
144
    def advance_page(self): ...
145
    def reset(self): ...
146
    def get(self, url: str): ...
147
    @property
148
    def raw(self): ...
149
```
150

151
[Paging](./paging.md)
152

153
### Long-Running Operations
154

155
Polling system for long-running operations with configurable retry strategies, timeout handling, and completion detection for Azure ARM and other async API patterns.
156

157
```python { .api }
158
class LROPoller:
159
    def result(self, timeout=None): ...
160
    def wait(self, timeout=None): ...
161
    def done(self) -> bool: ...
162
    def add_done_callback(self, func): ...
163

164
class PollingMethod:
165
    def initialize(self, client, initial_response, deserialization_callback): ...
166
    def run(self) -> bool: ...
167
```
168

169
[Long-Running Operations](./polling.md)
170

171
### Pipeline System
172

173
Configurable HTTP request/response pipeline with policy-based architecture supporting custom middleware, authentication injection, logging, and retry logic.
174

175
```python { .api }
176
class Pipeline:
177
    def __init__(self, policies=None, sender=None): ...
178
    def run(self, request, **kwargs): ...
179

180
class HTTPPolicy:
181
    def send(self, request, **kwargs): ...
182

183
class SansIOHTTPPolicy:
184
    def on_request(self, request, **kwargs): ...
185
    def on_response(self, request, response, **kwargs): ...
186
```
187

188
[Pipeline System](./pipeline.md)
189

190
### Exception Handling
191

192
Comprehensive error handling with specialized exception types for validation errors, HTTP operation failures, authentication issues, and client request problems.
193

194
```python { .api }
195
class ClientException(Exception): ...
196
class ValidationError(ClientException): ...
197
class HttpOperationError(ClientException): ...
198
class AuthenticationError(ClientException): ...
199
class TokenExpiredError(ClientException): ...
200
```
201

202
[Exception Handling](./exceptions.md)
203

204
## Types
205

206
Core type definitions used across the MSRest API.
207

208
```python { .api }
209
class SDKClient:
210
    def __init__(self, creds, config: Configuration): ...
211
    def close(self): ...
212

213
# Model class from msrest.serialization
214
class Model:
215
    def validate(self): ...
216
    def serialize(self, keep_readonly=False, **kwargs): ...
217
    def as_dict(self, keep_readonly=True, key_transformer=None, **kwargs): ...
218
    @classmethod
219
    def deserialize(cls, data, content_type=None): ...
220
    @classmethod
221
    def from_dict(cls, data, key_extractors=None, content_type=None): ...
222

223
# Version information
224
__version__: str  # Package version string (e.g., "0.7.1")
225
msrest_version: str  # Alias for __version__
226
```