aiooss2

0.2.11 verified Fri May 01 auth: no python

Async client for Alibaba Cloud OSS (Object Storage Service), built on oss2 and aiohttp/asyncio. Current version 0.2.11, released Mar 2024. Low release cadence (last release 0.2.11). Requires Python >=3.8.

pip install aiooss2

Common errors

error RuntimeError: Cannot close a running event loop ↓

cause Calling await bucket.close() or service.close() inside a running event loop.

fix

Remove explicit close() or restructure to avoid closing inside loop; typically service is closed after all operations.

error AttributeError: module 'aiooss2' has no attribute 'AioBucket' ↓

cause Importing from aiooss2 before version 0.2.5 where top-level exports were added.

fix

Upgrade to >=0.2.5 or import from lower level: from aiooss2.bucket import AioBucket

error oss2.exceptions.RequestError: ('Connection aborted.', ...) ↓

cause Missing or incorrect endpoint; often wrong region or protocol mismatch.

fix

Ensure endpoint string includes 'https://' prefix, e.g., 'https://oss-cn-hangzhou.aliyuncs.com'.

Warnings

gotcha AioBucket and AioService require an event loop to be running. Do not instantiate them before asyncio.run() or outside async context. ↓

fix Always create AioBucket/AioService inside a coroutine, typically after asyncio.run(main()).

gotcha For resumable_upload and resumable_download, the source argument must be a file path string, not a file-like object. Passing a file object silently fails. ↓

fix Use string path: await resumable_upload(bucket, 'remote_key', '/local/path')

gotcha The async methods on AioBucket return coroutines directly; no need to wrap in asyncio.ensure_future(). Failing to await them will raise RuntimeWarning. ↓

fix Always await: result = await bucket.put_object(...)

deprecated Using positional arguments for endpoints is deprecated in favor of keyword arguments for clarity. ↓

fix Use AioBucket(auth, bucket_name, endpoint_name) with explicit keyword or positional as per current docs.

Imports

AioBucket
wrong
```
from aiooss2.bucket import AioBucket
```
correct
```
from aiooss2 import AioBucket
```
AioBucket is exposed at top-level; do not import from submodule.
AioService
```
from aiooss2 import AioService
```
resumable_upload
```
from aiooss2 import resumable_upload
```
resumable_download
```
from aiooss2 import resumable_download
```

Quickstart

Basic usage: create Auth, AioBucket, list objects, upload file.

import asyncio
from aiooss2 import AioBucket, AioService, Auth

async def main():
    auth = Auth(os.environ.get('OSS_ACCESS_KEY_ID', ''), os.environ.get('OSS_ACCESS_KEY_SECRET', ''))
    service = AioService(auth, 'https://oss-cn-hangzhou.aliyuncs.com')
    bucket = AioBucket(auth, 'my-bucket', 'oss-cn-hangzhou')
    # List objects
    async for obj in bucket.list_objects():
        print(obj.key)
    # Upload file
    with open('local.txt', 'rb') as f:
        result = await bucket.put_object('remote.txt', f)
    await service.close()

asyncio.run(main())