Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update the Python Quickstart README #1326

Merged
merged 4 commits into from
Dec 15, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions NOTICE
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
MinIO Cloud Storage, (C) 2014-2023 MinIO, Inc.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added and linked to this along with the license


This product includes software developed at MinIO, Inc.
(https://min.io/).

The MinIO project contains unmodified/modified subcomponents too with
separate copyright notices and license terms. Your use of the source
code for these subcomponents is subject to the terms and conditions
of Apache License Version 2.0
131 changes: 95 additions & 36 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,96 +1,155 @@
# MinIO Python SDK for Amazon S3 Compatible Cloud Storage [![Slack](https://slack.min.io/slack?type=svg)](https://slack.min.io)
# 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)

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

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)
This Quickstart Guide covers how to install the MinIO client SDK, connect to the object storage service, and create a sample file uploader.

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

## Download using pip
The `play` server is a public MinIO cluster located at [https://play.min.io](https://play.min.io).
This cluster runs the latest stable version of MinIO and may be used for testing and development.
The access credentials in the example are open to the public and all data uploaded to `play` should be considered public and world-readable.

For a complete list of APIs and examples, see the [Python Client API Reference](https://min.io/docs/minio/linux/developers/python/API.html)

## Install the MinIO Python SDK

The Python SDK requires Python version 3.7+.
You can install the SDK with `pip` or from the [`minio/minio-py` GitHub repository](https://github.com/minio/minio-py):

### Using `pip`

```sh
pip3 install minio
```

## Download source
### Using Source From GitHub

```sh
git clone https://github.com/minio/minio-py
cd minio-py
python setup.py install
```

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

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

| Parameters | Description |
|------------|------------------------------------------------------------|
| Endpoint | URL to S3 service. |
| Access Key | Access key (aka user ID) of an account in the S3 service. |
| Secret Key | Secret key (aka password) of an account in the S3 service. |
| Parameter | Description |
|--------------|--------------------------------------------------------|
| `endpoint` | URL of the target service. |
| `access_key` | Access key (user ID) of a user account in the service. |
| `secret_key` | Secret key (password) for the user account. |

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

### file_uploader.py
```py
from minio import Minio
from minio.error import S3Error

client = Minio("play.min.io",
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps this is more practical, less verbose yet still some additional context for novice readers.

access_key="Q3AM3UQ867SPQQA43P2F",
secret_key="zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG",
)
```

## Example - File Uploader
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see minio-go style README is too verbose for Python. My suggestion is to provide the example directly.


This example does the following:

- Connects to the MinIO `play` server using the provided credentials.
- Creates a bucket named `python-test-bucket` if it does not already exist.
- Uploads a file named `test-file.txt` from `/tmp`, renaming it `my-test-file.txt`.
- Verifies the file was created using [`mc ls`](https://min.io/docs/minio/linux/reference/minio-mc/mc-ls.html).

### `file_uploader.py`

```py
# file_uploader.py MinIO Python SDK example
feorlen marked this conversation as resolved.
Show resolved Hide resolved
from minio import Minio
from minio.error import S3Error

def main():
# Create a client with the MinIO server playground, its access key
# and secret key.
client = Minio(
"play.min.io",
client = Minio("play.min.io",
access_key="Q3AM3UQ867SPQQA43P2F",
secret_key="zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG",
)

# Make 'asiatrip' bucket if not exist.
found = client.bucket_exists("asiatrip")
# The file to upload, change this path if needed
source_file = "/tmp/test-file.txt"

# The destination bucket and filename on the MinIO server
bucket_name = "python-test-bucket"
destination_file = "my-test-file.txt"

# Make the bucket if it doesn't exist.
found = client.bucket_exists(bucket_name)
if not found:
client.make_bucket("asiatrip")
client.make_bucket(bucket_name)
print("Created bucket", bucket_name)
else:
print("Bucket 'asiatrip' already exists")
print("Bucket", bucket_name, "already exists")

# Upload '/home/user/Photos/asiaphotos.zip' as object name
# 'asiaphotos-2015.zip' to bucket 'asiatrip'.
# Upload the file, renaming it in the process
client.fput_object(
"asiatrip", "asiaphotos-2015.zip", "/home/user/Photos/asiaphotos.zip",
bucket_name, destination_file, source_file,
)
print(
"'/home/user/Photos/asiaphotos.zip' is successfully uploaded as "
"object 'asiaphotos-2015.zip' to bucket 'asiatrip'."
source_file, "successfully uploaded as object",
destination_file, "to bucket", bucket_name,
)


if __name__ == "__main__":
try:
main()
except S3Error as exc:
print("error occurred.", exc)
```

#### Run File Uploader
To run this example:

1. Create a file in `/tmp` named `test-file.txt`.
To use a different path or filename, modify the value of `source_file`.

2. Run `file_uploader.py` with the following command:

```sh
$ python file_uploader.py
'/home/user/Photos/asiaphotos.zip' is successfully uploaded as object 'asiaphotos-2015.zip' to bucket 'asiatrip'.
python file_uploader.py
```

$ mc ls play/asiatrip/
[2016-06-02 18:10:29 PDT] 82KiB asiaphotos-2015.zip
If the bucket does not exist on the server, the output resembles the following:

```sh
Created bucket python-test-bucket
/tmp/test-file.txt successfully uploaded as object my-test-file.txt to bucket python-test-bucket
```

3. Verify the uploaded file with `mc ls`:

```sh
mc ls play/python-test-bucket
[2023-11-03 22:18:54 UTC] 20KiB STANDARD my-test-file.txt
```

## More References

* [Python Client API Reference](https://min.io/docs/minio/linux/developers/python/API.html)
* [Examples](https://github.com/minio/minio-py/tree/master/examples)

## Explore Further

* [Complete Documentation](https://min.io/docs/minio/kubernetes/upstream/index.html)

## Contribute
Please refer [Contributors Guide](https://github.com/minio/minio-py/blob/master/CONTRIBUTING.md)

[Contributors Guide](https://github.com/minio/minio-py/blob/master/CONTRIBUTING.md)

## License

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.

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