diff --git a/NOTICE b/NOTICE new file mode 100644 index 000000000..a4d953402 --- /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 60ca12cee..2739e6d1c 100644 --- a/README.md +++ b/README.md @@ -1,19 +1,32 @@ -# 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 @@ -21,52 +34,75 @@ 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", + access_key="Q3AM3UQ867SPQQA43P2F", + secret_key="zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG", +) +``` + +## Example - File Uploader + +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 +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() @@ -74,23 +110,46 @@ if __name__ == "__main__": 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)