0
# MinIO Python SDK
1

2
MinIO Python SDK provides simple APIs to access any Amazon S3 Compatible Object Storage. It supports full S3 API compatibility with advanced features like server-side encryption, object versioning, lifecycle management, and bucket notifications. The SDK includes both standard S3 operations via the `Minio` class and administrative operations via the `MinioAdmin` class.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```python
14
from minio import Minio, MinioAdmin
15
```
16

17
For specific functionality:
18

19
```python
20
from minio import (
21
    Minio, MinioAdmin,
22
    S3Error, InvalidResponseError, ServerError
23
)
24
from minio.credentials import StaticProvider, EnvAWSProvider, ChainedProvider
25
from minio.sse import SseCustomerKey, SseKMS, SseS3
26
from minio.commonconfig import Tags, CopySource, ComposeSource
27
```
28

29
## Basic Usage
30

31
```python
32
from minio import Minio
33
from minio.error import S3Error
34

35
# Create MinIO client
36
client = Minio(
37
    "play.min.io",
38
    access_key="minioadmin",
39
    secret_key="minioadmin",
40
    secure=True
41
)
42

43
# Create bucket
44
try:
45
    client.make_bucket("my-bucket")
46
except S3Error as e:
47
    print(f"Error: {e}")
48

49
# Upload object
50
try:
51
    result = client.fput_object(
52
        "my-bucket", "my-object", "/path/to/file.txt"
53
    )
54
    print(f"Uploaded: {result.object_name}")
55
except S3Error as e:
56
    print(f"Error: {e}")
57

58
# Download object
59
try:
60
    client.fget_object("my-bucket", "my-object", "/path/to/download.txt")
61
    print("Downloaded successfully")
62
except S3Error as e:
63
    print(f"Error: {e}")
64

65
# List objects
66
try:
67
    objects = client.list_objects("my-bucket")
68
    for obj in objects:
69
        print(f"Object: {obj.object_name}, Size: {obj.size}")
70
except S3Error as e:
71
    print(f"Error: {e}")
72
```
73

74
## Architecture
75

76
The MinIO Python SDK is built around two main client classes:
77

78
- **Minio**: Standard S3 operations including bucket management, object operations, versioning, lifecycle, encryption, and policies
79
- **MinioAdmin**: Administrative operations for MinIO server management including user/group management, policies, service accounts, and server configuration
80

81
**Thread Safety**: Both clients are thread-safe when using Python's `threading` library but are NOT safe for multiprocessing.
82

83
**Credential Management**: Flexible credential system supporting static credentials, environment variables, AWS config files, IAM roles, and credential chaining.
84

85
**Error Handling**: Comprehensive exception hierarchy with `S3Error` for S3 operations, `ServerError` for HTTP errors, and `InvalidResponseError` for malformed responses.
86

87
## Capabilities
88

89
### Client Operations
90

91
Core bucket and object operations including CRUD operations, metadata management, and basic configuration.
92

