0
# Client Connection
1

2
The Connection class provides a high-level interface to Swift with automatic authentication, connection pooling, retry logic, and convenient wrapper methods for all Swift operations.
3

4
## Capabilities
5

6
### Connection Initialization
7

8
Create a connection with comprehensive authentication options, retry configuration, and SSL settings.
9

10
```python { .api }
11
class Connection:
12
    def __init__(
13
        self,
14
        authurl=None,
15
        user=None,
16
        key=None,
17
        retries=5,
18
        preauthurl=None,
19
        preauthtoken=None,
20
        snet=False,
21
        starting_backoff=1,
22
        max_backoff=64,
23
        tenant_name=None,
24
        os_options=None,
25
        auth_version="1",
26
        cacert=None,
27
        insecure=False,
28
        cert=None,
29
        cert_key=None,
30
        ssl_compression=True,
31
        retry_on_ratelimit=True,
32
        timeout=None,
33
        session=None,
34
        force_auth_retry=False
35
    ):
36
        """
37
        Initialize Swift connection with authentication and configuration options.
38

39
        Parameters:
40
        - authurl: str, authentication URL
41
        - user: str, username to authenticate as
42
        - key: str, key/password to authenticate with
43
        - retries: int, number of times to retry requests before failing (default 5)
44
        - preauthurl: str, storage URL if already authenticated
45
        - preauthtoken: str, authentication token if already authenticated
46
        - snet: bool, use SERVICENET internal network (default False)
47
        - starting_backoff: int, initial delay between retries in seconds (default 1)
48
        - max_backoff: int, maximum delay between retries in seconds (default 64)
49
        - tenant_name: str, tenant/account name for auth 2.0+ systems
50
        - os_options: dict, OpenStack options (tenant_id, auth_token, service_type, etc.)
51
        - auth_version: str, OpenStack auth version ('1', '2.0', '3', default '1')
52
        - cacert: str, CA bundle file for TLS server certificate verification
53
        - insecure: bool, allow access without checking SSL certs (default False)
54
        - cert: str, client certificate file for SSL client certificate authentication
55
        - cert_key: str, client certificate private key file
56
        - ssl_compression: bool, enable SSL compression (default True)
57
        - retry_on_ratelimit: bool, retry ratelimited connections after backoff (default True)
58
        - timeout: float, socket read timeout passed to requests library
59
        - session: keystoneauth1.session.Session object for authentication
60
        - force_auth_retry: bool, reset auth info on unexpected errors (default False)
61
        """
62
```
63

64
#### Usage Examples
65

66
```python
67
# Basic v1 authentication
68
conn = Connection(
69
    authurl='http://swift.example.com/auth/v1.0',
70
    user='tenant:username',
71
    key='password'
72
)
73

74
# Keystone v3 authentication
75
conn = Connection(
76
    authurl='https://identity.example.com:5000/v3',
77
    user='myuser',
78
    key='mypassword',
79
    auth_version='3',
80
    os_options={
81
        'project_name': 'myproject',
82
        'user_domain_name': 'mydomain',
83
        'project_domain_name': 'mydomain',
84
    }
85
)
86

87
# Pre-authenticated connection
88
conn = Connection(
89
    preauthurl='https://swift.example.com/v1/AUTH_account',
90
    preauthtoken='existing_auth_token'
91
)
92

93
# SSL configuration
94
conn = Connection(
95
    authurl='https://identity.example.com:5000/v3',
96
    user='myuser',
97
    key='mypassword',
98
    auth_version='3',
99
    cacert='/path/to/ca-bundle.crt',
100
    cert='/path/to/client.crt',
101
    cert_key='/path/to/client.key',
102
    insecure=False
103
)
104
```
105

106
### Account Operations
107

108
Retrieve account metadata and container listings with optional filtering and pagination.
109

110
```python { .api }
111
def head_account(self, headers=None):
112
    """
113
    Get account metadata.
114

115
    Parameters:
116
    - headers: dict, additional headers to include in request
117

118
    Returns:
119
    dict: account metadata headers (all lowercase keys)
120
    """
121

122
def get_account(
123
    self,
124
    marker=None,
125
    limit=None,
126
    prefix=None,
127
    end_marker=None,
128
    full_listing=False,
129
    headers=None,
130
    delimiter=None
131
):
132
    """
133
    Get account container listing.
134

135
    Parameters:
136
    - marker: str, start listing after this container name
137
    - limit: int, maximum number of containers to return
138
    - prefix: str, only list containers beginning with this prefix
139
    - end_marker: str, stop listing before this container name
140
    - full_listing: bool, return complete listing (may require multiple requests)
141
    - headers: dict, additional headers to include in request
142
    - delimiter: str, delimiter for hierarchical container names
143

144
    Returns:
145
    tuple: (response_headers dict, containers list)
146
    """
147

148
def post_account(self, headers, response_dict=None, query_string=None, data=None):
149
    """
150
    Update account metadata.
151

152
    Parameters:
153
    - headers: dict, headers to set as account metadata
154
    - response_dict: dict, optional dict to store response info
155
    - query_string: str, optional query string to append to request
156
    - data: bytes, optional data to include in request body
157

158
    Returns:
159
    tuple: (response_headers dict, response_body bytes)
160
    """
161
```
162

