From cef7cb5ac0d993b30deea8435939fe52a3c6efa6 Mon Sep 17 00:00:00 2001 From: "Bala.FA" Date: Mon, 30 Nov 2020 09:56:52 +0530 Subject: [PATCH 1/2] fix all examples and documentations --- CONTRIBUTING.md | 30 +- README.md | 237 +++----- docs/API.md | 508 ++++++++++-------- examples/bucket_exists.py | 20 +- examples/delete_bucket_encryption.py | 5 +- examples/delete_bucket_lifecycle.py | 5 +- examples/delete_bucket_notification.py | 5 +- examples/delete_bucket_policy.py | 25 + examples/delete_bucket_replication.py | 5 +- examples/delete_bucket_tags.py | 5 +- examples/delete_object_lock_config.py | 5 +- examples/delete_object_tags.py | 5 +- examples/disable_object_legal_hold.py | 5 +- examples/enable_object_legal_hold.py | 5 +- examples/fget_object.py | 15 +- examples/get_bucket_encryption.py | 5 +- examples/get_bucket_lifecycle.py | 5 +- examples/get_bucket_notification.py | 5 +- examples/get_bucket_policy.py | 19 +- examples/get_bucket_replication.py | 5 +- examples/get_bucket_tags.py | 5 +- examples/get_bucket_versioning.py | 5 +- examples/get_object.py | 17 +- examples/get_object_lock_config.py | 5 +- examples/get_object_retention.py | 5 +- examples/get_object_tags.py | 5 +- examples/is_object_legal_hold_enabled.py | 8 +- examples/list_buckets.py | 12 +- examples/list_objects.py | 49 +- ...ation.py => listen_bucket_notification.py} | 22 +- examples/make_bucket.py | 25 +- examples/minio_with_assume_role_provider.py | 2 +- examples/minio_with_aws_config_provider.py | 4 +- examples/minio_with_chained_provider.py | 4 +- examples/minio_with_client_grants_provider.py | 3 +- examples/minio_with_env_aws_provider.py | 4 +- examples/minio_with_env_minio_provider.py | 2 +- examples/minio_with_iam_aws_provider.py | 4 +- examples/minio_with_ldap_identity_provider.py | 2 +- ...minio_with_minio_client_config_provider.py | 2 +- examples/minio_with_web_identity_provider.py | 2 +- examples/presigned_post_policy.py | 8 +- examples/remove_bucket.py | 19 +- examples/remove_object.py | 25 +- examples/remove_objects.py | 27 +- examples/select_object_content.py | 6 +- examples/set_bucket_encryption.py | 5 +- examples/set_bucket_lifecycle.py | 13 +- examples/set_bucket_notification.py | 7 +- examples/set_bucket_policy.py | 164 ++---- examples/set_bucket_replication.py | 5 +- examples/set_bucket_tags.py | 5 +- examples/set_bucket_versioning.py | 5 +- examples/set_object_lock_config.py | 5 +- examples/set_object_retention.py | 5 +- examples/set_object_tags.py | 5 +- examples/stat_object.py | 15 +- minio/api.py | 296 ++++++---- 58 files changed, 822 insertions(+), 899 deletions(-) create mode 100644 examples/delete_bucket_policy.py rename examples/{listen_notification.py => listen_bucket_notification.py} (52%) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3c1fe44d8..2dd2a6d12 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,20 +1,10 @@ -### Setup your minio-py Github Repository -Fork [minio-py upstream](https://github.com/minio/minio-py/fork) source repository to your own personal repository. - -```sh -$ git clone https://github.com/$USER_ID/minio-py -$ cd minio-py -$ python setup.py install -... -``` - -### Developer Guidelines - -``minio-py`` welcomes your contribution. To make the process as seamless as possible, we ask for the following: - -* Go ahead and fork the project and make your changes. We encourage pull requests to discuss code changes. - - Fork it - - Create your feature branch (git checkout -b my-new-feature) - - Commit your changes (git commit -am 'Add some feature') - - Push to the branch (git push origin my-new-feature) - - Create new Pull Request +# Contributors Guide +``minio-py`` welcomes your contribution. Below steps can be followed to create a pull request. + +* Fork this minio-py repository into your account. +* Create a feature branch in your fork (`$ git checkout -b my-new-feature`). +* Hack, hack, hack... +* Run checks. (`$ make check`). +* Commit your changes (`$ git commit -am 'Add some feature'`). +* Push the feature branch into your fork (`$ git push origin -u my-new-feature`). +* Create new pull request to `master` branch. diff --git a/README.md b/README.md index f9068807f..5e20ab873 100644 --- a/README.md +++ b/README.md @@ -1,28 +1,19 @@ -# MinIO Python Library for Amazon S3 Compatible Cloud Storage [![Slack](https://slack.min.io/slack?type=svg)](https://slack.min.io) +# MinIO Python SDK for Amazon S3 Compatible Cloud Storage [![Slack](https://slack.min.io/slack?type=svg)](https://slack.min.io) -The MinIO Python Client SDK provides simple APIs to access any Amazon S3 compatible object storage server. +MinIO Python SDK is Simple Storage Service (aka S3) client to perform bucket and object operations to any Amazon S3 compatible object storage service. -This quickstart guide will show you how to install the client SDK and execute an example python program. For a complete list of APIs and examples, please take a look at the [Python Client API Reference](https://docs.min.io/docs/python-client-api-reference) documentation. - -This document assumes that you have a working [Python](https://www.python.org/downloads/) setup in place. +For a complete list of APIs and examples, please take a look at the [Python Client API Reference](https://docs.min.io/docs/python-client-api-reference) ## Minimum Requirements +Python 3.6 or higher. -- Python 3.6 or higher - -## Download from pip +## Download using pip ```sh pip install minio ``` -## Download from pip3 - -```sh -pip3 install minio -``` - -## Download from source +## Download source ```sh git clone https://github.com/minio/minio-py @@ -30,182 +21,76 @@ cd minio-py python setup.py install ``` -## Initialize MinIO Client - -You need four items in order to connect to MinIO object storage server. - -| Params | Description | -| :------- | :---- | -| endpoint | URL to object storage service. | -| access_key| Access key is like user ID that uniquely identifies your account. | -| secret_key| Secret key is the password to your account. | -|secure|Set this value to 'True' to enable secure (HTTPS) access.| - -```py -from minio import Minio -from minio.error import ResponseError - -minioClient = Minio('play.min.io', - access_key='Q3AM3UQ867SPQQA43P2F', - secret_key='zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG', - secure=True) -``` - -**NOTE on concurrent usage:** The `Minio` object is thread safe when using the Python `threading` library. Specifically, it is **NOT** safe to share it between multiple processes, for example when using `multiprocessing.Pool`. The solution is simply to create a new `Minio` object in each process, and not share it between processes. - - ## Quick Start Example - File Uploader -This example program connects to a MinIO object storage server, makes a bucket on the server and then uploads a file to the bucket. +This example program connects to an object storage server, makes a bucket on the server and then uploads a file to the bucket. + +You need three items in order to connect to an object storage server. -We will use the MinIO server running at [https://play.min.io](https://play.min.io) in this example. Feel free to use this service for testing and development. Access credentials shown in this example are open to the public. +| 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. | -#### file-uploader.py +This example uses MinIO server playground [https://play.min.io](https://play.min.io). Feel free to use this service for test and development. +### file_uploader.py ```py -# Import MinIO library. from minio import Minio -from minio.error import (ResponseError, BucketAlreadyOwnedByYou, - BucketAlreadyExists) - -# Initialize minioClient with an endpoint and access/secret keys. -minioClient = Minio('play.min.io', - access_key='Q3AM3UQ867SPQQA43P2F', - secret_key='zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG', - secure=True) - -# Make a bucket with the make_bucket API call. -try: - minioClient.make_bucket("maylogs", location="us-east-1") -except BucketAlreadyOwnedByYou as err: - pass -except BucketAlreadyExists as err: - pass -except ResponseError as err: - raise - -# Put an object 'pumaserver_debug.log' with contents from 'pumaserver_debug.log'. -try: - minioClient.fput_object('maylogs', 'pumaserver_debug.log', '/tmp/pumaserver_debug.log') -except ResponseError as err: - print(err) - +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", + access_key="Q3AM3UQ867SPQQA43P2F", + secret_key="zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG", + ) + + # Make 'asiatrip' bucket if not exist. + found = client.bucket_exists("asiatrip") + if not found: + client.make_bucket("asiatrip") + else: + print("Bucket 'asiatrip' already exists") + + # Upload '/home/user/Photos/asiaphotos.zip' as object name + # 'asiaphotos-2015.zip' to bucket 'asiatrip'. + client.put_object( + "asiatrip", "asiaphotos-2015.zip", "/home/user/Photos/asiaphotos.zip", + ) + print( + "'/home/user/Photos/asiaphotos.zip' is successfully uploaded as " + "object 'asiaphotos-2015.zip' to bucket 'asiatrip'." + ) + + +if __name__ == "__main__": + try: + main() + except S3Error as exc: + print("error occurred.", exc) ``` -#### Run file-uploader - -```bash -python file_uploader.py +#### Run File Uploader +```sh +$ python file_uploader.py +'/home/user/Photos/asiaphotos.zip' is successfully uploaded as object 'asiaphotos-2015.zip' to bucket 'asiatrip'. -mc ls play/maylogs/ -[2016-05-27 16:41:37 PDT] 12MiB pumaserver_debug.log +$ mc ls play/asiatrip/ +[2016-06-02 18:10:29 PDT] 82KiB asiaphotos-2015.zip ``` -## API Reference - -The full API Reference is available here. -* [Complete API Reference](https://docs.min.io/docs/python-client-api-reference) - -### API Reference : Bucket Operations - -* [`make_bucket`](https://docs.min.io/docs/python-client-api-reference#make_bucket) -* [`list_buckets`](https://docs.min.io/docs/python-client-api-reference#list_buckets) -* [`bucket_exists`](https://docs.min.io/docs/python-client-api-reference#bucket_exists) -* [`remove_bucket`](https://docs.min.io/docs/python-client-api-reference#remove_bucket) -* [`list_objects`](https://docs.min.io/docs/python-client-api-reference#list_objects) - -### API Reference : Bucket policy Operations - -* [`get_bucket_policy`](https://docs.min.io/docs/python-client-api-reference#get_bucket_policy) -* [`set_bucket_policy`](https://docs.min.io/docs/python-client-api-reference#set_bucket_policy) - -### API Reference : Bucket notification Operations - -* [`set_bucket_notification`](https://docs.min.io/docs/python-client-api-reference#set_bucket_notification) -* [`get_bucket_notification`](https://docs.min.io/docs/python-client-api-reference#get_bucket_notification) -* [`remove_all_bucket_notification`](https://docs.min.io/docs/python-client-api-reference#remove_all_bucket_notification) -* [`listen_bucket_notification`](https://docs.min.io/docs/python-client-api-reference#listen_bucket_notification) - -### API Reference : Default bucket encryption configuration Operations - -* [`put_bucket_encryption`](https://docs.min.io/docs/python-client-api-reference#put_bucket_encryption) -* [`get_bucket_encryption`](https://docs.min.io/docs/python-client-api-reference#get_bucket_encryption) -* [`delete_bucket_encryption`](https://docs.min.io/docs/python-client-api-reference#delete_bucket_encryption) - -### API Reference : File Object Operations - -* [`fput_object`](https://docs.min.io/docs/python-client-api-reference#fput_object) -* [`fget_object`](https://docs.min.io/docs/python-client-api-reference#fget_object) - -### API Reference : Object Operations - -* [`get_object`](https://docs.min.io/docs/python-client-api-reference#get_object) -* [`put_object`](https://docs.min.io/docs/python-client-api-reference#put_object) -* [`stat_object`](https://docs.min.io/docs/python-client-api-reference#stat_object) -* [`copy_object`](https://docs.min.io/docs/python-client-api-reference#copy_object) -* [`remove_object`](https://docs.min.io/docs/python-client-api-reference#remove_object) -* [`remove_objects`](https://docs.min.io/docs/python-client-api-reference#remove_objects) - -### API Reference : Presigned Operations - -* [`presigned_get_object`](https://docs.min.io/docs/python-client-api-reference#presigned_get_object) -* [`presigned_put_object`](https://docs.min.io/docs/python-client-api-reference#presigned_put_object) -* [`presigned_post_policy`](https://docs.min.io/docs/python-client-api-reference#presigned_post_policy) - -## Full Examples - -#### Full Examples : Bucket Operations - -* [make_bucket.py](https://github.com/minio/minio-py/blob/master/examples/make_bucket.py) -* [list_buckets.py](https://github.com/minio/minio-py/blob/master/examples/list_buckets.py) -* [bucket_exists.py](https://github.com/minio/minio-py/blob/master/examples/bucket_exists.py) -* [list_objects.py](https://github.com/minio/minio-py/blob/master/examples/list_objects.py) -* [remove_bucket.py](https://github.com/minio/minio-py/blob/master/examples/remove_bucket.py) - -#### Full Examples : Bucket policy Operations - -* [set_bucket_policy.py](https://github.com/minio/minio-py/blob/master/examples/set_bucket_policy.py) -* [get_bucket_policy.py](https://github.com/minio/minio-py/blob/master/examples/get_bucket_policy.py) - -#### Full Examples: Bucket notification Operations - -* [set_bucket_notification.py](https://github.com/minio/minio-py/blob/master/examples/set_bucket_notification.py) -* [get_bucket_notification.py](https://github.com/minio/minio-py/blob/master/examples/get_bucket_notification.py) -* [remove_all_bucket_notification.py](https://github.com/minio/minio-py/blob/master/examples/remove_all_bucket_notification.py) -* [listen_bucket_notification.py](https://github.com/minio/minio-py/blob/master/examples/listen_notification.py) - -#### Full Examples: Default bucket encryption configuration Operations - -* [put_bucket_encryption.py](https://github.com/minio/minio-py/blob/master/examples/put_bucket_encryption.py) -* [get_bucket_encryption.py](https://github.com/minio/minio-py/blob/master/examples/get_bucket_encryption.py) -* [delete_bucket_encryption.py](https://github.com/minio/minio-py/blob/master/examples/delete_bucket_encryption.py) - -#### Full Examples : File Object Operations - -* [fput_object.py](https://github.com/minio/minio-py/blob/master/examples/fput_object.py) -* [fget_object.py](https://github.com/minio/minio-py/blob/master/examples/fget_object.py) - -#### Full Examples : Object Operations - -* [get_object.py](https://github.com/minio/minio-py/blob/master/examples/get_object.py) -* [put_object.py](https://github.com/minio/minio-py/blob/master/examples/put_object.py) -* [stat_object.py](https://github.com/minio/minio-py/blob/master/examples/stat_object.py) -* [copy_object.py](https://github.com/minio/minio-py/blob/master/examples/copy_object.py) -* [remove_object.py](https://github.com/minio/minio-py/blob/master/examples/remove_object.py) -* [remove_objects.py](https://github.com/minio/minio-py/blob/master/examples/remove_objects.py) - -#### Full Examples : Presigned Operations - -* [presigned_get_object.py](https://github.com/minio/minio-py/blob/master/examples/presigned_get_object.py) -* [presigned_put_object.py](https://github.com/minio/minio-py/blob/master/examples/presigned_put_object.py) -* [presigned_post_policy.py](https://github.com/minio/minio-py/blob/master/examples/presigned_post_policy.py) +## More References +* [Python Client API Reference](https://docs.min.io/docs/python-client-api-reference) +* [Examples](https://github.com/minio/minio-py/tree/release/examples) ## Explore Further - * [Complete Documentation](https://docs.min.io) -* [MinIO Python SDK API Reference](https://docs.min.io/docs/python-client-api-reference) ## Contribute - -[Contributors Guide](https://github.com/minio/minio-py/blob/master/CONTRIBUTING.md) +Please refer [Contributors Guide](https://github.com/minio/minio-py/blob/release/CONTRIBUTING.md) [![PYPI](https://img.shields.io/pypi/v/minio.svg)](https://pypi.python.org/pypi/minio) diff --git a/docs/API.md b/docs/API.md index 7aadb8e96..03a3cc53a 100644 --- a/docs/API.md +++ b/docs/API.md @@ -1,32 +1,65 @@ # Python Client API Reference [![Slack](https://slack.min.io/slack?type=svg)](https://slack.min.io) -## Initialize MinIO Client object. +## 1. Constructor -## MinIO +### Minio(endpoint, access_key=None, secret_key=None, session_token=None, secure=True, region=None, http_client=None, credentials=None) +| | +|---------------------------------------------------------------------------------------------------------------------------------------| +| `Minio(endpoint, access_key=None, secret_key=None, session_token=None, secure=True, region=None, http_client=None, credentials=None)` | +| Initializes a new client object. | -```py -from minio import Minio -from minio.error import ResponseError +__Parameters__ + +| Param | Type | Description | +|:----------------|:----------------------------------|:---------------------------------------------------------------------------------| +| `endpoint` | _str_ | Hostname of a S3 service. | +| `access_key` | _str_ | (Optional) Access key (aka user ID) of your account in S3 service. | +| `secret_key` | _str_ | (Optional) Secret Key (aka password) of your account in S3 service. | +| `session_token` | _str_ | (Optional) Session token of your account in S3 service. | +| `secure` | _bool_ | (Optional) Flag to indicate to use secure (TLS) connection to S3 service or not. | +| `region` | _str_ | (Optional) Region name of buckets in S3 service. | +| `http_client` | _urllib3.poolmanager.PoolManager_ | (Optional) Customized HTTP client. | +| `credentials` | _minio.credentials.Credentials_ | (Optional) Credentials of your account in S3 service. | -minioClient = Minio( - 'play.min.io', - access_key='Q3AM3UQ867SPQQA43P2F', - secret_key='zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG', - secure=True, -) -``` -## AWS S3 +**NOTE on concurrent usage:** `Minio` object is thread safe when using the Python `threading` library. Specifically, it is **NOT** safe to share it between multiple processes, for example when using `multiprocessing.Pool`. The solution is simply to create a new `Minio` object in each process, and not share it between processes. + +__Example__ ```py from minio import Minio -from minio.error import ResponseError -s3Client = Minio( - 's3.amazonaws.com', - access_key='YOUR-ACCESSKEYID', - secret_key='YOUR-SECRETACCESSKEY', - secure=True, +# Create client with anonymous access. +client = Minio("play.min.io") + +# Create client with access and secret key. +client = Minio("s3.amazonaws.com", "ACCESS-KEY", "SECRET-KEY") + +# Create client with access key and secret key with specific region. +client = Minio( + "play.minio.io:9000", + access_key="Q3AM3UQ867SPQQA43P2F", + secret_key="zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG", + region="my-region", +) + +# Create client with custom HTTP client using proxy server. +import urllib3 +client = Minio( + "SERVER:PORT", + access_key="ACCESS_KEY", + secret_key="SECRET_KEY", + secure=True, + http_client=urllib3.ProxyManager( + "https://PROXYSERVER:PROXYPORT/", + timeout=urllib3.Timeout.DEFAULT_TIMEOUT, + cert_reqs="CERT_REQUIRED", + retries=urllib3.Retry( + total=5, + backoff_factor=0.2, + status_forcelist=[500, 502, 503, 504], + ), + ), ) ``` @@ -62,87 +95,6 @@ s3Client = Minio( | [`get_object_lock_config`](#get_object_lock_config) | | | [`set_object_lock_config`](#set_object_lock_config) | | -## 1. Constructor - - - -### Minio(endpoint, access_key=None, secret_key=None, session_token=None, secure=True, region=None, http_client=None, credentials=None) -| | -|---------------------------------------------------------------------------------------------------------------------------------------| -| `Minio(endpoint, access_key=None, secret_key=None, session_token=None, secure=True, region=None, http_client=None, credentials=None)` | -| Initializes a new client object. | - -__Parameters__ - -| Param | Type | Description | -|:----------------|:----------------------------------|:---------------------------------------------------------------------------------| -| `endpoint` | _str_ | Hostname of a S3 service. | -| `access_key` | _str_ | (Optional) Access key (aka user ID) of your account in S3 service. | -| `secret_key` | _str_ | (Optional) Secret Key (aka password) of your account in S3 service. | -| `session_token` | _str_ | (Optional) Session token of your account in S3 service. | -| `secure` | _bool_ | (Optional) Flag to indicate to use secure (TLS) connection to S3 service or not. | -| `region` | _str_ | (Optional) Region name of buckets in S3 service. | -| `http_client` | _urllib3.poolmanager.PoolManager_ | (Optional) Customized HTTP client. | -| `credentials` | _minio.credentials.Credentials_ | (Optional) Credentials of your account in S3 service. | - - -**NOTE on concurrent usage:** The `Minio` object is thread safe when using the Python `threading` library. Specifically, it is **NOT** safe to share it between multiple processes, for example when using `multiprocessing.Pool`. The solution is simply to create a new `Minio` object in each process, and not share it between processes. - -__Example__ - -### MinIO - -```py -from minio import Minio -from minio.error import ResponseError - -minioClient = Minio( - 'play.min.io', - access_key='Q3AM3UQ867SPQQA43P2F', - secret_key='zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG', -) -``` - -> NOTE: If there is a corporate proxy, specify a custom httpClient using *urllib3.ProxyManager* as shown below: - -```py -from minio import Minio -from minio.error import ResponseError -import urllib3 - -httpClient = urllib3.ProxyManager( - 'https://proxy_host.sampledomain.com:8119/', - timeout=urllib3.Timeout.DEFAULT_TIMEOUT, - cert_reqs='CERT_REQUIRED', - retries=urllib3.Retry( - total=5, - backoff_factor=0.2, - status_forcelist=[500, 502, 503, 504], - ) -) - -minioClient = Minio( - 'your_hostname.sampledomain.com:9000', - access_key='ACCESS_KEY', - secret_key='SECRET_KEY', - secure=True, - http_client=httpClient, -) -``` - -### AWS S3 - -```py -from minio import Minio -from minio.error import ResponseError - -s3Client = Minio( - 's3.amazonaws.com', - access_key='ACCESS_KEY', - secret_key='SECRET_KEY', -) -``` - ## 2. Bucket operations @@ -162,9 +114,14 @@ __Parameters__ __Example__ ```py -minio.make_bucket('foo') -minio.make_bucket('foo', 'us-west-1') -minio.make_bucket('foo', 'us-west-1', object_lock=True) +# Create bucket. +client.make_bucket("my-bucket") + +# Create bucket on specific region. +client.make_bucket("my-bucket", "us-west-1") + +# Create bucket with object-lock feature on specific region. +client.make_bucket("my-bucket", "eu-west-2", object_lock=True) ``` @@ -175,15 +132,15 @@ List information of all accessible buckets. __Parameters__ -| Return | -|:-----------------------------------------| -| An iterator contains bucket information. | +| Return | +|:-----------------| +| List of _Bucket_ | __Example__ ```py -bucket_list = minio.list_buckets() -for bucket in bucket_list: +buckets = client.list_buckets() +for bucket in buckets: print(bucket.name, bucket.creation_date) ``` @@ -202,11 +159,10 @@ __Parameters__ __Example__ ```py -found = minio.bucket_exists("my-bucketname") -if found: - print("my-bucketname exists") +if client.bucket_exists("my-bucket"): + print("my-bucket exists") else: - print("my-bucketname does not exist") + print("my-bucket does not exist") ``` @@ -224,63 +180,66 @@ __Parameters__ __Example__ ```py -minio.remove_bucket("my-bucketname") +client.remove_bucket("my-bucket") ``` -### list_objects(bucket_name, prefix=None, recursive=False, include_version=False) +### list_objects(bucket_name, prefix=None, recursive=False, start_after=None, include_user_meta=False, include_version=False, use_api_v1=False) -Lists object information of a bucket using S3 API version 1, optionally for prefix recursively. +Lists object information of a bucket. __Parameters__ -| Param | Type | Description | -|:------------------|:-------|:-----------------------------------------------------| -| `bucket_name` | _str_ | Name of the bucket. | -| `prefix` | _str_ | Object name starts with prefix. | -| `recursive` | _bool_ | List recursively than directory structure emulation. | -| `include_version` | _bool_ | Flag to control whether include object versions. | +| Param | Type | Description | +|:--------------------|:-------|:---------------------------------------------------------| +| `bucket_name` | _str_ | Name of the bucket. | +| `prefix` | _str_ | Object name starts with prefix. | +| `recursive` | _bool_ | List recursively than directory structure emulation. | +| `start_after` | _str_ | List objects after this key name. | +| `include_user_meta` | _bool_ | MinIO specific flag to control to include user metadata. | +| `include_version` | _bool_ | Flag to control whether include object versions. | +| `use_api_v1` | _bool_ | Flag to control to use ListObjectV1 S3 API or not. | __Return Value__ -| Return | -|:----------------------------------------------------------| -| An iterator contains object information as _minio.Object_ | +| Return | +|:------------------------| +| An iterator of _Object_ | __Example__ ```py # List objects information. -objects = minio.list_objects('foo') -for object in objects: - print(object) +objects = client.list_objects("my-bucket") +for obj in objects: + print(obj) -# List objects information whose names starts with 'hello/'. -objects = minio.list_objects('foo', prefix='hello/') -for object in objects: - print(object) +# List objects information whose names starts with "my/prefix/". +objects = client.list_objects("my-bucket", prefix="my/prefix/") +for obj in objects: + print(obj) # List objects information recursively. -objects = minio.list_objects('foo', recursive=True) -for object in objects: - print(object) +objects = client.list_objects("my-bucket", recursive=True) +for obj in objects: + print(obj) # List objects information recursively whose names starts with -# 'hello/'. -objects = minio.list_objects( - 'foo', prefix='hello/', recursive=True, +# "my/prefix/". +objects = client.list_objects( + "my-bucket", prefix="my/prefix/", recursive=True, ) -for object in objects: - print(object) +for obj in objects: + print(obj) # List objects information recursively after object name -# 'hello/world/1'. -objects = minio.list_objects( - 'foo', recursive=True, start_after='hello/world/1', +# "my/prefix/world/1". +objects = client.list_objects( + "my-bucket", recursive=True, start_after="my/prefix/world/1", ) -for object in objects: - print(object) +for obj in objects: + print(obj) ``` @@ -304,7 +263,7 @@ __Return Value__ __Example__ ```py -config = minio.get_bucket_policy("my-bucketname") +policy = client.get_bucket_policy("my-bucket") ``` @@ -323,7 +282,55 @@ __Parameters__ __Example__ ```py -minio.set_bucket_policy("my-bucketname", config) +# Example anonymous read-only bucket policy. +policy = { + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Principal": {"AWS": "*"}, + "Action": ["s3:GetBucketLocation", "s3:ListBucket"], + "Resource": "arn:aws:s3:::my-bucket", + }, + { + "Effect": "Allow", + "Principal": {"AWS": "*"}, + "Action": "s3:GetObject", + "Resource": "arn:aws:s3:::my-bucket/*", + }, + ], +} +client.set_bucket_policy("my-bucket", json.dumps(policy)) + +# Example anonymous read-write bucket policy. +policy = { + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Principal": {"AWS": "*"}, + "Action": [ + "s3:GetBucketLocation", + "s3:ListBucket", + "s3:ListBucketMultipartUploads", + ], + "Resource": "arn:aws:s3:::my-bucket", + }, + { + "Effect": "Allow", + "Principal": {"AWS": "*"}, + "Action": [ + "s3:GetObject", + "s3:PutObject", + "s3:DeleteObject", + "s3:ListMultipartUploadParts", + "s3:AbortMultipartUpload", + ], + "Resource": "arn:aws:s3:::my-bucket/images/*", + }, + ], +} +client.set_bucket_policy("my-bucket", json.dumps(policy)) ``` @@ -341,7 +348,7 @@ __Parameters__ __Example__ ```py -minio.delete_bucket_policy("my-bucketname") +client.delete_bucket_policy("my-bucket") ``` @@ -365,7 +372,7 @@ __Return Value__ __Example__ ```py -config = minio.get_bucket_notification("my-bucketname") +config = client.get_bucket_notification("my-bucket") ``` @@ -388,13 +395,13 @@ config = NotificationConfig( queue_config_list=[ QueueConfig( "QUEUE-ARN-OF-THIS-BUCKET", - ['s3:ObjectCreated:*'], + ["s3:ObjectCreated:*"], config_id="1", prefix_filter_rule=PrefixFilterRule("abc"), ), ], ) -minio.set_bucket_notification("my-bucketname", config) +client.set_bucket_notification("my-bucket", config) ``` @@ -412,12 +419,12 @@ __Parameters__ __Example__ ```py -minio.delete_bucket_notification("my-bucketname") +client.delete_bucket_notification("my-bucket") ``` -### listen_bucket_notification(bucket_name, prefix='', suffix='', events=('s3:ObjectCreated:*', 's3:ObjectRemoved:*', 's3:ObjectAccessed:*')) +### listen_bucket_notification(bucket_name, prefix='', suffix='', events=('s3:ObjectCreated:\*', 's3:ObjectRemoved:\*', 's3:ObjectAccessed:\*')) Listen events of object prefix and suffix of a bucket. Caller should iterate returned iterator to read new events. @@ -430,13 +437,20 @@ __Parameters__ | `suffix` | _str_ | Listen events of object ends with suffix. | | `events` | _list_ | Events to listen. | +__Return Value__ + +| Param | +|:------------------------------------| +| Iterator of event records as _dict_ | + ```py -iter = minio.listen_bucket_notification( - "my-bucketname", - events=('s3:ObjectCreated:*', 's3:ObjectAccessed:*'), +events = client.listen_bucket_notification( + "my-bucket", + prefix="my-prefix/", + events=["s3:ObjectCreated:*", "s3:ObjectRemoved:*"], ) -for events in iter: - print(events) +for event in events: + print(event) ``` @@ -460,7 +474,7 @@ __Return Value__ __Example__ ```py -config = minio.get_bucket_encryption("my-bucketname") +config = client.get_bucket_encryption("my-bucket") ``` @@ -479,8 +493,8 @@ __Parameters__ __Example__ ```py -minio.set_bucket_encryption( - "my-bucketname", SSEConfig(Rule.new_sse_s3_rule()), +client.set_bucket_encryption( + "my-bucket", SSEConfig(Rule.new_sse_s3_rule()), ) ``` @@ -499,7 +513,7 @@ __Parameters__ __Example__ ```py -minio.delete_bucket_encryption("my-bucketname") +client.delete_bucket_encryption("my-bucket") ``` @@ -517,7 +531,7 @@ __Parameters__ __Example__ ```py -config = minio.get_bucket_versioning("my-bucketname") +config = client.get_bucket_versioning("my-bucket") print(config.status) ``` @@ -537,7 +551,7 @@ __Parameters__ __Example__ ```py -minio.set_bucket_versioning("my-bucketname", VersioningConfig(ENABLED)) +client.set_bucket_versioning("my-bucket", VersioningConfig(ENABLED)) ``` @@ -555,7 +569,7 @@ __Parameters__ __Example__ ```py -minio.delete_bucket_replication("my-bucketname") +client.delete_bucket_replication("my-bucket") ``` @@ -577,7 +591,7 @@ __Parameters__ __Example__ ```py -config = minio.get_bucket_replication("my-bucketname") +config = client.get_bucket_replication("my-bucket") ``` @@ -618,7 +632,7 @@ config = ReplicationConfig( ), ], ) -minio.set_bucket_replication("my-bucketname", config) +client.set_bucket_replication("my-bucket", config) ``` @@ -636,7 +650,7 @@ __Parameters__ __Example__ ```py -minio.delete_bucket_lifecycle("my-bucketname") +client.delete_bucket_lifecycle("my-bucket") ``` @@ -659,7 +673,7 @@ __Parameters__ __Example__ ```py -config = minio.get_bucket_lifecycle("my-bucketname") +config = client.get_bucket_lifecycle("my-bucket") ``` @@ -694,7 +708,7 @@ config = LifecycleConfig( ), ], ) -minio.set_bucket_lifecycle("my-bucketname", config) +client.set_bucket_lifecycle("my-bucket", config) ``` @@ -712,7 +726,7 @@ __Parameters__ __Example__ ```py -minio.delete_bucket_tags("my-bucketname") +client.delete_bucket_tags("my-bucket") ``` @@ -734,7 +748,7 @@ __Parameters__ __Example__ ```py -tags = minio.get_bucket_tags("my-bucketname") +tags = client.get_bucket_tags("my-bucket") ``` @@ -756,7 +770,7 @@ __Example__ tags = Tags.new_bucket_tags() tags["Project"] = "Project One" tags["User"] = "jsmith" -client.set_bucket_tags("my-bucketname", tags) +client.set_bucket_tags("my-bucket", tags) ``` @@ -774,7 +788,7 @@ __Parameters__ __Example__ ```py -minio.delete_object_lock_config("my-bucketname") +client.delete_object_lock_config("my-bucket") ``` @@ -796,7 +810,7 @@ __Parameters__ __Example__ ```py -config = minio.get_object_lock_config("my-bucketname") +config = client.get_object_lock_config("my-bucket") ``` @@ -816,7 +830,7 @@ __Example__ ```py config = ObjectLockConfig(GOVERNANCE, 15, DAYS) -minio.set_object_lock_config("my-bucketname", config) +client.set_object_lock_condig("my-bucket", config) ``` ## 3. Object operations @@ -849,18 +863,42 @@ __Return Value__ __Example__ ```py -// Get entire object data. - try: - response = minio.get_object('foo', 'bar') - // Read data from response. +# Get data of an object. +try: + response = client.get_object("my-bucket", "my-object") + # Read data from response. +finally: + response.close() + response.release_conn() + +# Get data of an object of version-ID. +try: + response = client.get_object( + "my-bucket", "my-object", + version_id="dfbd25b3-abec-4184-a4e8-5a35a5c1174d", + ) + # Read data from response. +finally: + response.close() + response.release_conn() + +# Get data of an object from offset and length. +try: + response = client.get_object( + "my-bucket", "my-object", offset=512, length=1024, + ) + # Read data from response. finally: response.close() response.release_conn() -// Get object data for offset/length. +# Get data of an SSE-C encrypted object. try: - response = minio.get_object('foo', 'bar', 2, 4) - // Read data from response. + response = client.get_object( + "my-bucket", "my-object", + ssec=SseCustomerKey(b"32byteslongsecretkeymustprovided"), + ) + # Read data from response. finally: response.close() response.release_conn() @@ -868,7 +906,7 @@ finally: -### select_object_content(bucket_name, object_name, opts) +### select_object_content(bucket_name, object_name, request) Select content of an object by SQL expression. @@ -931,9 +969,19 @@ __Return Value__ __Example__ ```py -minio.fget_object('foo', 'bar', 'localfile') -minio.fget_object( - 'foo', 'bar', 'localfile', version_id='VERSION-ID', +# Download data of an object. +client.fget_object("my-bucket", "my-object", "my-filename") + +# Download data of an object of version-ID. +client.fget_object( + "my-bucket", "my-object", "my-filename", + version_id="dfbd25b3-abec-4184-a4e8-5a35a5c1174d", +) + +# Download data of an SSE-C encrypted object. +client.fget_object( + "my-bucket", "my-object", "my-filename", + ssec=SseCustomerKey(b"32byteslongsecretkeymustprovided"), ) ``` @@ -1343,14 +1391,42 @@ __Parameters__ __Return Value__ -| Return | -|:---------| +| Return | +|:-------------------------------| | Object information as _Object_ | __Example__ ```py -stat = minio.stat_object("my-bucketname", "my-objectname") +# Get object information. +result = client.stat_object("my-bucket", "my-object") +print( + "last-modified: {0}, size: {1}".format( + result.last_modified, result.size, + ), +) + +# Get object information of version-ID. +result = client.stat_object( + "my-bucket", "my-object", + version_id="dfbd25b3-abec-4184-a4e8-5a35a5c1174d", +) +print( + "last-modified: {0}, size: {1}".format( + result.last_modified, result.size, + ), +) + +# Get SSE-C encrypted object information. +result = client.stat_object( + "my-bucket", "my-object", + ssec=SseCustomerKey(b"32byteslongsecretkeymustprovided"), +) +print( + "last-modified: {0}, size: {1}".format( + result.last_modified, result.size, + ), +) ``` @@ -1370,11 +1446,13 @@ __Parameters__ __Example__ ```py -minio.remove_object("my-bucketname", "my-objectname") -minio.remove_object( - "my-bucketname", - "my-objectname", - version_id="13f88b18-8dcd-4c83-88f2-8631fdb6250c", +# Remove object. +client.remove_object("my-bucket", "my-object") + +# Remove version of an object. +client.remove_object( + "my-bucket", "my-object", + version_id="dfbd25b3-abec-4184-a4e8-5a35a5c1174d", ) ``` @@ -1401,17 +1479,24 @@ __Return Value__ __Example__ ```py -errors = minio.remove_objects( - "my-bucketname", +# Remove list of objects. +errors = client.remove_objects( + "my-bucket", [ - DeleteObject("my-objectname1"), - DeleteObject("my-objectname2"), - DeleteObject( - "my-objectname3", - "13f88b18-8dcd-4c83-88f2-8631fdb6250c", - ), + DeleteObject("my-object1"), + DeleteObject("my-object2"), + DeleteObject("my-object3", "13f88b18-8dcd-4c83-88f2-8631fdb6250c"), ], ) +for error in errors: + print("error occured when deleting object", error) + +# Remove a prefix recursively. +delete_object_list = map( + lambda x: DeleteObject(x.object_name), + client.list_objects("my-bucket", "my/prefix/", recursive=True), +) +errors = client.remove_objects("my-bucket", delete_object_list) for error in errors: print("error occured when deleting object", error) ``` @@ -1433,7 +1518,7 @@ __Parameters__ __Example__ ```py -minio.delete_object_tags("my-bucketname", "my-objectname") +client.delete_object_tags("my-bucket", "my-object") ``` @@ -1457,7 +1542,7 @@ __Parameters__ __Example__ ```py -tags = minio.get_object_tags("my-bucketname", "my-objectname") +tags = client.get_object_tags("my-bucket", "my-object") ``` @@ -1481,7 +1566,7 @@ __Example__ tags = Tags.new_object_tags() tags["Project"] = "Project One" tags["User"] = "jsmith" -client.set_object_tags("my-bucketname", "my-objectname", tags) +client.set_object_tags("my-bucket", "my-object", tags) ``` @@ -1501,7 +1586,7 @@ __Parameters__ __Example__ ```py -minio.enable_object_legal_hold("my-bucketname", "my-objectname") +client.enable_object_legal_hold("my-bucket", "my-object") ``` @@ -1521,7 +1606,7 @@ __Parameters__ __Example__ ```py -minio.disable_object_legal_hold("my-bucketname", "my-objectname") +client.disable_object_legal_hold("my-bucket", "my-object") ``` @@ -1541,7 +1626,10 @@ __Parameters__ __Example__ ```py -minio.is_object_legal_hold_enabled("my-bucketname", "my-objectname") +if client.is_object_legal_hold_enabled("my-bucket", "my-object"): + print("legal hold is enabled on my-object") +else: + print("legal hold is not enabled on my-object") ``` @@ -1568,7 +1656,7 @@ __Return Value__ __Example__ ```py -config = minio.get_object_retention("my-bucketname", "my-objectname") +config = client.get_object_retention("my-bucket", "my-object") ``` @@ -1590,7 +1678,7 @@ __Example__ ```py config = Retention(GOVERNANCE, datetime.utcnow() + timedelta(days=10)) -minio.set_object_retention("my-bucketname", "my-objectname", config) +client.set_object_retention("my-bucket", "my-object", config) ``` diff --git a/examples/bucket_exists.py b/examples/bucket_exists.py index a07d647a5..13a7df887 100644 --- a/examples/bucket_exists.py +++ b/examples/bucket_exists.py @@ -14,17 +14,15 @@ # See the License for the specific language governing permissions and # limitations under the License. -# Note: YOUR-ACCESSKEYID, YOUR-SECRETACCESSKEY and my-bucketname are -# dummy values, please replace them with original values. - from minio import Minio -from minio.error import ResponseError -client = Minio('s3.amazonaws.com', - access_key='YOUR-ACCESSKEYID', - secret_key='YOUR-SECRETACCESSKEY') +client = Minio( + "play.min.io", + access_key="Q3AM3UQ867SPQQA43P2F", + secret_key="zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG", +) -try: - print(client.bucket_exists('my-bucketname')) -except ResponseError as err: - print(err) +if client.bucket_exists("my-bucket"): + print("my-bucket exists") +else: + print("my-bucket does not exist") diff --git a/examples/delete_bucket_encryption.py b/examples/delete_bucket_encryption.py index 97429b87a..324ea7c97 100644 --- a/examples/delete_bucket_encryption.py +++ b/examples/delete_bucket_encryption.py @@ -14,9 +14,6 @@ # See the License for the specific language governing permissions and # limitations under the License. -# Note: YOUR-ACCESSKEYID, YOUR-SECRETACCESSKEY and my-bucketname are -# dummy values, please replace them with original values. - from minio import Minio client = Minio( @@ -25,4 +22,4 @@ secret_key="zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG", ) -client.delete_bucket_encryption("my-bucketname") +client.delete_bucket_encryption("my-bucket") diff --git a/examples/delete_bucket_lifecycle.py b/examples/delete_bucket_lifecycle.py index ececb49d3..82e3d28aa 100644 --- a/examples/delete_bucket_lifecycle.py +++ b/examples/delete_bucket_lifecycle.py @@ -14,9 +14,6 @@ # See the License for the specific language governing permissions and # limitations under the License. -# Note: YOUR-ACCESSKEYID, YOUR-SECRETACCESSKEY and my-bucketname are -# dummy values, please replace them with original values. - from minio import Minio client = Minio( @@ -25,4 +22,4 @@ secret_key="zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG", ) -client.delete_bucket_lifecycle("my-bucketname") +client.delete_bucket_lifecycle("my-bucket") diff --git a/examples/delete_bucket_notification.py b/examples/delete_bucket_notification.py index 190aa1f36..b1e3f5ed7 100644 --- a/examples/delete_bucket_notification.py +++ b/examples/delete_bucket_notification.py @@ -14,9 +14,6 @@ # See the License for the specific language governing permissions and # limitations under the License. -# Note: YOUR-ACCESSKEYID, YOUR-SECRETACCESSKEY and my-bucketname are -# dummy values, please replace them with original values. - from minio import Minio client = Minio( @@ -25,4 +22,4 @@ secret_key="zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG", ) -client.delete_bucket_notification("my-bucketname") +client.delete_bucket_notification("my-bucket") diff --git a/examples/delete_bucket_policy.py b/examples/delete_bucket_policy.py new file mode 100644 index 000000000..0c9853830 --- /dev/null +++ b/examples/delete_bucket_policy.py @@ -0,0 +1,25 @@ +# -*- coding: utf-8 -*- +# MinIO Python Library for Amazon S3 Compatible Cloud Storage. +# Copyright (C) 2020 MinIO, Inc. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +from minio import Minio + +client = Minio( + "play.min.io", + access_key="Q3AM3UQ867SPQQA43P2F", + secret_key="zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG", +) + +client.delete_bucket_policy("my-bucket") diff --git a/examples/delete_bucket_replication.py b/examples/delete_bucket_replication.py index e28f04558..a7ebaeb26 100644 --- a/examples/delete_bucket_replication.py +++ b/examples/delete_bucket_replication.py @@ -14,9 +14,6 @@ # See the License for the specific language governing permissions and # limitations under the License. -# Note: YOUR-ACCESSKEYID, YOUR-SECRETACCESSKEY and my-bucketname are -# dummy values, please replace them with original values. - from minio import Minio client = Minio( @@ -25,4 +22,4 @@ secret_key="zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG", ) -client.delete_bucket_replication("my-bucketname") +client.delete_bucket_replication("my-bucket") diff --git a/examples/delete_bucket_tags.py b/examples/delete_bucket_tags.py index f77672628..ab4dbbcdb 100644 --- a/examples/delete_bucket_tags.py +++ b/examples/delete_bucket_tags.py @@ -14,9 +14,6 @@ # See the License for the specific language governing permissions and # limitations under the License. -# Note: YOUR-ACCESSKEYID, YOUR-SECRETACCESSKEY and my-bucketname are -# dummy values, please replace them with original values. - from minio import Minio client = Minio( @@ -25,4 +22,4 @@ secret_key="zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG", ) -client.delete_bucket_tags("my-bucketname") +client.delete_bucket_tags("my-bucket") diff --git a/examples/delete_object_lock_config.py b/examples/delete_object_lock_config.py index 9561afaba..7bb333b8b 100644 --- a/examples/delete_object_lock_config.py +++ b/examples/delete_object_lock_config.py @@ -14,9 +14,6 @@ # See the License for the specific language governing permissions and # limitations under the License. -# Note: YOUR-ACCESSKEYID, YOUR-SECRETACCESSKEY and my-bucketname are -# dummy values, please replace them with original values. - from minio import Minio client = Minio( @@ -25,4 +22,4 @@ secret_key="zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG", ) -client.delete_object_lock_config("my-bucketname") +client.delete_object_lock_config("my-bucket") diff --git a/examples/delete_object_tags.py b/examples/delete_object_tags.py index 79cf31e59..66a22edf3 100644 --- a/examples/delete_object_tags.py +++ b/examples/delete_object_tags.py @@ -14,9 +14,6 @@ # See the License for the specific language governing permissions and # limitations under the License. -# Note: YOUR-ACCESSKEYID, YOUR-SECRETACCESSKEY and my-bucketname are -# dummy values, please replace them with original values. - from minio import Minio client = Minio( @@ -25,4 +22,4 @@ secret_key="zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG", ) -client.delete_object_tags("my-bucketname", "my-objectname") +client.delete_object_tags("my-bucket", "my-object") diff --git a/examples/disable_object_legal_hold.py b/examples/disable_object_legal_hold.py index 70db87abf..ea07c4520 100644 --- a/examples/disable_object_legal_hold.py +++ b/examples/disable_object_legal_hold.py @@ -14,9 +14,6 @@ # See the License for the specific language governing permissions and # limitations under the License. -# Note: YOUR-ACCESSKEYID, YOUR-SECRETACCESSKEY and my-bucketname are -# dummy values, please replace them with original values. - from minio import Minio client = Minio( @@ -25,4 +22,4 @@ secret_key="zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG", ) -client.disable_object_legal_hold("my-bucketname", "my-objectname") +client.disable_object_legal_hold("my-bucket", "my-object") diff --git a/examples/enable_object_legal_hold.py b/examples/enable_object_legal_hold.py index fd77afc70..d78706bd6 100644 --- a/examples/enable_object_legal_hold.py +++ b/examples/enable_object_legal_hold.py @@ -14,9 +14,6 @@ # See the License for the specific language governing permissions and # limitations under the License. -# Note: YOUR-ACCESSKEYID, YOUR-SECRETACCESSKEY and my-bucketname are -# dummy values, please replace them with original values. - from minio import Minio client = Minio( @@ -25,4 +22,4 @@ secret_key="zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG", ) -client.enable_object_legal_hold("my-bucketname", "my-objectname") +client.enable_object_legal_hold("my-bucket", "my-object") diff --git a/examples/fget_object.py b/examples/fget_object.py index 36dc6a2fc..eb157fd53 100644 --- a/examples/fget_object.py +++ b/examples/fget_object.py @@ -14,29 +14,26 @@ # See the License for the specific language governing permissions and # limitations under the License. -# Note: YOUR-ACCESSKEYID, YOUR-SECRETACCESSKEY, my-bucketname and my-objectname -# are dummy values, please replace them with original values. - from minio import Minio from minio.sse import SseCustomerKey client = Minio( - "s3.amazonaws.com", - access_key="YOUR-ACCESSKEYID", - secret_key="YOUR-SECRETACCESSKEY", + "play.min.io", + access_key="Q3AM3UQ867SPQQA43P2F", + secret_key="zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG", ) # Download data of an object. -client.fget_object("my-bucketname", "my-objectname", "my-filename") +client.fget_object("my-bucket", "my-object", "my-filename") # Download data of an object of version-ID. client.fget_object( - "my-bucketname", "my-objectname", "my-filename", + "my-bucket", "my-object", "my-filename", version_id="dfbd25b3-abec-4184-a4e8-5a35a5c1174d", ) # Download data of an SSE-C encrypted object. client.fget_object( - "my-bucketname", "my-objectname", "my-filename", + "my-bucket", "my-object", "my-filename", ssec=SseCustomerKey(b"32byteslongsecretkeymustprovided"), ) diff --git a/examples/get_bucket_encryption.py b/examples/get_bucket_encryption.py index ff502c354..8dd8efde7 100644 --- a/examples/get_bucket_encryption.py +++ b/examples/get_bucket_encryption.py @@ -14,9 +14,6 @@ # See the License for the specific language governing permissions and # limitations under the License. -# Note: YOUR-ACCESSKEYID, YOUR-SECRETACCESSKEY and my-bucketname are -# dummy values, please replace them with original values. - from minio import Minio client = Minio( @@ -25,4 +22,4 @@ secret_key="zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG", ) -config = client.get_bucket_encryption("my-bucketname") +config = client.get_bucket_encryption("my-bucket") diff --git a/examples/get_bucket_lifecycle.py b/examples/get_bucket_lifecycle.py index 7bab30fbe..1cb89d9fa 100644 --- a/examples/get_bucket_lifecycle.py +++ b/examples/get_bucket_lifecycle.py @@ -14,9 +14,6 @@ # See the License for the specific language governing permissions and # limitations under the License. -# Note: YOUR-ACCESSKEYID, YOUR-SECRETACCESSKEY and my-bucketname are -# dummy values, please replace them with original values. - from minio import Minio client = Minio( @@ -25,4 +22,4 @@ secret_key="zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG", ) -config = client.get_bucket_lifecycle("my-bucketname") +config = client.get_bucket_lifecycle("my-bucket") diff --git a/examples/get_bucket_notification.py b/examples/get_bucket_notification.py index 2935d8a56..ddf2a8af3 100644 --- a/examples/get_bucket_notification.py +++ b/examples/get_bucket_notification.py @@ -14,9 +14,6 @@ # See the License for the specific language governing permissions and # limitations under the License. -# Note: YOUR-ACCESSKEYID, YOUR-SECRETACCESSKEY and my-bucketname are -# dummy values, please replace them with original values. - from minio import Minio client = Minio( @@ -25,4 +22,4 @@ secret_key="zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG", ) -config = client.get_bucket_notification("my-bucketname") +config = client.get_bucket_notification("my-bucket") diff --git a/examples/get_bucket_policy.py b/examples/get_bucket_policy.py index 3e1ef7e81..67b95e17f 100644 --- a/examples/get_bucket_policy.py +++ b/examples/get_bucket_policy.py @@ -14,19 +14,12 @@ # See the License for the specific language governing permissions and # limitations under the License. -# Note: YOUR-ACCESSKEYID, YOUR-SECRETACCESSKEY and my-bucketname are -# dummy values, please replace them with original values. - from minio import Minio -from minio.error import ResponseError -client = Minio('s3.amazonaws.com', secure=True, - access_key='YOUR-ACCESSKEYID', - secret_key='YOUR-SECRETACCESSKEY') +client = Minio( + "play.min.io", + access_key="Q3AM3UQ867SPQQA43P2F", + secret_key="zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG", +) -# Make a new bucket -try: - # Get current policy of bucket 'my-bucketname'. - print(client.get_bucket_policy('my-bucketname')) -except ResponseError as err: - print(err) +policy = client.get_bucket_policy("my-bucket") diff --git a/examples/get_bucket_replication.py b/examples/get_bucket_replication.py index 4c688802b..0c29597d0 100644 --- a/examples/get_bucket_replication.py +++ b/examples/get_bucket_replication.py @@ -14,9 +14,6 @@ # See the License for the specific language governing permissions and # limitations under the License. -# Note: YOUR-ACCESSKEYID, YOUR-SECRETACCESSKEY and my-bucketname are -# dummy values, please replace them with original values. - from minio import Minio client = Minio( @@ -25,4 +22,4 @@ secret_key="zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG", ) -config = client.get_bucket_replication("my-bucketname") +config = client.get_bucket_replication("my-bucket") diff --git a/examples/get_bucket_tags.py b/examples/get_bucket_tags.py index 7c2b11b43..95c7b1f99 100644 --- a/examples/get_bucket_tags.py +++ b/examples/get_bucket_tags.py @@ -14,9 +14,6 @@ # See the License for the specific language governing permissions and # limitations under the License. -# Note: YOUR-ACCESSKEYID, YOUR-SECRETACCESSKEY and my-bucketname are -# dummy values, please replace them with original values. - from minio import Minio client = Minio( @@ -25,4 +22,4 @@ secret_key="zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG", ) -tags = client.get_bucket_tags("my-bucketname") +tags = client.get_bucket_tags("my-bucket") diff --git a/examples/get_bucket_versioning.py b/examples/get_bucket_versioning.py index 4e4141287..4ef41e2a8 100644 --- a/examples/get_bucket_versioning.py +++ b/examples/get_bucket_versioning.py @@ -14,9 +14,6 @@ # See the License for the specific language governing permissions and # limitations under the License. -# Note: YOUR-ACCESSKEYID, YOUR-SECRETACCESSKEY and my-bucketname are -# dummy values, please replace them with original values. - from minio import Minio client = Minio( @@ -25,5 +22,5 @@ secret_key="zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG", ) -config = client.get_bucket_versioning("my-bucketname") +config = client.get_bucket_versioning("my-bucket") print(config.status) diff --git a/examples/get_object.py b/examples/get_object.py index 58e8747dd..aecd93d73 100644 --- a/examples/get_object.py +++ b/examples/get_object.py @@ -14,21 +14,18 @@ # See the License for the specific language governing permissions and # limitations under the License. -# Note: YOUR-ACCESSKEYID, YOUR-SECRETACCESSKEY, my-bucketname, my-objectname -# and my-testfile are dummy values, please replace them with original values. - from minio import Minio from minio.sse import SseCustomerKey client = Minio( - "s3.amazonaws.com", - access_key="YOUR-ACCESSKEYID", - secret_key="YOUR-SECRETACCESSKEY", + "play.min.io", + access_key="Q3AM3UQ867SPQQA43P2F", + secret_key="zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG", ) # Get data of an object. try: - response = client.get_object("my-bucketname", "my-objectname") + response = client.get_object("my-bucket", "my-object") # Read data from response. finally: response.close() @@ -37,7 +34,7 @@ # Get data of an object of version-ID. try: response = client.get_object( - "my-bucketname", "my-objectname", + "my-bucket", "my-object", version_id="dfbd25b3-abec-4184-a4e8-5a35a5c1174d", ) # Read data from response. @@ -48,7 +45,7 @@ # Get data of an object from offset and length. try: response = client.get_object( - "my-bucketname", "my-objectname", offset=512, length=1024, + "my-bucket", "my-object", offset=512, length=1024, ) # Read data from response. finally: @@ -58,7 +55,7 @@ # Get data of an SSE-C encrypted object. try: response = client.get_object( - "my-bucketname", "my-objectname", + "my-bucket", "my-object", ssec=SseCustomerKey(b"32byteslongsecretkeymustprovided"), ) # Read data from response. diff --git a/examples/get_object_lock_config.py b/examples/get_object_lock_config.py index 5d98678bb..2255edc42 100644 --- a/examples/get_object_lock_config.py +++ b/examples/get_object_lock_config.py @@ -14,9 +14,6 @@ # See the License for the specific language governing permissions and # limitations under the License. -# Note: YOUR-ACCESSKEYID, YOUR-SECRETACCESSKEY and my-bucketname are -# dummy values, please replace them with original values. - from minio import Minio client = Minio( @@ -25,4 +22,4 @@ secret_key="zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG", ) -config = client.get_object_lock_config("my-bucketname") +config = client.get_object_lock_config("my-bucket") diff --git a/examples/get_object_retention.py b/examples/get_object_retention.py index 9bb9bdef4..d060bffd8 100644 --- a/examples/get_object_retention.py +++ b/examples/get_object_retention.py @@ -14,9 +14,6 @@ # See the License for the specific language governing permissions and # limitations under the License. -# Note: YOUR-ACCESSKEYID, YOUR-SECRETACCESSKEY and my-bucketname are -# dummy values, please replace them with original values. - from minio import Minio client = Minio( @@ -25,4 +22,4 @@ secret_key="zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG", ) -config = client.get_object_retention("my-bucketname", "my-objectname") +config = client.get_object_retention("my-bucket", "my-object") diff --git a/examples/get_object_tags.py b/examples/get_object_tags.py index f1e40c733..3631acc80 100644 --- a/examples/get_object_tags.py +++ b/examples/get_object_tags.py @@ -14,9 +14,6 @@ # See the License for the specific language governing permissions and # limitations under the License. -# Note: YOUR-ACCESSKEYID, YOUR-SECRETACCESSKEY and my-bucketname are -# dummy values, please replace them with original values. - from minio import Minio client = Minio( @@ -25,4 +22,4 @@ secret_key="zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG", ) -tags = client.get_object_tags("my-bucketname", "my-objectname") +tags = client.get_object_tags("my-bucket", "my-object") diff --git a/examples/is_object_legal_hold_enabled.py b/examples/is_object_legal_hold_enabled.py index 057f477c2..82b665390 100644 --- a/examples/is_object_legal_hold_enabled.py +++ b/examples/is_object_legal_hold_enabled.py @@ -14,9 +14,6 @@ # See the License for the specific language governing permissions and # limitations under the License. -# Note: YOUR-ACCESSKEYID, YOUR-SECRETACCESSKEY and my-bucketname are -# dummy values, please replace them with original values. - from minio import Minio client = Minio( @@ -25,4 +22,7 @@ secret_key="zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG", ) -status = client.is_object_legal_hold_enabled("my-bucketname", "my-objectname") +if client.is_object_legal_hold_enabled("my-bucket", "my-object"): + print("legal hold is enabled on my-object") +else: + print("legal hold is not enabled on my-object") diff --git a/examples/list_buckets.py b/examples/list_buckets.py index 193ff1fda..373b35556 100644 --- a/examples/list_buckets.py +++ b/examples/list_buckets.py @@ -14,16 +14,14 @@ # See the License for the specific language governing permissions and # limitations under the License. -# Note: YOUR-ACCESSKEYID and YOUR-SECRETACCESSKEY are -# dummy values, please replace them with original values. - from minio import Minio -client = Minio('s3.amazonaws.com', - access_key='YOUR-ACCESSKEYID', - secret_key='YOUR-SECRETACCESSKEY') +client = Minio( + "play.min.io", + access_key="Q3AM3UQ867SPQQA43P2F", + secret_key="zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG", +) buckets = client.list_buckets() - for bucket in buckets: print(bucket.name, bucket.creation_date) diff --git a/examples/list_objects.py b/examples/list_objects.py index d76a7b120..fcabe4b5d 100644 --- a/examples/list_objects.py +++ b/examples/list_objects.py @@ -14,26 +14,41 @@ # See the License for the specific language governing permissions and # limitations under the License. -# Note: YOUR-ACCESSKEYID, YOUR-SECRETACCESSKEY, my-bucketname and my-prefixname -# are dummy values, please replace them with original values. - from minio import Minio -client = Minio('s3.amazonaws.com', - access_key='YOUR-ACCESSKEYID', - secret_key='YOUR-SECRETACCESSKEY') +client = Minio( + "play.min.io", + access_key="Q3AM3UQ867SPQQA43P2F", + secret_key="zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG", +) + +# List objects information. +objects = client.list_objects("my-bucket") +for obj in objects: + print(obj) + +# List objects information whose names starts with "my/prefix/". +objects = client.list_objects("my-bucket", prefix="my/prefix/") +for obj in objects: + print(obj) + +# List objects information recursively. +objects = client.list_objects("my-bucket", recursive=True) +for obj in objects: + print(obj) -# List all object paths in bucket that begin with my-prefixname. -objects = client.list_objects('my-bucketname', prefix='my-prefixname', - recursive=True) +# List objects information recursively whose names starts with +# "my/prefix/". +objects = client.list_objects( + "my-bucket", prefix="my/prefix/", recursive=True, +) for obj in objects: - print(obj.bucket_name, obj.object_name.encode('utf-8'), obj.last_modified, - obj.etag, obj.size, obj.content_type) + print(obj) -# List all object paths in bucket that begin with my-prefixname using -# API V1 listing API. -objects = client.list_objects('my-bucketname', prefix='my-prefixname', - recursive=True, use_api_v1=True) +# List objects information recursively after object name +# "my/prefix/world/1". +objects = client.list_objects( + "my-bucket", recursive=True, start_after="my/prefix/world/1", +) for obj in objects: - print(obj.bucket_name, obj.object_name.encode('utf-8'), obj.last_modified, - obj.etag, obj.size, obj.content_type) + print(obj) diff --git a/examples/listen_notification.py b/examples/listen_bucket_notification.py similarity index 52% rename from examples/listen_notification.py rename to examples/listen_bucket_notification.py index 8a89f3d0d..ea9eb0d87 100644 --- a/examples/listen_notification.py +++ b/examples/listen_bucket_notification.py @@ -14,20 +14,18 @@ # See the License for the specific language governing permissions and # limitations under the License. -# Note: YOUR-ACCESSKEYID, YOUR-SECRETACCESSKEY, my-testfile, my-bucketname and -# my-objectname are dummy values, please replace them with original values. - from minio import Minio -client = Minio('play.min.io', - access_key='Q3AM3UQ867SPQQA43P2F', - secret_key='zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG') +client = Minio( + "play.min.io", + access_key="Q3AM3UQ867SPQQA43P2F", + secret_key="zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG", +) -# Put a file with default content-type. -events = client.listen_bucket_notification('my-bucket', 'my-prefix/', - '.my-suffix', - ['s3:ObjectCreated:*', - 's3:ObjectRemoved:*', - 's3:ObjectAccessed:*']) +events = client.listen_bucket_notification( + "my-bucket", + prefix="my-prefix/", + events=["s3:ObjectCreated:*", "s3:ObjectRemoved:*"], +) for event in events: print(event) diff --git a/examples/make_bucket.py b/examples/make_bucket.py index b4c51122b..3e7720e52 100644 --- a/examples/make_bucket.py +++ b/examples/make_bucket.py @@ -14,18 +14,19 @@ # See the License for the specific language governing permissions and # limitations under the License. -# Note: YOUR-ACCESSKEYID, YOUR-SECRETACCESSKEY and my-bucketname are -# dummy values, please replace them with original values. - from minio import Minio -from minio.error import ResponseError -client = Minio('s3.amazonaws.com', - access_key='YOUR-ACCESSKEYID', - secret_key='YOUR-SECRETACCESSKEY') +client = Minio( + "play.min.io", + access_key="Q3AM3UQ867SPQQA43P2F", + secret_key="zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG", +) + +# Create bucket. +client.make_bucket("my-bucket") + +# Create bucket on specific region. +client.make_bucket("my-bucket", "us-west-1") -# Make a new bucket -try: - client.make_bucket('my-bucketname') -except ResponseError as err: - print(err) +# Create bucket with object-lock feature on specific region. +client.make_bucket("my-bucket", "eu-west-2", object_lock=True) diff --git a/examples/minio_with_assume_role_provider.py b/examples/minio_with_assume_role_provider.py index fe3d54d8e..ac352e224 100644 --- a/examples/minio_with_assume_role_provider.py +++ b/examples/minio_with_assume_role_provider.py @@ -56,5 +56,5 @@ client = Minio("MINIO-HOST:MINIO-PORT", credentials=provider) # Get information of an object. -stat = client.stat_object("my-bucketname", "my-objectname") +stat = client.stat_object("my-bucket", "my-object") print(stat) diff --git a/examples/minio_with_aws_config_provider.py b/examples/minio_with_aws_config_provider.py index 204ef1610..ac134699e 100644 --- a/examples/minio_with_aws_config_provider.py +++ b/examples/minio_with_aws_config_provider.py @@ -18,8 +18,8 @@ from minio import Minio from minio.credentials import AWSConfigProvider -client = Minio('s3.amazonaws.com', credentials=AWSConfigProvider()) +client = Minio("s3.amazonaws.com", credentials=AWSConfigProvider()) # Get information of an object. -stat = client.stat_object("my-bucketname", "my-objectname") +stat = client.stat_object("my-bucket", "my-object") print(stat) diff --git a/examples/minio_with_chained_provider.py b/examples/minio_with_chained_provider.py index dc955531c..d68b04b69 100644 --- a/examples/minio_with_chained_provider.py +++ b/examples/minio_with_chained_provider.py @@ -23,7 +23,7 @@ EnvAWSProvider, IamAwsProvider) client = Minio( - 's3.amazonaws.com', + "s3.amazonaws.com", credentials=ChainedProvider( [ IamAwsProvider(), @@ -34,5 +34,5 @@ ) # Get information of an object. -stat = client.stat_object("my-bucketname", "my-objectname") +stat = client.stat_object("my-bucket", "my-object") print(stat) diff --git a/examples/minio_with_client_grants_provider.py b/examples/minio_with_client_grants_provider.py index c71a368ab..958126e66 100644 --- a/examples/minio_with_client_grants_provider.py +++ b/examples/minio_with_client_grants_provider.py @@ -13,7 +13,6 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. -# import json @@ -59,5 +58,5 @@ def get_jwt(client_id, client_secret, idp_endpoint): client = Minio("MINIO-HOST:MINIO-PORT", credentials=provider) # Get information of an object. -stat = client.stat_object("my-bucketname", "my-objectname") +stat = client.stat_object("my-bucket", "my-object") print(stat) diff --git a/examples/minio_with_env_aws_provider.py b/examples/minio_with_env_aws_provider.py index 98e90209d..69898149d 100644 --- a/examples/minio_with_env_aws_provider.py +++ b/examples/minio_with_env_aws_provider.py @@ -18,8 +18,8 @@ from minio import Minio from minio.credentials import EnvAWSProvider -client = Minio('s3.amazonaws.com', credentials=EnvAWSProvider()) +client = Minio("s3.amazonaws.com", credentials=EnvAWSProvider()) # Get information of an object. -stat = client.stat_object("my-bucketname", "my-objectname") +stat = client.stat_object("my-bucket", "my-object") print(stat) diff --git a/examples/minio_with_env_minio_provider.py b/examples/minio_with_env_minio_provider.py index 076d3b68c..f0f985b5f 100644 --- a/examples/minio_with_env_minio_provider.py +++ b/examples/minio_with_env_minio_provider.py @@ -21,5 +21,5 @@ client = Minio("MINIO-HOST:MINIO-PORT", credentials=EnvMinioProvider()) # Get information of an object. -stat = client.stat_object("my-bucketname", "my-objectname") +stat = client.stat_object("my-bucket", "my-object") print(stat) diff --git a/examples/minio_with_iam_aws_provider.py b/examples/minio_with_iam_aws_provider.py index 7db88fbd6..5c9e57132 100644 --- a/examples/minio_with_iam_aws_provider.py +++ b/examples/minio_with_iam_aws_provider.py @@ -18,8 +18,8 @@ from minio import Minio from minio.credentials import IamAwsProvider -client = Minio('s3.amazonaws.com', credentials=IamAwsProvider()) +client = Minio("s3.amazonaws.com", credentials=IamAwsProvider()) # Get information of an object. -stat = client.stat_object("my-bucketname", "my-objectname") +stat = client.stat_object("my-bucket", "my-object") print(stat) diff --git a/examples/minio_with_ldap_identity_provider.py b/examples/minio_with_ldap_identity_provider.py index 047ac691c..55b8468a7 100644 --- a/examples/minio_with_ldap_identity_provider.py +++ b/examples/minio_with_ldap_identity_provider.py @@ -32,5 +32,5 @@ client = Minio("MINIO-HOST:MINIO-PORT", credentials=provider) # Get information of an object. -stat = client.stat_object("my-bucketname", "my-objectname") +stat = client.stat_object("my-bucket", "my-object") print(stat) diff --git a/examples/minio_with_minio_client_config_provider.py b/examples/minio_with_minio_client_config_provider.py index 2f6aeb51a..283c7e178 100644 --- a/examples/minio_with_minio_client_config_provider.py +++ b/examples/minio_with_minio_client_config_provider.py @@ -23,5 +23,5 @@ ) # Get information of an object. -stat = client.stat_object("my-bucketname", "my-objectname") +stat = client.stat_object("my-bucket", "my-object") print(stat) diff --git a/examples/minio_with_web_identity_provider.py b/examples/minio_with_web_identity_provider.py index a9a9d989f..0135f8ff0 100644 --- a/examples/minio_with_web_identity_provider.py +++ b/examples/minio_with_web_identity_provider.py @@ -72,5 +72,5 @@ def get_jwt(client_id, client_secret, idp_client_id, idp_endpoint): client = Minio("MINIO-HOST:MINIO-PORT", credentials=provider) # Get information of an object. -stat = client.stat_object("my-bucketname", "my-objectname") +stat = client.stat_object("my-bucket", "my-object") print(stat) diff --git a/examples/presigned_post_policy.py b/examples/presigned_post_policy.py index 30efbe508..b681cfe22 100644 --- a/examples/presigned_post_policy.py +++ b/examples/presigned_post_policy.py @@ -20,9 +20,9 @@ from minio.datatypes import PostPolicy client = Minio( - "s3.amazonaws.com", - access_key="YOUR-ACCESSKEYID", - secret_key="YOUR-SECRETACCESSKEY", + "play.min.io", + access_key="Q3AM3UQ867SPQQA43P2F", + secret_key="zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG", ) policy = PostPolicy( @@ -35,7 +35,7 @@ curl_cmd = ( "curl -X POST " - "https://s3.amazonaws.com/my-bucket " + "https://play.min.io/my-bucket " "{0} -F file=@" ).format( " ".join(["-F {0}={1}".format(k, v) for k, v in form_data.items()]), diff --git a/examples/remove_bucket.py b/examples/remove_bucket.py index 3a9ecbd77..a3c60795d 100644 --- a/examples/remove_bucket.py +++ b/examples/remove_bucket.py @@ -14,19 +14,12 @@ # See the License for the specific language governing permissions and # limitations under the License. -# Note: YOUR-ACCESSKEYID, YOUR-SECRETACCESSKEY and my-bucketname are -# dummy values, please replace them with original values. - from minio import Minio -from minio.error import ResponseError -client = Minio('s3.amazonaws.com', - access_key='YOUR-ACCESSKEYID', - secret_key='YOUR-SECRETACCESSKEY') +client = Minio( + "play.min.io", + access_key="Q3AM3UQ867SPQQA43P2F", + secret_key="zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG", +) -# Remove a bucket -# This operation will only work if your bucket is empty. -try: - client.remove_bucket('my-bucketname') -except ResponseError as err: - print(err) +client.remove_bucket("my-bucket") diff --git a/examples/remove_object.py b/examples/remove_object.py index 3320e2707..8828509fc 100644 --- a/examples/remove_object.py +++ b/examples/remove_object.py @@ -14,18 +14,19 @@ # See the License for the specific language governing permissions and # limitations under the License. -# Note: YOUR-ACCESSKEYID, YOUR-SECRETACCESSKEY, my-bucketname and my-objectname -# are dummy values, please replace them with original values. - from minio import Minio -from minio.error import ResponseError -client = Minio('s3.amazonaws.com', - access_key='YOUR-ACCESSKEYID', - secret_key='YOUR-SECRETACCESSKEY') +client = Minio( + "play.min.io", + access_key="Q3AM3UQ867SPQQA43P2F", + secret_key="zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG", +) + +# Remove object. +client.remove_object("my-bucket", "my-object") -# Remove an object. -try: - client.remove_object('my-bucketname', 'my-objectname') -except ResponseError as err: - print(err) +# Remove version of an object. +client.remove_object( + "my-bucket", "my-object", + version_id="dfbd25b3-abec-4184-a4e8-5a35a5c1174d", +) diff --git a/examples/remove_objects.py b/examples/remove_objects.py index 749e3677c..95c9ac2bb 100644 --- a/examples/remove_objects.py +++ b/examples/remove_objects.py @@ -14,21 +14,32 @@ # See the License for the specific language governing permissions and # limitations under the License. -# Note: YOUR-ACCESSKEYID, YOUR-SECRETACCESSKEY, my-bucketname and my-prefix -# are dummy values, please replace them with original values. - from minio import Minio from minio.deleteobjects import DeleteObject -client = Minio('s3.amazonaws.com', - access_key='YOUR-ACCESSKEYID', - secret_key='YOUR-SECRETACCESSKEY') +client = Minio( + "play.min.io", + access_key="Q3AM3UQ867SPQQA43P2F", + secret_key="zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG", +) + +# Remove list of objects. +errors = client.remove_objects( + "my-bucket", + [ + DeleteObject("my-object1"), + DeleteObject("my-object2"), + DeleteObject("my-object3", "13f88b18-8dcd-4c83-88f2-8631fdb6250c"), + ], +) +for error in errors: + print("error occured when deleting object", error) # Remove a prefix recursively. delete_object_list = map( lambda x: DeleteObject(x.object_name), - client.list_objects("my-bucketname", "my-prefix", recursive=True), + client.list_objects("my-bucket", "my/prefix/", recursive=True), ) -errors = client.remove_objects("my-bucketname", delete_object_list) +errors = client.remove_objects("my-bucket", delete_object_list) for error in errors: print("error occured when deleting object", error) diff --git a/examples/select_object_content.py b/examples/select_object_content.py index 20bbbefb2..59f5a4bca 100644 --- a/examples/select_object_content.py +++ b/examples/select_object_content.py @@ -20,9 +20,9 @@ SelectRequest) client = Minio( - "s3.amazonaws.com", - access_key="YOUR-ACCESSKEY", - secret_key="YOUR-SECRETKEY", + "play.min.io", + access_key="Q3AM3UQ867SPQQA43P2F", + secret_key="zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG", ) with client.select_object_content( diff --git a/examples/set_bucket_encryption.py b/examples/set_bucket_encryption.py index 58eb1bedf..fe840c5c1 100644 --- a/examples/set_bucket_encryption.py +++ b/examples/set_bucket_encryption.py @@ -14,9 +14,6 @@ # See the License for the specific language governing permissions and # limitations under the License. -# Note: YOUR-ACCESSKEYID, YOUR-SECRETACCESSKEY and my-bucketname are -# dummy values, please replace them with original values. - from minio import Minio from minio.sseconfig import Rule, SSEConfig @@ -27,5 +24,5 @@ ) client.set_bucket_encryption( - "my-bucketname", SSEConfig(Rule.new_sse_s3_rule()), + "my-bucket", SSEConfig(Rule.new_sse_s3_rule()), ) diff --git a/examples/set_bucket_lifecycle.py b/examples/set_bucket_lifecycle.py index de9840f10..ec053b8c4 100644 --- a/examples/set_bucket_lifecycle.py +++ b/examples/set_bucket_lifecycle.py @@ -14,12 +14,9 @@ # See the License for the specific language governing permissions and # limitations under the License. -# Note: YOUR-ACCESSKEYID, YOUR-SECRETACCESSKEY and my-bucketname are -# dummy values, please replace them with original values. - from minio import Minio from minio.commonconfig import ENABLED, Filter -from minio.lifecycleconfig import Expiration, LifecycleConfig, Rule +from minio.lifecycleconfig import Expiration, LifecycleConfig, Rule, Transition client = Minio( "play.min.io", @@ -29,6 +26,12 @@ config = LifecycleConfig( [ + Rule( + ENABLED, + rule_filter=Filter(prefix="documents/"), + rule_id="rule1", + transition=Transition(days=30, storage_class="GLACIER"), + ), Rule( ENABLED, rule_filter=Filter(prefix="logs/"), @@ -37,4 +40,4 @@ ), ], ) -client.set_bucket_lifecycle("my-bucketname", config) +client.set_bucket_lifecycle("my-bucket", config) diff --git a/examples/set_bucket_notification.py b/examples/set_bucket_notification.py index 6b826538f..89c43f452 100644 --- a/examples/set_bucket_notification.py +++ b/examples/set_bucket_notification.py @@ -14,9 +14,6 @@ # See the License for the specific language governing permissions and # limitations under the License. -# Note: YOUR-ACCESSKEYID, YOUR-SECRETACCESSKEY and my-bucketname are -# dummy values, please replace them with original values. - from minio import Minio from minio.notificationconfig import (NotificationConfig, PrefixFilterRule, QueueConfig) @@ -31,10 +28,10 @@ queue_config_list=[ QueueConfig( "QUEUE-ARN-OF-THIS-BUCKET", - ['s3:ObjectCreated:*'], + ["s3:ObjectCreated:*"], config_id="1", prefix_filter_rule=PrefixFilterRule("abc"), ), ], ) -client.set_bucket_notification("my-bucketname", config) +client.set_bucket_notification("my-bucket", config) diff --git a/examples/set_bucket_policy.py b/examples/set_bucket_policy.py index 38a40b52d..f1c938f6b 100644 --- a/examples/set_bucket_policy.py +++ b/examples/set_bucket_policy.py @@ -14,120 +14,62 @@ # See the License for the specific language governing permissions and # limitations under the License. -# Note: YOUR-ACCESSKEYID, YOUR-SECRETACCESSKEY and my-bucketname are -# dummy values, please replace them with original values. - import json from minio import Minio -from minio.error import ResponseError - -client = Minio('s3.amazonaws.com', - access_key='YOUR-ACCESSKEYID', - secret_key='YOUR-SECRETACCESSKEY') - -# Make a new bucket -try: - # Set bucket policy to read-only for bucket 'my-bucketname' - policy_read_only = { - "Version": "2012-10-17", - "Statement": [ - { - "Sid": "", - "Effect": "Allow", - "Principal": {"AWS": "*"}, - "Action": "s3:GetBucketLocation", - "Resource": "arn:aws:s3:::my-bucketname" - }, - { - "Sid": "", - "Effect": "Allow", - "Principal": {"AWS": "*"}, - "Action": "s3:ListBucket", - "Resource": "arn:aws:s3:::my-bucketname" - }, - { - "Sid": "", - "Effect": "Allow", - "Principal": {"AWS": "*"}, - "Action": "s3:GetObject", - "Resource": "arn:aws:s3:::my-bucketname/*" - } - ] - } - client.set_bucket_policy('my-bucketname', json.dumps(policy_read_only)) - # Set bucket policy to read-write for bucket 'my-bucketname' - policy_read_write = { - "Version": "2012-10-17", - "Statement": [ - { - "Action": ["s3:GetBucketLocation"], - "Sid": "", - "Resource": ["arn:aws:s3:::my-bucketname"], - "Effect": "Allow", - "Principal": {"AWS": "*"} - }, - { - "Action": ["s3:ListBucket"], - "Sid": "", - "Resource": ["arn:aws:s3:::my-bucketname"], - "Effect": "Allow", - "Principal": {"AWS": "*"} - }, - { - "Action": ["s3:ListBucketMultipartUploads"], - "Sid": "", - "Resource": ["arn:aws:s3:::my-bucketname"], - "Effect": "Allow", - "Principal": {"AWS": "*"} - }, - { - "Action": ["s3:ListMultipartUploadParts", - "s3:GetObject", - "s3:AbortMultipartUpload", - "s3:DeleteObject", - "s3:PutObject"], - "Sid": "", - "Resource": ["arn:aws:s3:::my-bucketname/*"], - "Effect": "Allow", - "Principal": {"AWS": "*"} - } - ] - } - client.set_bucket_policy('my-bucketname', json.dumps(policy_read_write)) +client = Minio( + "play.min.io", + access_key="Q3AM3UQ867SPQQA43P2F", + secret_key="zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG", +) - # Set bucket policy to write-only for bucket 'my-bucketname' - policy_write_only = { - "Version": "2012-10-17", - "Statement": [ - { - "Sid": "", - "Effect": "Allow", - "Principal": {"AWS": "*"}, - "Action": "s3:GetBucketLocation", - "Resource": "arn:aws:s3:::my-bucketname" - }, - {"Sid": "", - "Effect": "Allow", - "Principal": {"AWS": "*"}, - "Action": "s3:ListBucketMultipartUploads", - "Resource": "arn:aws:s3:::my-bucketname" - }, - { - "Sid": "", - "Effect": "Allow", - "Principal": {"AWS": "*"}, - "Action": [ - "s3:ListMultipartUploadParts", - "s3:AbortMultipartUpload", - "s3:DeleteObject", - "s3:PutObject"], - "Resource":"arn:aws:s3:::my-bucketname/*" - } - ] - } - client.set_bucket_policy('my-bucketname', json.dumps(policy_write_only)) +# Example anonymous read-only bucket policy. +policy = { + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Principal": {"AWS": "*"}, + "Action": ["s3:GetBucketLocation", "s3:ListBucket"], + "Resource": "arn:aws:s3:::my-bucket", + }, + { + "Effect": "Allow", + "Principal": {"AWS": "*"}, + "Action": "s3:GetObject", + "Resource": "arn:aws:s3:::my-bucket/*", + }, + ], +} +client.set_bucket_policy("my-bucket", json.dumps(policy)) -except ResponseError as err: - print(err) +# Example anonymous read-write bucket policy. +policy = { + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Principal": {"AWS": "*"}, + "Action": [ + "s3:GetBucketLocation", + "s3:ListBucket", + "s3:ListBucketMultipartUploads", + ], + "Resource": "arn:aws:s3:::my-bucket", + }, + { + "Effect": "Allow", + "Principal": {"AWS": "*"}, + "Action": [ + "s3:GetObject", + "s3:PutObject", + "s3:DeleteObject", + "s3:ListMultipartUploadParts", + "s3:AbortMultipartUpload", + ], + "Resource": "arn:aws:s3:::my-bucket/images/*", + }, + ], +} +client.set_bucket_policy("my-bucket", json.dumps(policy)) diff --git a/examples/set_bucket_replication.py b/examples/set_bucket_replication.py index 3c2133f87..de5d38c6f 100644 --- a/examples/set_bucket_replication.py +++ b/examples/set_bucket_replication.py @@ -14,9 +14,6 @@ # See the License for the specific language governing permissions and # limitations under the License. -# Note: YOUR-ACCESSKEYID, YOUR-SECRETACCESSKEY and my-bucketname are -# dummy values, please replace them with original values. - from minio import Minio from minio.commonconfig import DISABLED, ENABLED, AndOperator, Filter from minio.replicationconfig import (DeleteMarkerReplication, Destination, @@ -50,4 +47,4 @@ ), ], ) -client.set_bucket_replication("my-bucketname", config) +client.set_bucket_replication("my-bucket", config) diff --git a/examples/set_bucket_tags.py b/examples/set_bucket_tags.py index 9277fb8fb..0d759765c 100644 --- a/examples/set_bucket_tags.py +++ b/examples/set_bucket_tags.py @@ -14,9 +14,6 @@ # See the License for the specific language governing permissions and # limitations under the License. -# Note: YOUR-ACCESSKEYID, YOUR-SECRETACCESSKEY and my-bucketname are -# dummy values, please replace them with original values. - from minio import Minio from minio.commonconfig import Tags @@ -29,4 +26,4 @@ tags = Tags.new_bucket_tags() tags["Project"] = "Project One" tags["User"] = "jsmith" -client.set_bucket_tags("my-bucketname", tags) +client.set_bucket_tags("my-bucket", tags) diff --git a/examples/set_bucket_versioning.py b/examples/set_bucket_versioning.py index 78af5761f..418616a75 100644 --- a/examples/set_bucket_versioning.py +++ b/examples/set_bucket_versioning.py @@ -14,9 +14,6 @@ # See the License for the specific language governing permissions and # limitations under the License. -# Note: YOUR-ACCESSKEYID, YOUR-SECRETACCESSKEY and my-bucketname are -# dummy values, please replace them with original values. - from minio import Minio from minio.commonconfig import ENABLED from minio.versioningconfig import VersioningConfig @@ -27,4 +24,4 @@ secret_key="zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG", ) -client.set_bucket_versioning("my-bucketname", VersioningConfig(ENABLED)) +client.set_bucket_versioning("my-bucket", VersioningConfig(ENABLED)) diff --git a/examples/set_object_lock_config.py b/examples/set_object_lock_config.py index bf2ce4f1e..a777a809d 100644 --- a/examples/set_object_lock_config.py +++ b/examples/set_object_lock_config.py @@ -14,9 +14,6 @@ # See the License for the specific language governing permissions and # limitations under the License. -# Note: YOUR-ACCESSKEYID, YOUR-SECRETACCESSKEY and my-bucketname are -# dummy values, please replace them with original values. - from minio import Minio from minio.commonconfig import GOVERNANCE from minio.objectlockconfig import DAYS, ObjectLockConfig @@ -28,4 +25,4 @@ ) config = ObjectLockConfig(GOVERNANCE, 15, DAYS) -client.set_object_lock_condig("my-bucketname", config) +client.set_object_lock_condig("my-bucket", config) diff --git a/examples/set_object_retention.py b/examples/set_object_retention.py index b79617a8d..a0afc8b80 100644 --- a/examples/set_object_retention.py +++ b/examples/set_object_retention.py @@ -14,9 +14,6 @@ # See the License for the specific language governing permissions and # limitations under the License. -# Note: YOUR-ACCESSKEYID, YOUR-SECRETACCESSKEY and my-bucketname are -# dummy values, please replace them with original values. - from datetime import datetime, timedelta from minio import Minio @@ -30,4 +27,4 @@ ) config = Retention(GOVERNANCE, datetime.utcnow() + timedelta(days=10)) -client.set_object_retention("my-bucketname", "my-objectname", config) +client.set_object_retention("my-bucket", "my-object", config) diff --git a/examples/set_object_tags.py b/examples/set_object_tags.py index c7683e0cb..edcd53820 100644 --- a/examples/set_object_tags.py +++ b/examples/set_object_tags.py @@ -14,9 +14,6 @@ # See the License for the specific language governing permissions and # limitations under the License. -# Note: YOUR-ACCESSKEYID, YOUR-SECRETACCESSKEY and my-bucketname are -# dummy values, please replace them with original values. - from minio import Minio from minio.commonconfig import Tags @@ -29,4 +26,4 @@ tags = Tags.new_object_tags() tags["Project"] = "Project One" tags["User"] = "jsmith" -client.set_object_tags("my-bucketname", "my-objectname", tags) +client.set_object_tags("my-bucket", "my-object", tags) diff --git a/examples/stat_object.py b/examples/stat_object.py index a6a9219db..3a38ff020 100644 --- a/examples/stat_object.py +++ b/examples/stat_object.py @@ -14,20 +14,17 @@ # See the License for the specific language governing permissions and # limitations under the License. -# Note: YOUR-ACCESSKEYID, YOUR-SECRETACCESSKEY, my-bucketname and my-objectname -# are dummy values, please replace them with original values. - from minio import Minio from minio.sse import SseCustomerKey client = Minio( - "s3.amazonaws.com", - access_key="YOUR-ACCESSKEYID", - secret_key="YOUR-SECRETACCESSKEY", + "play.min.io", + access_key="Q3AM3UQ867SPQQA43P2F", + secret_key="zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG", ) # Get object information. -result = client.stat_object("my-bucketname", "my-objectname") +result = client.stat_object("my-bucket", "my-object") print( "last-modified: {0}, size: {1}".format( result.last_modified, result.size, @@ -36,7 +33,7 @@ # Get object information of version-ID. result = client.stat_object( - "my-bucketname", "my-objectname", + "my-bucket", "my-object", version_id="dfbd25b3-abec-4184-a4e8-5a35a5c1174d", ) print( @@ -47,7 +44,7 @@ # Get SSE-C encrypted object information. result = client.stat_object( - "my-bucketname", "my-objectname", + "my-bucket", "my-object", ssec=SseCustomerKey(b"32byteslongsecretkeymustprovided"), ) print( diff --git a/minio/api.py b/minio/api.py index ab152d36e..cc3a10bd3 100644 --- a/minio/api.py +++ b/minio/api.py @@ -16,15 +16,9 @@ # pylint: disable=too-many-lines,disable=too-many-branches,too-many-statements # pylint: disable=too-many-arguments -""" -minio.api -~~~~~~~~~~~~ - -This module implements the API. - -:copyright: (c) 2015, 2016, 2017 by MinIO, Inc. -:license: Apache 2.0, see LICENSE for more details. +""" +Simple Storage Service (aka S3) client to perform bucket and object operations. """ from __future__ import absolute_import @@ -100,12 +94,21 @@ class Minio: # pylint: disable=too-many-public-methods :return: :class:`Minio ` object Example:: - client = Minio('play.min.io') - client = Minio('s3.amazonaws.com', 'ACCESS_KEY', 'SECRET_KEY') - client = Minio('play.min.io', 'ACCESS_KEY', 'SECRET_KEY', - region='us-east-1') + # Create client with anonymous access. + client = Minio("play.min.io") + + # Create client with access and secret key. + client = Minio("s3.amazonaws.com", "ACCESS-KEY", "SECRET-KEY") + + # Create client with access key and secret key with specific region. + client = Minio( + "play.minio.io:9000", + access_key="Q3AM3UQ867SPQQA43P2F", + secret_key="zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG", + region="my-region", + ) - **NOTE on concurrent usage:** The `Minio` object is thread safe when using + **NOTE on concurrent usage:** `Minio` object is thread safe when using the Python `threading` library. Specifically, it is **NOT** safe to share it between multiple processes, for example when using `multiprocessing.Pool`. The solution is simply to create a new `Minio` @@ -583,9 +586,14 @@ def make_bucket(self, bucket_name, location=None, object_lock=False): :param object_lock: Flag to set object-lock feature. Examples:: - minio.make_bucket('foo') - minio.make_bucket('foo', 'us-west-1') - minio.make_bucket('foo', 'us-west-1', object_lock=True) + # Create bucket. + client.make_bucket("my-bucket") + + # Create bucket on specific region. + client.make_bucket("my-bucket", "us-west-1") + + # Create bucket with object-lock feature on specific region. + client.make_bucket("my-bucket", "eu-west-2", object_lock=True) """ check_bucket_name(bucket_name, True) if self._base_url.region: @@ -624,8 +632,8 @@ def list_buckets(self): :return: List of :class:`Bucket ` object. Example:: - bucket_list = minio.list_buckets() - for bucket in bucket_list: + buckets = client.list_buckets() + for bucket in buckets: print(bucket.name, bucket.creation_date) """ @@ -641,11 +649,10 @@ def bucket_exists(self, bucket_name): :return: True if the bucket exists. Example:: - found = minio.bucket_exists("my-bucketname") - if found: - print("my-bucketname exists") + if client.bucket_exists("my-bucket"): + print("my-bucket exists") else: - print("my-bucketname does not exist") + print("my-bucket does not exist") """ check_bucket_name(bucket_name) try: @@ -663,7 +670,7 @@ def remove_bucket(self, bucket_name): :param bucket_name: Name of the bucket. Example:: - minio.remove_bucket("my-bucketname") + client.remove_bucket("my-bucket") """ check_bucket_name(bucket_name) self._execute("DELETE", bucket_name) @@ -677,7 +684,7 @@ def get_bucket_policy(self, bucket_name): :return: Bucket policy configuration as JSON string. Example:: - config = minio.get_bucket_policy("my-bucketname") + policy = client.get_bucket_policy("my-bucket") """ check_bucket_name(bucket_name) response = self._execute( @@ -692,7 +699,7 @@ def delete_bucket_policy(self, bucket_name): :param bucket_name: Name of the bucket. Example:: - minio.delete_bucket_policy("my-bucketname") + client.delete_bucket_policy("my-bucket") """ check_bucket_name(bucket_name) self._execute("DELETE", bucket_name, query_params={"policy": ""}) @@ -705,7 +712,7 @@ def set_bucket_policy(self, bucket_name, policy): :param policy: Bucket policy configuration as JSON string. Example:: - minio.set_bucket_policy("my-bucketname", config) + client.set_bucket_policy("my-bucket", policy) """ check_bucket_name(bucket_name) is_valid_policy_type(policy) @@ -725,7 +732,7 @@ def get_bucket_notification(self, bucket_name): :return: :class:`NotificationConfig ` object. Example:: - config = minio.get_bucket_notification("my-bucketname") + config = client.get_bucket_notification("my-bucket") """ check_bucket_name(bucket_name) response = self._execute( @@ -745,13 +752,13 @@ def set_bucket_notification(self, bucket_name, config): queue_config_list=[ QueueConfig( "QUEUE-ARN-OF-THIS-BUCKET", - ['s3:ObjectCreated:*'], + ["s3:ObjectCreated:*"], config_id="1", prefix_filter_rule=PrefixFilterRule("abc"), ), ], ) - minio.set_bucket_notification("my-bucketname", config) + client.set_bucket_notification("my-bucket", config) """ check_bucket_name(bucket_name) if not isinstance(config, NotificationConfig): @@ -773,7 +780,7 @@ def delete_bucket_notification(self, bucket_name): :param bucket_name: Name of the bucket. Example:: - minio.delete_bucket_notification("my-bucketname") + client.delete_bucket_notification("my-bucket") """ self.set_bucket_notification(bucket_name, NotificationConfig()) @@ -785,8 +792,8 @@ def set_bucket_encryption(self, bucket_name, config): :param config: :class:`SSEConfig ` object. Example:: - minio.set_bucket_encryption( - "my-bucketname", SSEConfig(Rule.new_sse_s3_rule()), + client.set_bucket_encryption( + "my-bucket", SSEConfig(Rule.new_sse_s3_rule()), ) """ check_bucket_name(bucket_name) @@ -809,7 +816,7 @@ def get_bucket_encryption(self, bucket_name): :return: :class:`SSEConfig ` object. Example:: - config = minio.get_bucket_encryption("my-bucketname") + config = client.get_bucket_encryption("my-bucket") """ check_bucket_name(bucket_name) try: @@ -831,7 +838,7 @@ def delete_bucket_encryption(self, bucket_name): :param bucket_name: Name of the bucket. Example:: - minio.delete_bucket_encryption("my-bucketname") + client.delete_bucket_encryption("my-bucket") """ check_bucket_name(bucket_name) try: @@ -856,15 +863,16 @@ def listen_bucket_notification(self, bucket_name, prefix='', suffix='', :param prefix: Listen events of object starts with prefix. :param suffix: Listen events of object ends with suffix. :param events: Events to listen. - :return: Iterator contains event records. + :return: Iterator of event records as :dict:. Example:: - iter = minio.listen_bucket_notification( - "my-bucketname", - events=('s3:ObjectCreated:*', 's3:ObjectAccessed:*'), + events = client.listen_bucket_notification( + "my-bucket", + prefix="my-prefix/", + events=["s3:ObjectCreated:*", "s3:ObjectRemoved:*"], ) - for events in iter: - print(events) + for event in events: + print(event) """ check_bucket_name(bucket_name) if self._base_url.is_aws_host: @@ -908,8 +916,8 @@ def set_bucket_versioning(self, bucket_name, config): :param config: :class:`VersioningConfig `. Example:: - minio.set_bucket_versioning( - "my-bucketname", VersioningConfig(ENABLED), + client.set_bucket_versioning( + "my-bucket", VersioningConfig(ENABLED), ) """ check_bucket_name(bucket_name) @@ -932,7 +940,7 @@ def get_bucket_versioning(self, bucket_name): :return: :class:`VersioningConfig `. Example:: - config minio.get_bucket_versioning("my-bucketname") + config = client.get_bucket_versioning("my-bucket") print(config.status) """ check_bucket_name(bucket_name) @@ -1019,9 +1027,19 @@ def fget_object(self, bucket_name, object_name, file_path, :return: Object information. Example:: - minio.fget_object('foo', 'bar', 'localfile') - minio.fget_object( - 'foo', 'bar', 'localfile', version_id='VERSION-ID', + # Download data of an object. + client.fget_object("my-bucket", "my-object", "my-filename") + + # Download data of an object of version-ID. + client.fget_object( + "my-bucket", "my-object", "my-filename", + version_id="dfbd25b3-abec-4184-a4e8-5a35a5c1174d", + ) + + # Download data of an SSE-C encrypted object. + client.fget_object( + "my-bucket", "my-object", "my-filename", + ssec=SseCustomerKey(b"32byteslongsecretkeymustprovided"), ) """ check_bucket_name(bucket_name) @@ -1095,18 +1113,42 @@ def get_object(self, bucket_name, object_name, offset=0, length=0, :return: :class:`urllib3.response.HTTPResponse` object. Example:: - // Get entire object data. + # Get data of an object. try: - response = minio.get_object('foo', 'bar') - // Read data from response. + response = client.get_object("my-bucket", "my-object") + # Read data from response. + finally: + response.close() + response.release_conn() + + # Get data of an object of version-ID. + try: + response = client.get_object( + "my-bucket", "my-object", + version_id="dfbd25b3-abec-4184-a4e8-5a35a5c1174d", + ) + # Read data from response. + finally: + response.close() + response.release_conn() + + # Get data of an object from offset and length. + try: + response = client.get_object( + "my-bucket", "my-object", offset=512, length=1024, + ) + # Read data from response. finally: response.close() response.release_conn() - // Get object data for offset/length. + # Get data of an SSE-C encrypted object. try: - response = minio.get_object('foo', 'bar', 2, 4) - // Read data from response. + response = client.get_object( + "my-bucket", "my-object", + ssec=SseCustomerKey(b"32byteslongsecretkeymustprovided"), + ) + # Read data from response. finally: response.close() response.release_conn() @@ -1753,8 +1795,7 @@ def list_objects(self, bucket_name, prefix=None, recursive=False, start_after=None, include_user_meta=False, include_version=False, use_api_v1=False): """ - Lists object information of a bucket using S3 API version 2, optionally - for prefix recursively. + Lists object information of a bucket. :param bucket_name: Name of the bucket. :param prefix: Object name starts with prefix. @@ -1765,39 +1806,39 @@ def list_objects(self, bucket_name, prefix=None, recursive=False, :param include_version: Flag to control whether include object versions. :param use_api_v1: Flag to control to use ListObjectV1 S3 API or not. - :return: An iterator contains object information. + :return: Iterator of :class:`Object `. Example:: # List objects information. - objects = minio.list_objects('foo') - for object in objects: - print(object) + objects = client.list_objects("my-bucket") + for obj in objects: + print(obj) - # List objects information whose names starts with 'hello/'. - objects = minio.list_objects('foo', prefix='hello/') - for object in objects: - print(object) + # List objects information whose names starts with "my/prefix/". + objects = client.list_objects("my-bucket", prefix="my/prefix/") + for obj in objects: + print(obj) # List objects information recursively. - objects = minio.list_objects('foo', recursive=True) - for object in objects: - print(object) + objects = client.list_objects("my-bucket", recursive=True) + for obj in objects: + print(obj) # List objects information recursively whose names starts with - # 'hello/'. - objects = minio.list_objects( - 'foo', prefix='hello/', recursive=True, + # "my/prefix/". + objects = client.list_objects( + "my-bucket", prefix="my/prefix/", recursive=True, ) - for object in objects: - print(object) + for obj in objects: + print(obj) # List objects information recursively after object name - # 'hello/world/1'. - objects = minio.list_objects( - 'foo', recursive=True, start_after='hello/world/1', + # "my/prefix/world/1". + objects = client.list_objects( + "my-bucket", recursive=True, start_after="my/prefix/world/1", ) - for object in objects: - print(object) + for obj in objects: + print(obj) """ return self._list_objects( bucket_name, @@ -1822,7 +1863,20 @@ def stat_object(self, bucket_name, object_name, ssec=None, version_id=None, :return: :class:`Object `. Example:: - stat = minio.stat_object("my-bucketname", "my-objectname") + # Get object information. + result = client.stat_object("my-bucket", "my-object") + + # Get object information of version-ID. + result = client.stat_object( + "my-bucket", "my-object", + version_id="dfbd25b3-abec-4184-a4e8-5a35a5c1174d", + ) + + # Get SSE-C encrypted object information. + result = client.stat_object( + "my-bucket", "my-object", + ssec=SseCustomerKey(b"32byteslongsecretkeymustprovided"), + ) """ check_bucket_name(bucket_name) @@ -1864,11 +1918,13 @@ def remove_object(self, bucket_name, object_name, version_id=None): :param version_id: Version ID of the object. Example:: - minio.remove_object("my-bucketname", "my-objectname") - minio.remove_object( - "my-bucketname", - "my-objectname", - version_id="13f88b18-8dcd-4c83-88f2-8631fdb6250c", + # Remove object. + client.remove_object("my-bucket", "my-object") + + # Remove version of an object. + client.remove_object( + "my-bucket", "my-object", + version_id="dfbd25b3-abec-4184-a4e8-5a35a5c1174d", ) """ check_bucket_name(bucket_name) @@ -1924,19 +1980,28 @@ def remove_objects(self, bucket_name, delete_object_list, object. Example:: - errors = minio.remove_objects( - "my-bucketname", + # Remove list of objects. + errors = client.remove_objects( + "my-bucket", [ - DeleteObject("my-objectname1"), - DeleteObject("my-objectname2"), + DeleteObject("my-object1"), + DeleteObject("my-object2"), DeleteObject( - "my-objectname3", - "13f88b18-8dcd-4c83-88f2-8631fdb6250c", + "my-object3", "13f88b18-8dcd-4c83-88f2-8631fdb6250c", ), ], ) for error in errors: print("error occured when deleting object", error) + + # Remove a prefix recursively. + delete_object_list = map( + lambda x: DeleteObject(x.object_name), + client.list_objects("my-bucket", "my/prefix/", recursive=True), + ) + errors = client.remove_objects("my-bucket", delete_object_list) + for error in errors: + print("error occured when deleting object", error) """ check_bucket_name(bucket_name) @@ -2143,7 +2208,7 @@ def delete_bucket_replication(self, bucket_name): :param bucket_name: Name of the bucket. Example:: - minio.delete_bucket_replication("my-bucketname") + client.delete_bucket_replication("my-bucket") """ check_bucket_name(bucket_name) self._execute("DELETE", bucket_name, query_params={"replication": ""}) @@ -2156,7 +2221,7 @@ def get_bucket_replication(self, bucket_name): :return: :class:`ReplicationConfig ` object. Example:: - config = minio.get_bucket_replication("my-bucketname") + config = client.get_bucket_replication("my-bucket") """ check_bucket_name(bucket_name) try: @@ -2199,7 +2264,7 @@ def set_bucket_replication(self, bucket_name, config): ), ], ) - minio.set_bucket_replication("my-bucketname", config) + client.set_bucket_replication("my-bucket", config) """ check_bucket_name(bucket_name) if not isinstance(config, ReplicationConfig): @@ -2220,7 +2285,7 @@ def delete_bucket_lifecycle(self, bucket_name): :param bucket_name: Name of the bucket. Example:: - minio.delete_bucket_lifecycle("my-bucketname") + client.delete_bucket_lifecycle("my-bucket") """ check_bucket_name(bucket_name) self._execute("DELETE", bucket_name, query_params={"lifecycle": ""}) @@ -2233,7 +2298,7 @@ def get_bucket_lifecycle(self, bucket_name): :return: :class:`LifecycleConfig ` object. Example:: - config = minio.get_bucket_lifecycle("my-bucketname") + config = client.get_bucket_lifecycle("my-bucket") """ check_bucket_name(bucket_name) try: @@ -2256,6 +2321,14 @@ def set_bucket_lifecycle(self, bucket_name, config): Example:: config = LifecycleConfig( [ + Rule( + ENABLED, + rule_filter=Filter(prefix="documents/"), + rule_id="rule1", + transition=Transition( + days=30, storage_class="GLACIER", + ), + ), Rule( ENABLED, rule_filter=Filter(prefix="logs/"), @@ -2264,7 +2337,7 @@ def set_bucket_lifecycle(self, bucket_name, config): ), ], ) - minio.set_bucket_lifecycle("my-bucketname", config) + client.set_bucket_lifecycle("my-bucket", config) """ check_bucket_name(bucket_name) if not isinstance(config, LifecycleConfig): @@ -2285,7 +2358,7 @@ def delete_bucket_tags(self, bucket_name): :param bucket_name: Name of the bucket. Example:: - minio.delete_bucket_tags("my-bucketname") + client.delete_bucket_tags("my-bucket") """ check_bucket_name(bucket_name) self._execute("DELETE", bucket_name, query_params={"tagging": ""}) @@ -2298,7 +2371,7 @@ def get_bucket_tags(self, bucket_name): :return: :class:`Tags ` object. Example:: - tags = minio.get_bucket_tags("my-bucketname") + tags = client.get_bucket_tags("my-bucket") """ check_bucket_name(bucket_name) try: @@ -2323,7 +2396,7 @@ def set_bucket_tags(self, bucket_name, tags): tags = Tags.new_bucket_tags() tags["Project"] = "Project One" tags["User"] = "jsmith" - minio.set_bucket_tags("my-bucketname", tags) + client.set_bucket_tags("my-bucket", tags) """ check_bucket_name(bucket_name) if not isinstance(tags, Tags): @@ -2346,7 +2419,7 @@ def delete_object_tags(self, bucket_name, object_name, version_id=None): :param version_id: Version ID of the Object. Example:: - minio.delete_object_tags("my-bucketname", "my-objectname") + client.delete_object_tags("my-bucket", "my-object") """ check_bucket_name(bucket_name) check_non_empty_string(object_name) @@ -2369,7 +2442,7 @@ def get_object_tags(self, bucket_name, object_name, version_id=None): :return: :class:`Tags ` object. Example:: - tags = minio.get_object_tags("my-bucketname", "my-objectname") + tags = client.get_object_tags("my-bucket", "my-object") """ check_bucket_name(bucket_name) check_non_empty_string(object_name) @@ -2402,7 +2475,7 @@ def set_object_tags(self, bucket_name, object_name, tags, version_id=None): tags = Tags.new_object_tags() tags["Project"] = "Project One" tags["User"] = "jsmith" - minio.set_object_tags("my-bucketname", "my-objectname", tags) + client.set_object_tags("my-bucket", "my-object", tags) """ check_bucket_name(bucket_name) check_non_empty_string(object_name) @@ -2431,7 +2504,7 @@ def enable_object_legal_hold( :param version_id: Version ID of the object. Example:: - minio.enable_object_legal_hold("my-bucketname", "my-objectname") + client.enable_object_legal_hold("my-bucket", "my-object") """ check_bucket_name(bucket_name) check_non_empty_string(object_name) @@ -2458,7 +2531,7 @@ def disable_object_legal_hold( :param version_id: Version ID of the object. Example:: - minio.disable_object_legal_hold("my-bucketname", "my-objectname") + client.disable_object_legal_hold("my-bucket", "my-object") """ check_bucket_name(bucket_name) check_non_empty_string(object_name) @@ -2485,9 +2558,10 @@ def is_object_legal_hold_enabled( :param version_id: Version ID of the object. Example:: - status = minio.is_object_legal_hold_enabled( - "my-bucketname", "my-objectname", - ) + if client.is_object_legal_hold_enabled("my-bucket", "my-object"): + print("legal hold is enabled on my-object") + else: + print("legal hold is not enabled on my-object") """ check_bucket_name(bucket_name) check_non_empty_string(object_name) @@ -2514,7 +2588,7 @@ def delete_object_lock_config(self, bucket_name): :param bucket_name: Name of the bucket. Example:: - minio.delete_object_lock_config("my-bucketname") + client.delete_object_lock_config("my-bucket") """ self.set_object_lock_config( self, bucket_name, ObjectLockConfig(None, None, None), @@ -2528,7 +2602,7 @@ def get_object_lock_config(self, bucket_name): :return: :class:`ObjectLockConfig ` object. Example:: - config = minio.get_object_lock_config("my-bucketname") + config = client.get_object_lock_config("my-bucket") """ check_bucket_name(bucket_name) response = self._execute( @@ -2545,7 +2619,7 @@ def set_object_lock_config(self, bucket_name, config): Example:: config = ObjectLockConfig(GOVERNANCE, 15, DAYS) - minio.set_object_lock_config("my-bucketname", config) + client.set_object_lock_condig("my-bucket", config) """ check_bucket_name(bucket_name) if not isinstance(config, ObjectLockConfig): @@ -2571,9 +2645,7 @@ def get_object_retention( :return: :class:`Retention ` object. Example:: - config = minio.get_object_retention( - "my-bucketname", "my-objectname", - ) + config = client.get_object_retention("my-bucket", "my-object") """ check_bucket_name(bucket_name) check_non_empty_string(object_name) @@ -2607,9 +2679,7 @@ def set_object_retention( config = Retention( GOVERNANCE, datetime.utcnow() + timedelta(days=10), ) - minio.set_object_retention( - "my-bucketname", "my-objectname", config, - ) + client.set_object_retention("my-bucket", "my-object", config) """ check_bucket_name(bucket_name) check_non_empty_string(object_name) From 1e2e53163b3cae1ffff93efaaec1d753f61c5669 Mon Sep 17 00:00:00 2001 From: "Bala.FA" Date: Mon, 7 Dec 2020 22:46:14 +0530 Subject: [PATCH 2/2] address review comments --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 5e20ab873..7a3b527c8 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ Python 3.6 or higher. ## Download using pip ```sh -pip install minio +pip3 install minio ``` ## Download source @@ -22,9 +22,9 @@ python setup.py install ``` ## Quick Start Example - File Uploader -This example program connects to an object storage server, makes a bucket on the server and then uploads a file to the bucket. +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 three items in order to connect to an object storage server. +You need the following items to connect to an S3-compatible object storage server: | Parameters | Description | |------------|------------------------------------------------------------| @@ -58,7 +58,7 @@ def main(): # Upload '/home/user/Photos/asiaphotos.zip' as object name # 'asiaphotos-2015.zip' to bucket 'asiatrip'. - client.put_object( + client.fput_object( "asiatrip", "asiaphotos-2015.zip", "/home/user/Photos/asiaphotos.zip", ) print(