Skip to content

Commit 977c399

Browse files
feorlenfeorlen
authored
Update the Python Quickstart README (#1326)
1 parent 15c9699 commit 977c399

File tree

2 files changed

+104
-36
lines changed

2 files changed

+104
-36
lines changed

‎NOTICE

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
MinIO Cloud Storage, (C) 2014-2023 MinIO, Inc.
2+
3+
This product includes software developed at MinIO, Inc.
4+
(https://min.io/).
5+
6+
The MinIO project contains unmodified/modified subcomponents too with
7+
separate copyright notices and license terms. Your use of the source
8+
code for these subcomponents is subject to the terms and conditions
9+
of Apache License Version 2.0

‎README.md

Lines changed: 95 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -1,96 +1,155 @@
1-
# MinIO Python SDK for Amazon S3 Compatible Cloud Storage [![Slack](https://slack.min.io/slack?type=svg)](https://slack.min.io)
1+
# MinIO Python Client SDK for Amazon S3 Compatible Cloud Storage [![Slack](https://slack.min.io/slack?type=svg)](https://slack.min.io) [![Apache V2 License](https://img.shields.io/badge/license-Apache%20V2-blue.svg)](https://github.com/minio/minio-py/blob/master/LICENSE)
22

3-
MinIO Python SDK is Simple Storage Service (aka S3) client to perform bucket and object operations to any Amazon S3 compatible object storage service.
3+
The MinIO Python Client SDK provides high level APIs to access any MinIO Object Storage or other Amazon S3 compatible service.
44

5-
For a complete list of APIs and examples, please take a look at the [Python Client API Reference](https://min.io/docs/minio/linux/developers/python/API.html)
5+
This Quickstart Guide covers how to install the MinIO client SDK, connect to the object storage service, and create a sample file uploader.
66

7-
## Minimum Requirements
8-
Python 3.7 or higher.
7+
The example below uses:
8+
- [Python version 3.7+](https://www.python.org/downloads/)
9+
- The [MinIO `mc` command line tool](https://min.io/docs/minio/linux/reference/minio-mc.html)
10+
- The MinIO `play` test server
911

10-
## Download using pip
12+
The `play` server is a public MinIO cluster located at [https://play.min.io](https://play.min.io).
13+
This cluster runs the latest stable version of MinIO and may be used for testing and development.
14+
The access credentials in the example are open to the public and all data uploaded to `play` should be considered public and world-readable.
15+
16+
For a complete list of APIs and examples, see the [Python Client API Reference](https://min.io/docs/minio/linux/developers/python/API.html)
17+
18+
## Install the MinIO Python SDK
19+
20+
The Python SDK requires Python version 3.7+.
21+
You can install the SDK with `pip` or from the [`minio/minio-py` GitHub repository](https://github.com/minio/minio-py):
22+
23+
### Using `pip`
1124

1225
```sh
1326
pip3 install minio
1427
```
1528

16-
## Download source
29+
### Using Source From GitHub
1730

1831
```sh
1932
git clone https://github.com/minio/minio-py
2033
cd minio-py
2134
python setup.py install
2235
```
2336

24-
## Quick Start Example - File Uploader
25-
This example program connects to an S3-compatible object storage server, make a bucket on that server, and upload a file to the bucket.
37+
## Create a MinIO Client
2638

27-
You need the following items to connect to an S3-compatible object storage server:
39+
To connect to the target service, create a MinIO client using the `Minio()` method with the following required parameters:
2840

29-
| Parameters | Description |
30-
|------------|------------------------------------------------------------|
31-
| Endpoint | URL to S3 service. |
32-
| Access Key | Access key (aka user ID) of an account in the S3 service. |
33-
| Secret Key | Secret key (aka password) of an account in the S3 service. |
41+
| Parameter | Description |
42+
|--------------|--------------------------------------------------------|
43+
| `endpoint` | URL of the target service. |
44+
| `access_key` | Access key (user ID) of a user account in the service. |
45+
| `secret_key` | Secret key (password) for the user account. |
3446

35-
This example uses MinIO server playground [https://play.min.io](https://play.min.io). Feel free to use this service for test and development.
47+
For example:
3648

37-
### file_uploader.py
3849
```py
3950
from minio import Minio
40-
from minio.error import S3Error
4151

52+
client = Minio("play.min.io",
53+
access_key="Q3AM3UQ867SPQQA43P2F",
54+
secret_key="zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG",
55+
)
56+
```
57+
58+
## Example - File Uploader
59+
60+
This example does the following:
61+
62+
- Connects to the MinIO `play` server using the provided credentials.
63+
- Creates a bucket named `python-test-bucket` if it does not already exist.
64+
- Uploads a file named `test-file.txt` from `/tmp`, renaming it `my-test-file.txt`.
65+
- Verifies the file was created using [`mc ls`](https://min.io/docs/minio/linux/reference/minio-mc/mc-ls.html).
66+
67+
### `file_uploader.py`
68+
69+
```py
70+
# file_uploader.py MinIO Python SDK example
71+
from minio import Minio
72+
from minio.error import S3Error
4273

4374
def main():
4475
# Create a client with the MinIO server playground, its access key
4576
# and secret key.
46-
client = Minio(
47-
"play.min.io",
77+
client = Minio("play.min.io",
4878
access_key="Q3AM3UQ867SPQQA43P2F",
4979
secret_key="zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG",
5080
)
5181

52-
# Make 'asiatrip' bucket if not exist.
53-
found = client.bucket_exists("asiatrip")
82+
# The file to upload, change this path if needed
83+
source_file = "/tmp/test-file.txt"
84+
85+
# The destination bucket and filename on the MinIO server
86+
bucket_name = "python-test-bucket"
87+
destination_file = "my-test-file.txt"
88+
89+
# Make the bucket if it doesn't exist.
90+
found = client.bucket_exists(bucket_name)
5491
if not found:
55-
client.make_bucket("asiatrip")
92+
client.make_bucket(bucket_name)
93+
print("Created bucket", bucket_name)
5694
else:
57-
print("Bucket 'asiatrip' already exists")
95+
print("Bucket", bucket_name, "already exists")
5896

59-
# Upload '/home/user/Photos/asiaphotos.zip' as object name
60-
# 'asiaphotos-2015.zip' to bucket 'asiatrip'.
97+
# Upload the file, renaming it in the process
6198
client.fput_object(
62-
"asiatrip", "asiaphotos-2015.zip", "/home/user/Photos/asiaphotos.zip",
99+
bucket_name, destination_file, source_file,
63100
)
64101
print(
65-
"'/home/user/Photos/asiaphotos.zip' is successfully uploaded as "
66-
"object 'asiaphotos-2015.zip' to bucket 'asiatrip'."
102+
source_file, "successfully uploaded as object",
103+
destination_file, "to bucket", bucket_name,
67104
)
68105

69-
70106
if __name__ == "__main__":
71107
try:
72108
main()
73109
except S3Error as exc:
74110
print("error occurred.", exc)
75111
```
76112

77-
#### Run File Uploader
113+
To run this example:
114+
115+
1. Create a file in `/tmp` named `test-file.txt`.
116+
To use a different path or filename, modify the value of `source_file`.
117+
118+
2. Run `file_uploader.py` with the following command:
119+
78120
```sh
79-
$ python file_uploader.py
80-
'/home/user/Photos/asiaphotos.zip' is successfully uploaded as object 'asiaphotos-2015.zip' to bucket 'asiatrip'.
121+
python file_uploader.py
122+
```
81123

82-
$ mc ls play/asiatrip/
83-
[2016-06-02 18:10:29 PDT] 82KiB asiaphotos-2015.zip
124+
If the bucket does not exist on the server, the output resembles the following:
125+
126+
```sh
127+
Created bucket python-test-bucket
128+
/tmp/test-file.txt successfully uploaded as object my-test-file.txt to bucket python-test-bucket
129+
```
130+
131+
3. Verify the uploaded file with `mc ls`:
132+
133+
```sh
134+
mc ls play/python-test-bucket
135+
[2023-11-03 22:18:54 UTC] 20KiB STANDARD my-test-file.txt
84136
```
85137

86138
## More References
139+
87140
* [Python Client API Reference](https://min.io/docs/minio/linux/developers/python/API.html)
88141
* [Examples](https://github.com/minio/minio-py/tree/master/examples)
89142

90143
## Explore Further
144+
91145
* [Complete Documentation](https://min.io/docs/minio/kubernetes/upstream/index.html)
92146

93147
## Contribute
94-
Please refer [Contributors Guide](https://github.com/minio/minio-py/blob/master/CONTRIBUTING.md)
148+
149+
[Contributors Guide](https://github.com/minio/minio-py/blob/master/CONTRIBUTING.md)
150+
151+
## License
152+
153+
This SDK is distributed under the [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0), see [LICENSE](https://github.com/minio/minio-py/blob/master/LICENSE) and [NOTICE](https://github.com/minio/minio-go/blob/master/NOTICE) for more information.
95154

96155
[![PYPI](https://img.shields.io/pypi/v/minio.svg)](https://pypi.python.org/pypi/minio)

0 commit comments

Comments
 (0)