0
# Qiniu Python SDK
1

2
A comprehensive Python SDK for Qiniu Cloud Storage services, enabling developers to integrate file upload, download, and management capabilities with Qiniu's cloud storage platform. The SDK offers a full-featured API for storage operations including bucket management, file operations, CDN management, SMS services, and real-time communication features.
3

4
## Package Information
5

6
- **Package Name**: qiniu
7
- **Language**: Python
8
- **Installation**: `pip install qiniu`
9
- **Version**: 7.17.0
10

11
## Core Imports
12

13
```python
14
import qiniu
15
```
16

17
Most common usage patterns:
18

19
```python
20
from qiniu import Auth, BucketManager, put_file_v2, put_data
21
```
22

23
## Basic Usage
24

25
```python
26
from qiniu import Auth, put_file_v2, BucketManager
27

28
# Initialize authentication
29
access_key = 'your_access_key'
30
secret_key = 'your_secret_key'
31
auth = Auth(access_key, secret_key)
32

33
# Upload a file
34
bucket_name = 'your_bucket'
35
key = 'file_key'
36
local_file = './path/to/file.jpg'
37

38
# Generate upload token
39
token = auth.upload_token(bucket_name, key, 3600)
40

41
# Upload file
42
ret, info = put_file_v2(token, key, local_file)
43
print(info)
44
print(ret['key'], ret['hash'])
45

46
# Manage files
47
bucket_manager = BucketManager(auth)
48
ret, info = bucket_manager.stat(bucket_name, key)
49
print(ret)
50
```
51

52
## Architecture
53

54
The Qiniu SDK is organized around several key components:
55

56
- **Authentication**: `Auth` and `QiniuMacAuth` classes provide secure token-based authentication
57
- **Storage Operations**: `BucketManager` handles file and bucket management, upload functions handle file transfers
58
- **CDN Management**: `CdnManager` and `DomainManager` control content delivery and domain configuration
59
- **Processing Services**: `PersistentFop` enables data processing workflows
60
- **Compute Services**: `AccountClient` and `QcosClient` manage cloud computing resources
61
- **Communication Services**: `Sms` and `RtcServer` provide messaging and real-time communication
62
- **Utilities**: Helper functions for encoding, hashing, and data transformation
63

64
## Capabilities
65

66
### Authentication & Security
67

68
Secure authentication using access/secret keys with token-based access control for all Qiniu services.
69

70
```python { .api }
71
class Auth:
72
    def __init__(self, access_key: str, secret_key: str, disable_qiniu_timestamp_signature: bool = None): ...
73
    def upload_token(self, bucket: str, key: str = None, expires: int = 3600, policy: dict = None, strict_policy: bool = True) -> str: ...
74
    def private_download_url(self, url: str, expires: int = 3600) -> str: ...
75
    def token_of_request(self, url: str, body: str = None, content_type: str = None) -> str: ...
76

77
class QiniuMacAuth:
78
    def __init__(self, access_key: str, secret_key: str, disable_qiniu_timestamp_signature: bool = None): ...
79
    def token_of_request(self, method: str, host: str, url: str, qheaders: dict, content_type: str = None, body: str = None) -> str: ...
80
```
81

82
[Authentication](./authentication.md)
83

84
### File Storage Operations
85

86
Complete file upload, download, and management operations with support for resumable uploads and batch operations.
87

88
```python { .api }
89
def put_file_v2(up_token: str, key: str, file_path: str, **kwargs) -> tuple: ...
90
def put_data(up_token: str, key: str, data: bytes, **kwargs) -> tuple: ...
91
def put_stream_v2(up_token: str, key: str, input_stream, file_name: str, data_size: int, **kwargs) -> tuple: ...
92

93
class BucketManager:
94
    def __init__(self, auth: Auth, **kwargs): ...
95
    def list(self, bucket: str, prefix: str = None, marker: str = None, limit: int = None, delimiter: str = None) -> tuple: ...
96
    def stat(self, bucket: str, key: str) -> tuple: ...
97
    def delete(self, bucket: str, key: str) -> tuple: ...
98
    def copy(self, bucket: str, key: str, bucket_to: str, key_to: str, force: str = 'false') -> tuple: ...
99
    def batch(self, operations: list) -> tuple: ...
100
```
101

102
[File Storage](./file-storage.md)
103

104
### CDN Management
105

106
Content delivery network cache management, domain configuration, and traffic statistics.
107

108
```python { .api }
109
class CdnManager:
110
    def __init__(self, auth: Auth): ...
111
    def refresh_urls(self, urls: list) -> tuple: ...
112
    def refresh_dirs(self, dirs: list) -> tuple: ...
113
    def prefetch_urls(self, urls: list) -> tuple: ...
114
    def get_bandwidth_data(self, domains: list, start_date: str, end_date: str, granularity: str, data_type: str = None) -> tuple: ...
115

116
class DomainManager:
117
    def __init__(self, auth: Auth): ...
118
    def create_domain(self, name: str, body: dict) -> tuple: ...
119
    def put_httpsconf(self, name: str, certid: str, forceHttps: bool) -> tuple: ...
120
```
121

