AIStore Python SDK

1.23.0 verified Mon Apr 27 auth: no python

Python client SDK for AIStore (AIS), a high-performance object storage cluster for AI and deep learning workloads. The SDK provides APIs to manage clusters, buckets, and objects, supporting S3-compatible and Google Cloud Storage backends. Current version is 1.23.0, compatible with AIS server clusters running version 4.x. Releases follow irregular cadence, roughly 1 minor version per month.

pip install aistore

Common errors

error ImportError: cannot import name 'Client' from 'aistore' ↓

cause Trying to import Client from the top-level aistore package instead of aistore.sdk.

fix

Use: from aistore.sdk import Client

error aistore.sdk.errors.AISConnectionError: Failed to connect to ... ↓

cause The client is trying to connect to a target node instead of the gateway/proxy, or the gateway is not reachable.

fix

Ensure AIS_ENDPOINT points to the proxy URL (usually http://<PROXY_IP>:8080) and that the proxy is running.

error aistore.sdk.errors.AISBadArgument: Bucket provider is required ↓

cause Attempting to access a remote bucket (S3, GCS) without specifying the provider.

fix

Pass provider='s3' or provider='gcs' to bucket() or create_bucket().

error AttributeError: 'Object' object has no attribute 'put_content' ↓

cause Using an older SDK version (<1.20.0) that still uses put_object/get_object.

fix

Upgrade to latest aistore with: pip install --upgrade aistore

Warnings

gotcha The SDK's client must point to the AIS gateway (proxy) endpoint, not a target node. Connecting directly to a target will fail for many operations. ↓

fix Use the proxy/gateway URL (usually port 8080).

gotcha When using S3 or GCS backends, you must add the provider argument (e.g., 's3' or 'gcs') when creating or accessing the bucket. Otherwise AIStore defaults to the AIS internal provider and will not see the remote bucket. ↓

fix client.create_bucket('my-bucket', provider='s3') or client.bucket('my-bucket', provider='s3').object('key').get()

deprecated The method `put_object` and `get_object` have been deprecated in favor of `object.put_content` and `object.get`. ↓

fix Use bucket.object('key').put_content(data) and bucket.object('key').get() instead.

breaking Starting from version 4.0 of the AIS server, the object metadata format changed (v2). SDK versions < 1.23.0 may not parse v2 metadata correctly, causing errors when listing objects. ↓

fix Update the SDK to >=1.23.0 to support server 4.x.

Imports

Client

wrong

from aistore import Client

correct

from aistore.sdk import Client

The SDK is in aistore.sdk subpackage

Bucket
```
from aistore.sdk import Bucket
```
Object
```
from aistore.sdk import Object
```

Quickstart

Create a client, a bucket, put and get an object

from aistore.sdk import Client

# Initialize client with AIS gateway endpoint
gateway_url = os.environ.get('AIS_ENDPOINT', 'http://localhost:8080')
client = Client(gateway_url)

# Create a bucket (if not exists)
try:
    client.create_bucket('my-bucket')
except Exception as e:
    print(f'Bucket may already exist: {e}')

# Put an object
bucket = client.bucket('my-bucket')
bucket.object('hello.txt').put_content('Hello, AIStore!')

# Get the object back
obj = bucket.object('hello.txt').get()
print(obj.read_text())  # Hello, AIStore!