93
```python { .api }
94
class Minio:
95
    def __init__(
96
        self,
97
        endpoint: str,
98
        access_key: str | None = None,
99
        secret_key: str | None = None,
100
        session_token: str | None = None,
101
        secure: bool = True,
102
        region: str | None = None,
103
        http_client: urllib3.PoolManager | None = None,
104
        credentials: Provider | None = None,
105
        cert_check: bool = True
106
    ) -> None: ...
107
    
108
    def make_bucket(
109
        self, 
110
        bucket_name: str, 
111
        location: str | None = None, 
112
        object_lock: bool = False
113
    ) -> None: ...
114
    
115
    def list_buckets(self) -> list[Bucket]: ...
116
    
117
    def put_object(
118
        self,
119
        bucket_name: str,
120
        object_name: str, 
121
        data: io.IOBase,
122
        length: int = -1,
123
        content_type: str = "application/octet-stream",
124
        metadata: dict[str, str] | None = None,
125
        sse: Sse | None = None,
126
        progress: ProgressType | None = None,
127
        part_size: int = 0,
128
        num_parallel_uploads: int = 3,
129
        tags: Tags | None = None,
130
        retention: Retention | None = None,
131
        legal_hold: bool = False
132
    ) -> ObjectWriteResult: ...
133
    
134
    def get_object(
135
        self,
136
        bucket_name: str,
137
        object_name: str,
138
        offset: int = 0,
139
        length: int = 0,
140
        request_headers: dict[str, str] | None = None,
141
        ssec: SseCustomerKey | None = None,
142
        version_id: str | None = None,
143
        extra_query_params: dict[str, str] | None = None
144
    ) -> urllib3.HTTPResponse: ...
145
    
146
    def prompt_object(
147
        self,
148
        bucket_name: str,
149
        object_name: str,
150
        prompt: str,
151
        lambda_arn: str | None = None,
152
        request_headers: dict[str, str] | None = None,
153
        ssec: SseCustomerKey | None = None,
154
        version_id: str | None = None,
155
        **kwargs: Any
156
    ) -> urllib3.HTTPResponse: ...
157
    
158
    def enable_object_legal_hold(
159
        self,
160
        bucket_name: str,
161
        object_name: str,
162
        version_id: str | None = None
163
    ) -> None: ...
164
    
165
    def disable_object_legal_hold(
166
        self,
167
        bucket_name: str,
168
        object_name: str,
169
        version_id: str | None = None
170
    ) -> None: ...
171
    
172
    def is_object_legal_hold_enabled(
173
        self,
174
        bucket_name: str,
175
        object_name: str,
176
        version_id: str | None = None
177
    ) -> bool: ...
178
```
179

180
[Client Operations](./client-operations.md)
181

182
### Advanced Operations
183

184
Advanced S3 features including presigned URLs, SQL SELECT queries on objects, and bucket notifications.
185

186
```python { .api }
187
def presigned_get_object(
188
    self,
189
    bucket_name: str,
190
    object_name: str,
191
    expires: datetime.timedelta = datetime.timedelta(days=7),
192
    response_headers: dict[str, str] | None = None,
193
    request_date: datetime.datetime | None = None,
194
    version_id: str | None = None,
195
    extra_query_params: dict[str, str] | None = None
196
) -> str: ...
197

198
def select_object_content(
199
    self,
200
    bucket_name: str,
201
    object_name: str,
202
    request: SelectRequest
203
) -> SelectObjectReader: ...
204

205
def listen_bucket_notification(
206
    self,
207
    bucket_name: str,
208
    prefix: str = "",
209
    suffix: str = "",
210
    events: list[str] = ["s3:ObjectCreated:*", "s3:ObjectRemoved:*"]
211
) -> EventIterable: ...
212
```
213

214
[Advanced Operations](./advanced-operations.md)
215

216
### Administrative Operations
217

218
MinIO server administration including user management, policy configuration, and service accounts.
219

220
```python { .api }
221
class MinioAdmin:
222
    def __init__(
223
        self,
224
        endpoint: str,
225
        credentials: Provider,
226
        region: str = "",
227
        secure: bool = True,
228
        cert_check: bool = True,
229
        http_client: urllib3.PoolManager | None = None
230
    ) -> None: ...
231
    
232
    def user_add(self, access_key: str, secret_key: str) -> str: ...
233
    def policy_add(self, policy_name: str, policy_file: str) -> str: ...
234
    def info(self) -> str: ...
235
    def service_restart(self) -> str: ...
236
    def profile_start(self, profilers: tuple[str] = ()) -> str: ...
237
    def get_data_usage_info(self) -> str: ...
238
    def bucket_quota_clear(self, bucket: str) -> str: ...
239
    def add_site_replication(self, peer_sites: list[PeerSite]) -> str: ...
240
    def get_site_replication_info(self) -> str: ...
241
    def attach_policy_ldap(
242
        self,
243
        policies: list[str],
244
        user: str | None = None,
245
        group: str | None = None
246
    ) -> str: ...
247
    def attach_policy(
248
        self,
249
        policies: list[str],
250
        user: str | None = None,
251
        group: str | None = None
252
    ) -> str: ...
253
```
254

