Asynchronous MinIO Client SDK

Common errors

• TypeError: object asyncio.coroutine can't be used in 'await' expression

  cause Attempting to call an asynchronous `miniopy-async` method without the `await` keyword, or calling an async function in a synchronous context.
  fix Ensure all calls to `miniopy-async` methods are prefixed with `await` (e.g., `await client.list_buckets()`). Also, ensure your main execution flow uses `asyncio.run(your_async_main_function())`.

• ConnectionRefusedError: [Errno 111] Connection refused

  cause The MinIO server is either not running, not accessible from your environment, or the `endpoint` specified in `Minio` client initialization is incorrect (e.g., wrong host or port).
  fix Verify that your MinIO server is running and accessible. Double-check the `endpoint` (e.g., `localhost:9000`) used when creating the `Minio` client instance.

• miniopy_async.S3Error: [{'Code': 'NoSuchBucket', 'Message': 'The specified bucket does not exist'}]

  cause An operation was attempted on a MinIO bucket that does not exist, or the bucket name provided has a typo.
  fix Check the bucket name for accuracy. If you intend to create the bucket, ensure your credentials have the necessary permissions and call `client.make_bucket()` first.

Warnings

• breaking Python 3.8 and 3.9 are deprecated and no longer officially supported due to type hinting requirements.
  Fix: Upgrade your Python environment to version 3.10 or newer to ensure full compatibility and access to all features.
• gotcha All `miniopy-async` methods are coroutines and *must* be `await`ed. Forgetting `await` will result in a `TypeError` or unexpected behavior.
  Fix: Always prefix calls to `miniopy_async.Minio` methods (e.g., `client.list_buckets()`, `client.put_object()`) with the `await` keyword within an `async` function.
• breaking The `Minio` constructor gained a `server_url` parameter, intended to replace `change_host` for specifying the server endpoint for presigned URLs.
  Fix: If generating presigned URLs and needing to specify a different host, use the `server_url` parameter in the `Minio` constructor instead of deprecated methods.
• gotcha The `content-length-range` format for policy conditions in presigned URLs changed from integers to strings.
  Fix: Ensure that `content-length-range` values are passed as strings, e.g., `['1', '10485760']`, rather than integers.

Install

• pip install miniopy-async Install stable version

Imports

• Minio
  wrong:

  from minio import Minio

  correct:

  from miniopy_async import Minio

  Using 'minio' directly will import the synchronous client, not the async wrapper.
• S3Error
  wrong:

  from minio.error import S3Error

  correct:

  from miniopy_async import S3Error

  While 'minio.error.S3Error' exists, it's best to import from 'miniopy_async' for consistency.

Quickstart

This quickstart demonstrates how to initialize the `Minio` client, list existing buckets, and create a new bucket asynchronously. Ensure your MinIO server endpoint and credentials are provided via environment variables or directly in the code for execution.

import os
import asyncio
from miniopy_async import Minio, S3Error

async def main():
    endpoint = os.environ.get("MINIO_ENDPOINT", "localhost:9000")
    access_key = os.environ.get("MINIO_ACCESS_KEY", "minioadmin")
    secret_key = os.environ.get("MINIO_SECRET_KEY", "minioadmin")
    secure = os.environ.get("MINIO_SECURE", "false").lower() == "true"

    client = Minio(
        endpoint=endpoint,
        access_key=access_key,
        secret_key=secret_key,
        secure=secure
    )

    try:
        # Example: List all buckets
        buckets = await client.list_buckets()
        print(f"Successfully connected to MinIO. Found {len(buckets)} buckets:")
        for bucket in buckets:
            print(f"  - {bucket.name} (created at {bucket.creation_date})")

        # Example: Make a bucket if it doesn't exist
        test_bucket = "my-test-bucket"
        found = await client.bucket_exists(test_bucket)
        if not found:
            await client.make_bucket(test_bucket)
            print(f"Bucket '{test_bucket}' created successfully.")
        else:
            print(f"Bucket '{test_bucket}' already exists.")

    except S3Error as e:
        print(f"MinIO S3 Error: {e.code} - {e.message}")
    except Exception as e:
        print(f"An unexpected error occurred: {e}")

if __name__ == "__main__":
    # Ensure MinIO_ENDPOINT, MINIO_ACCESS_KEY, MINIO_SECRET_KEY are set
    # or MinIO is running locally with default credentials (minioadmin:minioadmin)
    asyncio.run(main())