0
# Python SwiftClient
1

2
A comprehensive Python client library for the OpenStack Swift Object Storage API, providing both a programmatic Python API and a command-line interface. It enables developers to interact with OpenStack Swift object storage services through a clean, well-documented interface that supports all core Swift operations including object upload/download, container management, metadata handling, and authentication.
3

4
## Package Information
5

6
- **Package Name**: python-swiftclient
7
- **Language**: Python
8
- **Installation**: `pip install python-swiftclient`
9
- **Python Requirements**: >= 3.7
10

11
## Core Imports
12

13
```python
14
import swiftclient
15
```
16

17
For high-level operations:
18

19
```python
20
from swiftclient import Connection
21
```
22

23
For bulk operations:
24

25
```python
26
from swiftclient.service import SwiftService
27
```
28

29
For low-level HTTP operations:
30

31
```python
32
from swiftclient import (
33
    get_auth, get_account, get_container, get_object,
34
    put_container, put_object, delete_object
35
)
36
```
37

38
## Basic Usage
39

40
### High-Level Connection API
41

42
```python
43
from swiftclient import Connection
44

45
# Create connection with authentication
46
conn = Connection(
47
    authurl='https://identity.example.com:5000/v3',
48
    user='myuser',
49
    key='mypassword',
50
    auth_version='3',
51
    os_options={
52
        'project_name': 'myproject',
53
        'user_domain_name': 'mydomain',
54
        'project_domain_name': 'mydomain',
55
    }
56
)
57

58
# Account operations
59
headers, containers = conn.get_account()
60

61
# Container operations
62
conn.put_container('mycontainer')
63
headers, objects = conn.get_container('mycontainer')
64

65
# Object operations
66
conn.put_object('mycontainer', 'myobject', 'Hello World!')
67
headers, content = conn.get_object('mycontainer', 'myobject')
68
print(content.decode('utf-8'))  # 'Hello World!'
69

70
# Cleanup
71
conn.delete_object('mycontainer', 'myobject')
72
conn.delete_container('mycontainer')
73
```
74

75
### Bulk Operations with SwiftService
76

77
```python
78
from swiftclient.service import SwiftService, SwiftUploadObject
79

80
# Upload multiple objects
81
with SwiftService() as swift:
82
    # Upload local files
83
    upload_objects = [
84
        SwiftUploadObject('path/to/file1.txt', object_name='file1.txt'),
85
        SwiftUploadObject('path/to/file2.txt', object_name='file2.txt')
86
    ]
87

88
    for result in swift.upload('mycontainer', upload_objects):
89
        if result['success']:
90
            print(f"Uploaded {result['object']}")
91
        else:
92
            print(f"Failed to upload {result['object']}: {result['error']}")
93
```
94

95
## Architecture
96

97
The python-swiftclient library provides multiple levels of abstraction for Swift operations:
98

99
- **Connection**: High-level client with automatic retry, authentication handling, and connection management
100
- **Low-level Functions**: Direct HTTP operations (get_object, put_object, etc.) for fine-grained control
101
- **SwiftService**: Bulk operations with multi-threading, progress reporting, and automatic retries
102
- **Command Line**: Full-featured CLI tool for all Swift operations
103

104
This multi-layered architecture allows developers to choose the appropriate abstraction level for their needs, from simple single operations to complex bulk processing workflows.
105

106
## Capabilities
107

108
### Command Line Interface
109

110
Complete command-line client for all Swift operations including upload, download, container management, and administrative tasks.
111

112
```bash { .api }
113
swift upload <container> <file>     # Upload objects
114
swift download <container>          # Download objects
115
swift list [<container>]           # List containers/objects
116
swift delete <container> [<object>] # Delete objects/containers
117
swift stat [<container>] [<object>] # Show statistics
118
swift post <container> [<object>]   # Update metadata
119
swift copy <container> <object>     # Copy objects
120
swift capabilities [<url>]          # Show cluster capabilities
121
swift auth                          # Show authentication info
122
swift tempurl <method> <seconds> <path> <key>  # Generate temporary URLs
123
swift bash_completion               # Enable shell completion
124
```
125

126
[Command Line Interface](./command-line-interface.md)
127

128
### Client Connection
129

130
High-level Swift client providing automatic authentication, connection pooling, retry logic, and convenient wrapper methods for all Swift operations.
131

