0
# Service Client
1

2
Core REST client functionality providing HTTP request creation, pipeline processing, URL formatting, streaming support, and context management. The ServiceClient class is the primary interface for sending HTTP requests through the msrest pipeline system.
3

4
## Capabilities
5

6
### Client Creation
7

8
Create service clients with configuration and optional credentials for REST API communication.
9

10
```python { .api }
11
class ServiceClient:
12
    def __init__(self, creds, config: Configuration):
13
        """
14
        Initialize REST service client.
15
        
16
        Parameters:
17
        - creds: Authentication credentials (deprecated, use config.credentials)
18
        - config: Service configuration object
19
        """
20

21
class SDKClient:
22
    def __init__(self, creds, config: Configuration):
23
        """
24
        Base class for all generated SDK clients.
25
        
26
        Parameters:
27
        - creds: Authentication credentials
28
        - config: Service configuration object
29
        """
30
    
31
    def close(self):
32
        """Close the client if keep_alive is True."""
33
```
34

35
### HTTP Request Methods
36

37
Create HTTP requests for different HTTP verbs with parameters, headers, and body content.
38

39
```python { .api }
40
def get(self, url: str, params=None, headers=None, content=None, form_content=None):
41
    """
42
    Create a GET request object.
43
    
44
    Parameters:
45
    - url: The request URL
46
    - params: URL query parameters dict
47
    - headers: HTTP headers dict
48
    - content: Request body content
49
    - form_content: Form data dict
50
    
51
    Returns:
52
    ClientRequest object
53
    """
54

55
def post(self, url: str, params=None, headers=None, content=None, form_content=None):
56
    """
57
    Create a POST request object.
58
    
59
    Parameters:
60
    - url: The request URL
61
    - params: URL query parameters dict
62
    - headers: HTTP headers dict
63
    - content: Request body content
64
    - form_content: Form data dict
65
    
66
    Returns:
67
    ClientRequest object
68
    """
69

70
def put(self, url: str, params=None, headers=None, content=None, form_content=None):
71
    """Create a PUT request object."""
72

73
def patch(self, url: str, params=None, headers=None, content=None, form_content=None):
74
    """Create a PATCH request object."""
75

76
def delete(self, url: str, params=None, headers=None, content=None, form_content=None):
77
    """Create a DELETE request object."""
78

79
def head(self, url: str, params=None, headers=None, content=None, form_content=None):
80
    """Create a HEAD request object."""
81

82
def merge(self, url: str, params=None, headers=None, content=None, form_content=None):
83
    """Create a MERGE request object."""
84
```
85

86
### Request Sending
87

88
Send prepared requests through the configured pipeline with response handling.
89

90
```python { .api }
91
def send(self, request, headers=None, content=None, **kwargs):
92
    """
93
    Send request object according to configuration.
94
    
95
    Parameters:
96
    - request: ClientRequest object to send
97
    - headers: Additional headers dict (deprecated)
98
    - content: Additional body content (deprecated)
99
    - kwargs: Additional configuration overrides
100
    
101
    Returns:
102
    HTTP response object
103
    """
104

105
def send_formdata(self, request, headers=None, content=None, **config):
106
    """
107
    Send data as multipart form-data request (deprecated).
108
    
109
    Parameters:
110
    - request: ClientRequest object
111
    - headers: Additional headers
112
    - content: Form data dict
113
    - config: Configuration overrides
114
    """
115
```
116

117
### URL Formatting
118

119
Format request URLs with the client base URL and parameter substitution.
120

121
```python { .api }
122
def format_url(self, url: str, **kwargs) -> str:
123
    """
124
    Format request URL with client base URL.
125
    
126
    Parameters:
127
    - url: Request URL to format
128
    - kwargs: URL template parameters
129
    
130
    Returns:
131
    Formatted absolute URL string
132
    """
133
```
134

135
### Streaming Support
136

137
Handle streaming uploads and downloads for large data transfers.
138

139
```python { .api }
140
def stream_upload(self, data, callback):
141
    """
142
    Generator for streaming request body data.
143
    
144
    Parameters:
145
    - data: File-like object to stream
146
    - callback: Progress monitoring callback
147
    
148
    Yields:
149
    Data chunks for upload
150
    """
151

152
def stream_download(self, data, callback):
153
    """
154
    Generator for streaming response body data.
155
    
156
    Parameters:
157
    - data: Response object to stream
158
    - callback: Progress monitoring callback
159
    
160
    Returns:
161
    Iterator of response data chunks
162
    """
163
```
164

165
### Context Management
166

167
Support for using service clients as context managers for automatic resource cleanup.
168

169
```python { .api }
170
def __enter__(self):
171
    """Enter context manager, enable keep_alive."""
172

173
def __exit__(self, *exc_details):
174
    """Exit context manager, disable keep_alive."""
175

176
def close(self):
177
    """Close the pipeline if keep_alive is True."""
178
```
179

180
### Header Management
181

182
Add persistent headers that apply to all requests (deprecated method).
183

184
```python { .api }
185
def add_header(self, header: str, value: str):
186
    """
187
    Add persistent header (deprecated).
188
    Use config.headers instead.
189
    
190
    Parameters:
191
    - header: Header name
192
    - value: Header value
193
    """
194
```
195

196
## Usage Examples
197

198
### Basic Client Usage
199

200
```python
201
from msrest import ServiceClient, Configuration
202

203
# Create configuration
204
config = Configuration(base_url='https://api.example.com')
205

206
# Create and use client
207
with ServiceClient(None, config) as client:
208
    # Create GET request
209
    request = client.get('/users', params={'limit': 10})
210
    
211
    # Send request
212
    response = client.send(request)
213
    
214
    # Process response
215
    print(f"Status: {response.status_code}")
216
    print(f"Data: {response.text}")
217
```
218

219
### POST Request with JSON Body
220

221
```python
222
import json
223
from msrest import ServiceClient, Configuration
224

225
config = Configuration(base_url='https://api.example.com')
226

227
with ServiceClient(None, config) as client:
228
    # Prepare JSON data
229
    data = {'name': 'John Doe', 'email': 'john@example.com'}
230
    json_data = json.dumps(data)
231
    
232
    # Create POST request
233
    request = client.post('/users', 
234
                         content=json_data,
235
                         headers={'Content-Type': 'application/json'})
236
    
237
    # Send request
238
    response = client.send(request)
239
    print(f"Created user: {response.status_code}")
240
```
241

242
### Streaming Upload
243

244
```python
245
from msrest import ServiceClient, Configuration
246

247
config = Configuration(base_url='https://api.example.com')
248

249
with ServiceClient(None, config) as client:
250
    # Define progress callback
251
    def progress_callback(chunk, response=None):
252
        print(f"Uploaded {len(chunk)} bytes")
253
    
254
    # Stream file upload
255
    with open('large_file.dat', 'rb') as f:
256
        for chunk in client.stream_upload(f, progress_callback):
257
            # Chunks are yielded for upload
258
            pass
259
```
260

261
## Types
262

263
```python { .api }
264
class ClientRequest:
265
    """Universal HTTP request abstraction."""
266
    method: str
267
    url: str
268
    headers: dict
269
    data: any
270
    files: dict
271
```