163
### Container Operations
164

165
Complete container management including creation, metadata operations, object listings, and deletion.
166

167
```python { .api }
168
def head_container(self, container, headers=None):
169
    """
170
    Get container metadata.
171

172
    Parameters:
173
    - container: str, container name
174
    - headers: dict, additional headers to include in request
175

176
    Returns:
177
    dict: container metadata headers (all lowercase keys)
178
    """
179

180
def get_container(
181
    self,
182
    container,
183
    marker=None,
184
    limit=None,
185
    prefix=None,
186
    delimiter=None,
187
    end_marker=None,
188
    version_marker=None,
189
    path=None,
190
    full_listing=False,
191
    headers=None,
192
    query_string=None
193
):
194
    """
195
    Get container object listing.
196

197
    Parameters:
198
    - container: str, container name to list objects from
199
    - marker: str, start listing after this object name
200
    - limit: int, maximum number of objects to return
201
    - prefix: str, only list objects beginning with this prefix
202
    - delimiter: str, delimiter for hierarchical object names
203
    - end_marker: str, stop listing before this object name
204
    - version_marker: str, version marker for versioned objects
205
    - path: str, path query (equivalent to delimiter='/' and prefix=path/)
206
    - full_listing: bool, return complete listing (may require multiple requests)
207
    - headers: dict, additional headers to include in request
208
    - query_string: str, optional query string to append to request
209

210
    Returns:
211
    tuple: (response_headers dict, objects list)
212
    """
213

214
def put_container(self, container, headers=None, response_dict=None, query_string=None):
215
    """
216
    Create container.
217

218
    Parameters:
219
    - container: str, container name to create
220
    - headers: dict, additional headers to set on container
221
    - response_dict: dict, optional dict to store response info
222
    - query_string: str, optional query string to append to request
223
    """
224

225
def post_container(self, container, headers, response_dict=None):
226
    """
227
    Update container metadata.
228

229
    Parameters:
230
    - container: str, container name to update
231
    - headers: dict, headers to set as container metadata
232
    - response_dict: dict, optional dict to store response info
233
    """
234

235
def delete_container(self, container, response_dict=None, query_string=None, headers={}):
236
    """
237
    Delete container.
238

239
    Parameters:
240
    - container: str, container name to delete
241
    - response_dict: dict, optional dict to store response info
242
    - query_string: str, optional query string to append to request
243
    - headers: dict, additional headers to include in request
244
    """
245
```
246

247
### Object Operations
248

249
Full object lifecycle management with support for large objects, streaming, metadata, and efficient transfers.
250