255
[Administrative Operations](./admin-operations.md)
256

257
### Credentials and Authentication
258

259
Comprehensive credential management system with multiple provider types and chaining support.
260

261
```python { .api }
262
class Credentials:
263
    def __init__(
264
        self,
265
        access_key: str,
266
        secret_key: str, 
267
        session_token: str | None = None,
268
        expiration: datetime.datetime | None = None
269
    ) -> None: ...
270

271
class StaticProvider(Provider):
272
    def __init__(
273
        self,
274
        access_key: str,
275
        secret_key: str,
276
        session_token: str | None = None
277
    ) -> None: ...
278

279
class ChainedProvider(Provider):
280
    def __init__(self, providers: list[Provider]) -> None: ...
281
```
282

283
[Credentials and Authentication](./credentials-auth.md)
284

285
### Configuration Classes
286

287
Configuration objects for bucket settings, server-side encryption, lifecycle management, and object policies.
288

289
```python { .api }
290
class Tags(dict):
291
    @classmethod
292
    def new_bucket_tags(cls) -> Tags: ...
293
    @classmethod  
294
    def new_object_tags(cls) -> Tags: ...
295

296
class VersioningConfig:
297
    def __init__(
298
        self,
299
        status: str | None = None,
300
        mfa_delete: str | None = None
301
    ) -> None: ...
302

303
class SseCustomerKey(Sse):
304
    def __init__(self, key: bytes) -> None: ...
305

306
class SseKMS(Sse):
307
    def __init__(self, key: str, context: dict[str, str] | None = None) -> None: ...
308
```
309

310
[Configuration Classes](./configuration.md)
311

312
### Error Handling
313

314
Exception hierarchy for comprehensive error handling across all MinIO operations.
315

316
```python { .api }
317
class MinioException(Exception):
318
    """Base exception class for MinIO operations."""
319

320
class S3Error(MinioException):
321
    def __init__(
322
        self,
323
        code: str,
324
        message: str,
325
        resource: str | None = None,
326
        request_id: str | None = None,
327
        host_id: str | None = None,
328
        response: urllib3.HTTPResponse | None = None,
329
        bucket_name: str | None = None,
330
        object_name: str | None = None
331
    ) -> None: ...
332

333
class InvalidResponseError(MinioException):
334
    def __init__(
335
        self, 
336
        code: int | None = None, 
337
        content_type: str | None = None, 
338
        body: str | None = None
339
    ) -> None: ...
340

341
class ServerError(MinioException):
342
    def __init__(self, message: str, status_code: int) -> None: ...
343
```
344

345
[Error Handling](./error-handling.md)
346

347
## Types
348

349
### Core Data Types
350

351
```python { .api }
352
class Bucket:
353
    def __init__(self, name: str, creation_date: datetime.datetime | None = None) -> None: ...
354
    name: str
355
    creation_date: datetime.datetime | None
356

357
class Object:
358
    bucket_name: str | None
359
    object_name: str | None
360
    last_modified: datetime.datetime | None
361
    etag: str | None
362
    size: int | None
363
    content_type: str | None
364
    is_dir: bool
365
    version_id: str | None
366
    is_latest: bool
367
    is_delete_marker: bool
368
    storage_class: str | None
369
    owner_id: str | None
370
    owner_name: str | None
371
    tags: Tags | None
372

373
class ObjectWriteResult:
374
    def __init__(
375
        self,
376
        bucket_name: str,
377
        object_name: str,
378
        etag: str,
379
        version_id: str | None = None,
380
        location: str | None = None
381
    ) -> None: ...
382
    bucket_name: str
383
    object_name: str
384
    etag: str
385
    version_id: str | None
386
    location: str | None
387
```
388

389
### Protocol Types
390

391
```python { .api }
392
from typing import Protocol
393

394
class ProgressType(Protocol):
395
    def __call__(self, bytes_amount: int) -> None: ...
396

397
class Provider(Protocol):
398
    def retrieve(self) -> Credentials | None: ...
399
```