122
[CDN Management](./cdn-management.md)
123

124
### Data Processing
125

126
Persistent data processing operations for media files including audio, video, and image transformations.
127

128
```python { .api }
129
class PersistentFop:
130
    def __init__(self, auth: Auth, bucket: str, pipeline: str = None, notify_url: str = None): ...
131
    def execute(self, key: str, fops: str = None, force: bool = None, persistent_type: int = None, workflow_template_id: str = None) -> tuple: ...
132
    def get_status(self, persistent_id: str) -> tuple: ...
133

134
def build_op(cmd: str, first_arg: str, **kwargs) -> str: ...
135
def pipe_cmd(*cmds: str) -> str: ...
136
def op_save(op: str, bucket: str, key: str) -> str: ...
137
```
138

139
[Data Processing](./data-processing.md)
140

141
### Cloud Computing
142

143
Application and service stack management for cloud computing resources including containers and access points.
144

145
```python { .api }
146
class AccountClient:
147
    def __init__(self, auth: Auth, host: str = None): ...
148
    def list_apps(self) -> tuple: ...
149
    def create_app(self, args: dict) -> tuple: ...
150
    def get_qcos_client(self, app_uri: str): ...
151

152
class QcosClient:
153
    def __init__(self, auth: Auth, host: str = None): ...
154
    def list_stacks(self) -> tuple: ...
155
    def create_stack(self, args: dict) -> tuple: ...
156
    def list_services(self, stack: str) -> tuple: ...
157
    def list_containers(self, stack: str = None, service: str = None) -> tuple: ...
158
```
159

160
[Cloud Computing](./cloud-computing.md)
161

162
### Communication Services
163

164
SMS messaging and real-time communication services for application integration.
165

166
```python { .api }
167
class Sms:
168
    def __init__(self, auth: Auth): ...
169
    def createSignature(self, signature: str, source: str, pics: list = None) -> tuple: ...
170
    def createTemplate(self, name: str, template: str, type: str, description: str, signature_id: str) -> tuple: ...
171
    def sendMessage(self, template_id: str, mobiles: list, parameters: dict) -> tuple: ...
172

173
class RtcServer:
174
    def __init__(self, auth: Auth): ...
175
    def create_app(self, data: dict) -> tuple: ...
176
    def list_user(self, app_id: str, room_name: str) -> tuple: ...
177
    def kick_user(self, app_id: str, room_name: str, user_id: str) -> tuple: ...
178

179
def get_room_token(access_key: str, secret_key: str, room_access: dict) -> str: ...
180
```
181

182
[Communication Services](./communication-services.md)
183

184
### Configuration & Utilities
185

186
Global configuration management, region/zone settings, and utility functions for encoding and data transformation.
187

188
```python { .api }
189
def set_default(**kwargs): ...
190
def get_default(key: str): ...
191

192
class Region:
193
    def __init__(self, **kwargs): ...
194
    def get_up_host_by_token(self, up_token: str, home_dir: str) -> str: ...
195
    def get_bucket_hosts(self, ak: str, bucket: str, home_dir: str = None, force: bool = False) -> dict: ...
196

197
class Zone:
198
    """Zone configuration (legacy alias for Region)"""
199
    def __init__(self, **kwargs): ...
200
    def get_up_host_by_token(self, up_token: str, home_dir: str) -> str: ...
201
    def get_bucket_hosts(self, ak: str, bucket: str, home_dir: str = None, force: bool = False) -> dict: ...
202

203
def urlsafe_base64_encode(data: bytes) -> str: ...
204
def urlsafe_base64_decode(data: str) -> bytes: ...
205
def entry(bucket: str, key: str) -> str: ...
206
def etag(file_path: str) -> str: ...
207
def crc32(data: bytes) -> int: ...
208
```
209

210
[Configuration & Utilities](./configuration-utilities.md)
211

212
## Common Types
213

214
```python { .api }
215
class ResponseInfo:
216
    """HTTP response information wrapper"""
217
    status_code: int
218
    text_body: str
219
    req_id: str
220
    x_log: str
221
    error: str
222
    url: str
223
    exception: Exception
224
    
225
    def ok(self) -> bool: ...
226
    def need_retry(self) -> bool: ...
227
    def connect_failed(self) -> bool: ...
228
    def json(self) -> dict: ...
229

230
class UploadProgressRecorder:
231
    """Persistent upload progress recording for resumable uploads"""
232
    def __init__(self, record_folder: str = None): ...
233
    def has_upload_record(self, file_name: str, key: str) -> bool: ...
234
    def get_upload_record(self, file_name: str, key: str) -> dict: ...
235
    def set_upload_record(self, file_name: str, key: str, data: dict): ...
236
    def delete_upload_record(self, file_name: str, key: str): ...
237
```