From 526810ef81c168798c3a8860195c809859268c2f Mon Sep 17 00:00:00 2001 From: Andrea Longo Date: Fri, 3 Nov 2023 16:40:39 -0600 Subject: [PATCH 1/2] Update the SDK Quickstart --- README.md | 146 +++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 112 insertions(+), 34 deletions(-) diff --git a/README.md b/README.md index 60ca12ce..be9e0c79 100644 --- a/README.md +++ b/README.md @@ -1,19 +1,21 @@ -# 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) [![Sourcegraph](https://sourcegraph.com/github.com/minio/minio-py/-/badge.svg)](https://sourcegraph.com/github.com/minio/minio-py?badge) [![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 straightforward APIs to access any Amazon S3 compatible object storage. -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 MinIO, and create a sample file uploader. +For a complete list of APIs and examples, see the [Python Client API Reference](https://min.io/docs/minio/linux/developers/python/API.html) -## Minimum Requirements -Python 3.7 or higher. +These examples presume a working [3.7+ Python development environment](https://www.python.org/downloads/) and the [MinIO `mc` command line tool](https://min.io/docs/minio/linux/reference/minio-mc.html). -## Download using pip +## Install the Minio Python SDK + +### Using pip ```sh pip3 install minio ``` -## Download source +### From GitHub ```sh git clone https://github.com/minio/minio-py @@ -21,49 +23,93 @@ 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. - -You need the following items to connect to an S3-compatible object storage server: +## Initialize a MinIO Client Object -| 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. | +The MinIO client requires the following parameters to connect to an Amazon S3 compatible object storage: -This example uses MinIO server playground [https://play.min.io](https://play.min.io). Feel free to use this service for test and development. +| Parameter | Description | +|------------|--------------------------------------------------------| +| Endpoint | URL to S3 service. | +| Access Key | Access key (user ID) of an account in the S3 service. | +| Secret Key | Secret key (password) of an account in the S3 service. | -### file_uploader.py ```py 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( + endpoint="play.min.io", + access_key="Q3AM3UQ867SPQQA43P2F", + secret_key="zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG", + ) + + print("MinIO Python SDK client initialized", client) + +if __name__ == "__main__": + try: + main() + except S3Error as exc: + print("error occurred.", exc) +``` + +## Example - File Uploader + +This sample code connects to an object storage server, creates a bucket, and uploads a file to the bucket. +It uses the MinIO `play` server, a public MinIO cluster located at [https://play.min.io](https://play.min.io). + +The `play` server runs the latest stable version of MinIO and may be used for testing and development. +The access credentials shown in this example are open to the public and all data uploaded to `play` should be considered public and non-protected. + +### `file_uploader.py` + +This example does the following: + +- Connects to the MinIO `play` server using the provided credentials. +- Creates a bucket named `minio-python-sdk-test-bucket`. +- Uploads a file named `minio-python-sdk-test-file.bin` from `/tmp`. +- Verifies the file was created using `mc ls`. + +```py +# file_uploader.py MinIO Python SDK example + +import os +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", + endpoint="play.min.io", access_key="Q3AM3UQ867SPQQA43P2F", secret_key="zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG", ) - # Make 'asiatrip' bucket if not exist. - found = client.bucket_exists("asiatrip") + bucket_name = "minio-python-sdk-test-bucket" + original_filename = "minio-python-sdk-test-file.bin" + path = "/tmp" + destination_filename = "my-test-file.bin" + + # 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) else: - print("Bucket 'asiatrip' already exists") + print("Bucket", bucket_name, "already exists") + + # Upload the file, renaming it in the process - # Upload '/home/user/Photos/asiaphotos.zip' as object name - # 'asiaphotos-2015.zip' to bucket 'asiatrip'. + original_full_path = os.path.join(path, original_filename) client.fput_object( - "asiatrip", "asiaphotos-2015.zip", "/home/user/Photos/asiaphotos.zip", + bucket_name, destination_filename, original_full_path, ) print( - "'/home/user/Photos/asiaphotos.zip' is successfully uploaded as " - "object 'asiaphotos-2015.zip' to bucket 'asiatrip'." + original_full_path, "successfully uploaded as object", + destination_filename, "to bucket", bucket_name, ) @@ -74,23 +120,55 @@ if __name__ == "__main__": print("error occurred.", exc) ``` -#### Run File Uploader +**1. Create a test file containing data:** + +You can do this with `dd` on Linux or macOS systems: + ```sh -$ python file_uploader.py -'/home/user/Photos/asiaphotos.zip' is successfully uploaded as object 'asiaphotos-2015.zip' to bucket 'asiatrip'. +dd if=/dev/urandom of=/tmp/minio-python-sdk-test-file.bin bs=2048 count=10 +``` + +or `fsutil` on Windows: -$ mc ls play/asiatrip/ -[2016-06-02 18:10:29 PDT] 82KiB asiaphotos-2015.zip +```sh +fsutil file createnew "C:\Users\\Desktop\minio-python-sdk-test-file.bin" 20480 +``` + +**2. Run `file_uploader.py` with the following command:** + +```sh +python file_uploader.py +``` + +The output resembles the following: + +```sh +/tmp/minio-python-sdk-test-file.bin successfully uploaded as object my-test-file.bin to bucket minio-python-sdk-test-bucket +``` + +**3. Verify the Uploaded File With `mc ls`:** + +```sh +mc ls play/minio-python-sdk-test-bucket +[2023-11-03 22:18:54 UTC] 20KiB STANDARD my-test-file.bin ``` ## 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) for more information. [![PYPI](https://img.shields.io/pypi/v/minio.svg)](https://pypi.python.org/pypi/minio) + From 7c518d85b2965ca117bad61298853016d7086fad Mon Sep 17 00:00:00 2001 From: Andrea Longo Date: Tue, 7 Nov 2023 16:27:14 -0700 Subject: [PATCH 2/2] rework text --- NOTICE | 9 ++++ README.md | 135 +++++++++++++++++++++++------------------------------- 2 files changed, 67 insertions(+), 77 deletions(-) create mode 100644 NOTICE diff --git a/NOTICE b/NOTICE new file mode 100644 index 00000000..a4d95340 --- /dev/null +++ b/NOTICE @@ -0,0 +1,9 @@ +MinIO Cloud Storage, (C) 2014-2023 MinIO, Inc. + +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 diff --git a/README.md b/README.md index be9e0c79..2739e6d1 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,32 @@ -# MinIO Python Client SDK for Amazon S3 Compatible Cloud Storage [![Slack](https://slack.min.io/slack?type=svg)](https://slack.min.io) [![Sourcegraph](https://sourcegraph.com/github.com/minio/minio-py/-/badge.svg)](https://sourcegraph.com/github.com/minio/minio-py?badge) [![Apache V2 License](https://img.shields.io/badge/license-Apache%20V2-blue.svg)](https://github.com/minio/minio-py/blob/master/LICENSE) +# 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) -The MinIO Python Client SDK provides straightforward APIs to access any Amazon S3 compatible object storage. +The MinIO Python Client SDK provides high level APIs to access any MinIO Object Storage or other Amazon S3 compatible service. + +This Quickstart Guide covers how to install the MinIO client SDK, connect to the object storage service, and create a sample file uploader. + +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 + +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. -This Quickstart Guide covers how to install the MinIO client SDK, connect to MinIO, and create a sample file uploader. For a complete list of APIs and examples, see the [Python Client API Reference](https://min.io/docs/minio/linux/developers/python/API.html) -These examples presume a working [3.7+ Python development environment](https://www.python.org/downloads/) and the [MinIO `mc` command line tool](https://min.io/docs/minio/linux/reference/minio-mc.html). +## Install the MinIO Python SDK -## 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 +### Using `pip` ```sh pip3 install minio ``` -### From GitHub +### Using Source From GitHub ```sh git clone https://github.com/minio/minio-py @@ -23,96 +34,75 @@ cd minio-py python setup.py install ``` -## Initialize a MinIO Client Object +## Create a MinIO Client -The MinIO client requires the following parameters to connect to an Amazon S3 compatible object storage: +To connect to the target service, create a MinIO client using the `Minio()` method with the following required parameters: -| Parameter | Description | -|------------|--------------------------------------------------------| -| Endpoint | URL to S3 service. | -| Access Key | Access key (user ID) of an account in the S3 service. | -| Secret Key | Secret key (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. | + +For example: ```py 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( - endpoint="play.min.io", - access_key="Q3AM3UQ867SPQQA43P2F", - secret_key="zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG", - ) - - print("MinIO Python SDK client initialized", client) -if __name__ == "__main__": - try: - main() - except S3Error as exc: - print("error occurred.", exc) +client = Minio("play.min.io", + access_key="Q3AM3UQ867SPQQA43P2F", + secret_key="zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG", +) ``` ## Example - File Uploader -This sample code connects to an object storage server, creates a bucket, and uploads a file to the bucket. -It uses the MinIO `play` server, a public MinIO cluster located at [https://play.min.io](https://play.min.io). - -The `play` server runs the latest stable version of MinIO and may be used for testing and development. -The access credentials shown in this example are open to the public and all data uploaded to `play` should be considered public and non-protected. - -### `file_uploader.py` - This example does the following: - Connects to the MinIO `play` server using the provided credentials. -- Creates a bucket named `minio-python-sdk-test-bucket`. -- Uploads a file named `minio-python-sdk-test-file.bin` from `/tmp`. -- Verifies the file was created using `mc ls`. +- 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 - -import os 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( - endpoint="play.min.io", + client = Minio("play.min.io", access_key="Q3AM3UQ867SPQQA43P2F", secret_key="zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG", ) - bucket_name = "minio-python-sdk-test-bucket" - original_filename = "minio-python-sdk-test-file.bin" - path = "/tmp" - destination_filename = "my-test-file.bin" + # 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(bucket_name) + print("Created bucket", bucket_name) else: print("Bucket", bucket_name, "already exists") # Upload the file, renaming it in the process - - original_full_path = os.path.join(path, original_filename) client.fput_object( - bucket_name, destination_filename, original_full_path, + bucket_name, destination_file, source_file, ) print( - original_full_path, "successfully uploaded as object", - destination_filename, "to bucket", bucket_name, + source_file, "successfully uploaded as object", + destination_file, "to bucket", bucket_name, ) - if __name__ == "__main__": try: main() @@ -120,37 +110,29 @@ if __name__ == "__main__": print("error occurred.", exc) ``` -**1. Create a test file containing data:** +To run this example: -You can do this with `dd` on Linux or macOS systems: +1. Create a file in `/tmp` named `test-file.txt`. + To use a different path or filename, modify the value of `source_file`. -```sh -dd if=/dev/urandom of=/tmp/minio-python-sdk-test-file.bin bs=2048 count=10 -``` - -or `fsutil` on Windows: - -```sh -fsutil file createnew "C:\Users\\Desktop\minio-python-sdk-test-file.bin" 20480 -``` - -**2. Run `file_uploader.py` with the following command:** +2. Run `file_uploader.py` with the following command: ```sh python file_uploader.py ``` -The output resembles the following: +If the bucket does not exist on the server, the output resembles the following: ```sh -/tmp/minio-python-sdk-test-file.bin successfully uploaded as object my-test-file.bin to bucket minio-python-sdk-test-bucket +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`:** +3. Verify the uploaded file with `mc ls`: ```sh -mc ls play/minio-python-sdk-test-bucket -[2023-11-03 22:18:54 UTC] 20KiB STANDARD my-test-file.bin +mc ls play/python-test-bucket +[2023-11-03 22:18:54 UTC] 20KiB STANDARD my-test-file.txt ``` ## More References @@ -168,7 +150,6 @@ mc ls play/minio-python-sdk-test-bucket ## 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) for more information. +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) -