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 be9e0c79a..2739e6d1c 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) -