132
```python { .api }
133
class Connection:
134
    def __init__(
135
        self,
136
        authurl=None,
137
        user=None,
138
        key=None,
139
        retries=5,
140
        preauthurl=None,
141
        preauthtoken=None,
142
        snet=False,
143
        starting_backoff=1,
144
        max_backoff=64,
145
        tenant_name=None,
146
        os_options=None,
147
        auth_version="1",
148
        cacert=None,
149
        insecure=False,
150
        cert=None,
151
        cert_key=None,
152
        ssl_compression=True,
153
        retry_on_ratelimit=True,
154
        timeout=None,
155
        session=None,
156
        force_auth_retry=False
157
    ): ...
158

159
    def get_account(self, marker=None, limit=None, prefix=None, end_marker=None, full_listing=False, headers=None, delimiter=None): ...
160
    def get_container(self, container, marker=None, limit=None, prefix=None, delimiter=None, end_marker=None, version_marker=None, path=None, full_listing=False, headers=None, query_string=None): ...
161
    def get_object(self, container, obj, resp_chunk_size=None, query_string=None, response_dict=None, headers=None): ...
162
    def put_container(self, container, headers=None, response_dict=None, query_string=None): ...
163
    def put_object(self, container, obj, contents, content_length=None, etag=None, chunk_size=None, content_type=None, headers=None, query_string=None, response_dict=None): ...
164
    def delete_object(self, container, obj, query_string=None, response_dict=None, headers=None): ...
165
```
166

167
[Client Connection](./client-connection.md)
168

169
### Authentication
170

171
Comprehensive authentication support for Swift v1 auth, Keystone v2/v3, and session-based authentication with multiple credential types and authentication methods.
172

173
```python { .api }
174
def get_auth(auth_url, user, key, **kwargs):
175
    """
176
    Get authentication/authorization credentials.
177

178
    Parameters:
179
    - auth_url: str, authentication URL
180
    - user: str, username for authentication
181
    - key: str, password/key for authentication
182
    - auth_version: str, auth version ('1', '2.0', '3')
183
    - os_options: dict, OpenStack identity service options
184
    - session: keystoneauth1 session object
185

186
    Returns:
187
    tuple: (storage_url, auth_token)
188
    """
189
```
190

191
[Authentication](./authentication.md)
192

193
### Low-Level Operations
194

195
Direct HTTP-level functions for Swift operations providing fine-grained control over requests, custom headers, and response handling.
196

197
```python { .api }
198
def get_account(url, token, marker=None, limit=None, prefix=None, end_marker=None, http_conn=None, full_listing=False, service_token=None, headers=None, delimiter=None): ...
199
def get_container(url, token, container, marker=None, limit=None, prefix=None, delimiter=None, end_marker=None, version_marker=None, path=None, http_conn=None, full_listing=False, service_token=None, headers=None, query_string=None): ...
200
def get_object(url, token, container, name, http_conn=None, resp_chunk_size=None, query_string=None, response_dict=None, headers=None, service_token=None): ...
201
def put_object(url, token=None, container=None, name=None, contents=None, content_length=None, etag=None, chunk_size=None, content_type=None, headers=None, http_conn=None, proxy=None, query_string=None, response_dict=None, service_token=None): ...
202
def delete_object(url, token=None, container=None, name=None, http_conn=None, headers=None, proxy=None, query_string=None, response_dict=None, service_token=None): ...
203
```
204

205
[Low-Level Operations](./low-level-operations.md)
206

207
### Bulk Operations Service
208

209
High-level service for bulk operations with multi-threading, progress reporting, automatic retries, and comprehensive error handling for upload, download, delete, and copy operations.
210

211
```python { .api }
212
class SwiftService:
213
    def __init__(self, options=None): ...
214
    def upload(self, container, objects, options=None): ...
215
    def download(self, container=None, objects=None, options=None): ...
216
    def delete(self, container=None, objects=None, options=None): ...
217
    def copy(self, container=None, objects=None, options=None): ...
218
    def post(self, container=None, objects=None, options=None): ...
219
    def list(self, container=None, options=None): ...
220
    def stat(self, container=None, objects=None, options=None): ...
221
    def get_capabilities(self, url=None): ...
222
```
223

224
[Bulk Operations Service](./bulk-operations.md)
225

226
### Utility Functions
227

228
Helper functions for temporary URLs, header processing, data formatting, and various Swift-specific operations.
229

230
```python { .api }
231
def generate_temp_url(path, seconds, key, method, absolute=False, prefix_based=False, iso8601=False, ip_range=None, digest=None, auth_url=None): ...
232
def parse_api_response(headers, body): ...
233
def config_true_value(value): ...
234
def prt_bytes(num_bytes, human_flag): ...
235
```
236

237
[Utility Functions](./utilities.md)
238

239
### Exception Handling
240

241
Comprehensive error handling with detailed HTTP context, transaction IDs, and Swift-specific error information.
242

243
```python { .api }
244
class ClientException(Exception):
245
    def __init__(
246
        self,
247
        msg,
248
        http_scheme='',
249
        http_host='',
250
        http_port='',
251
        http_path='',
252
        http_query='',
253
        http_status=None,
254
        http_reason='',
255
        http_device='',
256
        http_response_content='',
257
        http_response_headers=None
258
    ): ...
259
```
260

261
[Exception Handling](./exceptions.md)