Skip to content

Commit

Permalink
rework text
Browse files Browse the repository at this point in the history
  • Loading branch information
@feorlen
feorlen committed Nov 7, 2023
1 parent 526810e commit 7c518d8
Show file tree
Hide file tree
Showing 2 changed files with 67 additions and 77 deletions.
9 changes: 9 additions & 0 deletions NOTICE
View file
Original file line number Diff line number Diff line change
@@ -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
135 changes: 58 additions & 77 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,156 +1,138 @@
# 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
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()
except S3Error as exc:
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\<username>\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
Expand All @@ -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)

0 comments on commit 7c518d8

Please sign in to comment.