251
```python { .api }
252
def head_object(self, container, obj, headers=None, query_string=None):
253
    """
254
    Get object metadata.
255

256
    Parameters:
257
    - container: str, container name containing the object
258
    - obj: str, object name to get metadata for
259
    - headers: dict, additional headers to include in request
260
    - query_string: str, optional query string to append to request
261

262
    Returns:
263
    dict: object metadata headers (all lowercase keys)
264
    """
265

266
def get_object(
267
    self,
268
    container,
269
    obj,
270
    resp_chunk_size=None,
271
    query_string=None,
272
    response_dict=None,
273
    headers=None
274
):
275
    """
276
    Download object.
277

278
    Parameters:
279
    - container: str, container name containing the object
280
    - obj: str, object name to download
281
    - resp_chunk_size: int, chunk size for reading response (enables streaming)
282
    - query_string: str, optional query string to append to request
283
    - response_dict: dict, optional dict to store response info
284
    - headers: dict, additional headers to include in request
285

286
    Returns:
287
    tuple: (response_headers dict, object_content bytes or iterable)
288
    """
289

290
def put_object(
291
    self,
292
    container,
293
    obj,
294
    contents,
295
    content_length=None,
296
    etag=None,
297
    chunk_size=None,
298
    content_type=None,
299
    headers=None,
300
    query_string=None,
301
    response_dict=None
302
):
303
    """
304
    Upload object.
305

306
    Parameters:
307
    - container: str, container name to upload object to
308
    - obj: str, object name to create/update
309
    - contents: str/bytes/file-like/iterable, object content to upload
310
    - content_length: int, content length (computed automatically if None)
311
    - etag: str, expected MD5 hash of content
312
    - chunk_size: int, chunk size for reading file-like contents (default 65536)
313
    - content_type: str, MIME type of content
314
    - headers: dict, additional headers to set on object
315
    - query_string: str, optional query string to append to request
316
    - response_dict: dict, optional dict to store response info
317

318
    Returns:
319
    str: MD5 hash (ETag) of uploaded content
320
    """
321

322
def post_object(self, container, obj, headers, response_dict=None):
323
    """
324
    Update object metadata.
325

326
    Parameters:
327
    - container: str, container name containing the object
328
    - obj: str, object name to update
329
    - headers: dict, headers to set as object metadata
330
    - response_dict: dict, optional dict to store response info
331
    """
332

333
def copy_object(
334
    self,
335
    container,
336
    obj,
337
    destination=None,
338
    headers=None,
339
    fresh_metadata=None,
340
    response_dict=None
341
):
342
    """
343
    Copy object.
344

345
    Parameters:
346
    - container: str, source container name
347
    - obj: str, source object name
348
    - destination: str, destination in format "/container/object" (None for same location)
349
    - headers: dict, additional headers for copy request
350
    - fresh_metadata: bool, omit existing metadata (None/False preserves metadata)
351
    - response_dict: dict, optional dict to store response info
352
    """
353

354
def delete_object(
355
    self,
356
    container,
357
    obj,
358
    query_string=None,
359
    response_dict=None,
360
    headers=None
361
):
362
    """
363
    Delete object.
364

365
    Parameters:
366
    - container: str, container name containing the object
367
    - obj: str, object name to delete
368
    - query_string: str, optional query string to append to request
369
    - response_dict: dict, optional dict to store response info
370
    - headers: dict, additional headers to include in request
371
    """
372
```
373

374
### Connection Management
375

376
```python { .api }
377
def close(self):
378
    """
379
    Close the connection and clean up resources.
380
    """
381

382
def get_capabilities(self, url=None):
383
    """
384
    Get cluster capability information.
385

386
    Parameters:
387
    - url: str, optional URL to query capabilities from
388

389
    Returns:
390
    dict: cluster capabilities and configuration
391
    """
392
```
393

394
## Usage Examples
395

396
### Basic Operations
397

398
```python
399
from swiftclient import Connection
400

401
conn = Connection(
402
    authurl='https://identity.example.com:5000/v3',
403
    user='myuser',
404
    key='mypassword',
405
    auth_version='3',
406
    os_options={'project_name': 'myproject'}
407
)
408

409
# Account operations
410
account_headers = conn.head_account()
411
print(f"Account has {account_headers['x-account-container-count']} containers")
412

413
headers, containers = conn.get_account()
414
for container in containers:
415
    print(f"Container: {container['name']}, Objects: {container['count']}")
416

417
# Container operations
418
conn.put_container('documents')
419
conn.put_container('images', headers={'X-Container-Read': '.r:*'})
420

421
headers, objects = conn.get_container('documents')
422
for obj in objects:
423
    print(f"Object: {obj['name']}, Size: {obj['bytes']}")
424

425
# Object operations
426
conn.put_object('documents', 'readme.txt', 'Hello, World!')
427
headers, content = conn.get_object('documents', 'readme.txt')
428
print(content.decode('utf-8'))
429

430
# Set object metadata
431
conn.post_object('documents', 'readme.txt', {'X-Object-Meta-Author': 'John Doe'})
432

433
# Copy object
434
conn.copy_object('documents', 'readme.txt', '/documents/readme-copy.txt')
435

436
# Cleanup
437
conn.delete_object('documents', 'readme.txt')
438
conn.delete_object('documents', 'readme-copy.txt')
439
conn.delete_container('documents')
440

441
conn.close()
442
```
443

444
### Large File Upload with Streaming
445

446
```python
447
import io
448

449
# Upload large file with streaming
450
large_data = io.BytesIO(b'x' * 10000000)  # 10MB of data
451
etag = conn.put_object(
452
    'documents',
453
    'large-file.dat',
454
    large_data,
455
    content_length=10000000,
456
    chunk_size=65536
457
)
458
print(f"Uploaded with ETag: {etag}")
459

460
# Download with streaming
461
headers, content = conn.get_object('documents', 'large-file.dat', resp_chunk_size=65536)
462
total_bytes = 0
463
for chunk in content:
464
    total_bytes += len(chunk)
465
    print(f"Downloaded {total_bytes} bytes", end='\r')
466
print(f"\nTotal downloaded: {total_bytes} bytes")
467
```