Python SDKPythonPythonAistoreSdk

aistore.sdk.client

View as Markdown

Module Contents

Classes

NameDescription
ClientAIStore client for managing buckets, objects, and ETL jobs.

API

class aistore.sdk.client.Client(
    endpoint: str,
    skip_verify: bool = False,
    ca_cert: typing.Optional[str] = None,
    client_cert: typing.Optional[typing.Union[str, typing.Tuple[str, str]]] = None,
    timeout: typing.Optional[typing.Union[float, typing.Tuple[float, float]]] = None,
    retry_config: typing.Optional[aistore.sdk.retry_config.RetryConfig] = None,
    token: typing.Optional[str] = None,
    max_pool_size: typing.Optional[int] = None
)

AIStore client for managing buckets, objects, and ETL jobs.

Parameters:

endpoint
str

AIStore endpoint.

skip_verify
boolDefaults to False

If True, skip SSL certificate verification. If False (default), the ‘AIS_SKIP_VERIFY’ environment variable is also checked.

ca_cert
strDefaults to None

Path to a CA certificate file for SSL verification. If not provided, the ‘AIS_CLIENT_CA’ environment variable will be used. Defaults to None.

client_cert
Union[str, Tuple[str, str], None]Defaults to None

Path to a client certificate PEM file or a tuple (cert, key) for mTLS. If not provided, ‘AIS_CRT’ and ‘AIS_CRT_KEY’ environment variables will be used. Defaults to None.

timeout
Union[float, Tuple[float, float], None]Defaults to None

Timeout for HTTP requests.

  • Single float (e.g., 5.0): Applies to both connection and read timeouts.
  • Tuple (e.g., (3.0, 20.0)): First value is the connection timeout, second is the read timeout.
  • Tuple with 0 (e.g., (0, 20.0) or (3.0, 0)): Use 0 to disable specific timeout.
  • 0 or 0.0 or (0, 0): Disables all timeouts.
  • None (default): Check environment variables ‘AIS_CONNECT_TIMEOUT’ and ‘AIS_READ_TIMEOUT’. If env var is set to 0, that specific timeout is disabled. Defaults to (3, 20) if not set.
retry_config
RetryConfigDefaults to None

Defines retry behavior for HTTP and network failures. If not provided, the default retry configuration (RetryConfig.default()) is used.

token
strDefaults to None

Authorization token. If not provided, the ‘AIS_AUTHN_TOKEN’ environment variable will be used. Defaults to None.

max_pool_size
intDefaults to None

Maximum number of connections per host in the connection pool. If not provided, the ‘AIS_MAX_CONN_POOL’ environment variable will be used, or defaults to 10.

_DEFAULT_CONNECT_TIMEOUT
= 3
_DEFAULT_MAX_POOL_SIZE
= 10
_DEFAULT_READ_TIMEOUT
= 20
_request_client
retry_config
aistore.sdk.client.Client._parse_timeout_from_env(
    env_var_name: str,
    default_value: float
) -> typing.Optional[float]
staticmethod

Parse a timeout value from an environment variable.

Parameters:

env_var_name
str

Name of the environment variable to read

default_value
float

Default value to use if not set or parsing fails

Returns: Optional[float]

Parsed timeout value (None if 0, float otherwise), or default if invalid

aistore.sdk.client.Client._resolve_max_pool_size(
    max_pool_size: typing.Optional[int]
) -> int
staticmethod

Resolve max_pool_size value from parameter or environment variable.

Priority: explicit parameter > environment variable > default

Parameters:

max_pool_size
Optional[int]

max_pool_size parameter passed to init

Returns: int

Resolved max_pool_size value

aistore.sdk.client.Client._resolve_timeout(
    timeout: typing.Optional[typing.Union[float, typing.Tuple[float, float]]]
) -> typing.Optional[typing.Union[float, typing.Tuple[float, float]]]
staticmethod

Resolve timeout value from parameter or environment variables.

Priority: explicit parameter > environment variables > defaults

Special handling:

  • timeout=0 or timeout=(0, 0) -> None (disable all timeouts)
  • timeout=(0, 20) or timeout=(3, 0) -> convert 0 to None for that specific timeout
  • timeout=None (default) -> check env vars, fallback to (3, 20)
  • timeout=<value> -> use as-is (with 0 converted to None)
  • AIS_CONNECT_TIMEOUT=0 -> None for connect timeout (no limit)
  • AIS_READ_TIMEOUT=0 -> None for read timeout (no limit)
  • Both env vars=0 -> None (disable all timeouts)

Parameters:

timeout
Optional[Union[float, Tuple[float, float]]]

Timeout parameter passed to init

Returns: Optional[Union[float, Tuple[float, float]]]

Resolved timeout value, tuple (connect, read), or None if disabled

aistore.sdk.client.Client.batch(
    objects: typing.Union[typing.List[aistore.sdk.obj.object.Object], aistore.sdk.obj.object.Object, str, typing.List[str]] = None,    objects: typing.Union[typing.List[aistore.sdk.obj.object.Object], aistore.sdk.obj.object.Object, str, typing.List[str]] = None,
    bucket: typing.Optional[aistore.sdk.bucket.Bucket] = None,
    output_format: str = EXT_TAR,
    cont_on_err: bool = True,
    only_obj_name: bool = False,
    streaming_get: bool = True,
    colocation: aistore.sdk.enums.Colocation = Colocation.NONE
)

Factory constructor for Get-Batch API (MOSS - Multi-Object Streaming Service).

Efficiently retrieve multiple objects, archive files, or byte ranges in a single request, reducing network overhead and improving throughput for ML training workloads.

Parameters:

objects
Optional[Union[List[Object], Object, str, List[str]]]Defaults to None

Objects to retrieve. Can be:

  • Single object name: “file.txt”
  • List of names: [“file1.txt”, “file2.txt”]
  • Single Object instance
  • List of Object instances
  • None (add objects later via batch.add()) Note: if objects are specified as raw names (str or list of str), bucket must be provided
bucket
Optional[Bucket]Defaults to None

Default bucket for all objects

output_format
strDefaults to EXT_TAR

Archive format (tar, tgz, zip). Defaults to “.tar”

cont_on_err
boolDefaults to True

Continue on errors (missing files under 404/). Defaults to True

only_obj_name
boolDefaults to False

Use only obj name in archive path. Defaults to False

streaming_get
boolDefaults to True

Stream resulting archive prior to finalizing it in memory. Defaults to True

colocation
ColocationDefaults to Colocation.NONE

Colocation hint for optimization. Defaults to Colocation.NONE.

  • Colocation.NONE: no optimization - suitable for uniformly distributed data
  • Colocation.TARGET_AWARE: target-aware - objects are collocated on few targets
  • Colocation.TARGET_AND_SHARD_AWARE: target and shard-aware - enables archive handle reuse

Returns:

Batch object for building and executing Get-Batch requests

aistore.sdk.client.Client.bucket(
    bck_name: str,
    provider: typing.Union[aistore.sdk.provider.Provider, str] = Provider.AIS,
    namespace: aistore.sdk.types.Namespace = None
)

Factory constructor for bucket object. Does not make any HTTP request, only instantiates a bucket object.

Parameters:

bck_name
str

Name of bucket

provider
str or ProviderDefaults to Provider.AIS

Provider of bucket, one of “ais”, “aws”, “gcp”, … (optional, defaults to ais)

namespace
NamespaceDefaults to None

Namespace of bucket (optional, defaults to None)

Returns:

The bucket object created.

aistore.sdk.client.Client.cluster()

Factory constructor for cluster object. Does not make any HTTP request, only instantiates a cluster object.

Returns:

The cluster object created.

aistore.sdk.client.Client.dsort(
    dsort_id: str = ''
)

Factory constructor for dSort object. Contains APIs related to AIStore dSort operations. Does not make any HTTP request, only instantiates a dSort object.

Parameters:

dsort_id
strDefaults to ''

ID of the dSort job

Returns:

dSort object created

aistore.sdk.client.Client.etl(
    etl_name: str
)

Factory constructor for ETL object. Contains APIs related to AIStore ETL operations. Does not make any HTTP request, only instantiates an ETL object.

Parameters:

etl_name
str

Name of the ETL

Returns:

The ETL object created.

aistore.sdk.client.Client.get_object_from_url(
    url: str
) -> aistore.sdk.obj.object.Object

Creates an Object instance from a URL.

This method does not make any HTTP requests.

Parameters:

url
str

Full URL of the object (e.g., “ais://bucket1/file.txt”)

Returns: Object

The object constructed from the specified URL

Raises:

  • InvalidURLException: If the URL is invalid.
aistore.sdk.client.Client.job(
    job_id: str = '',
    job_kind: str = ''
)

Factory constructor for job object, which contains job-related functions. Does not make any HTTP request, only instantiates a job object.

Parameters:

job_id
strDefaults to ''

Optional ID for interacting with a specific job

job_kind
strDefaults to ''

Optional specific type of job empty for all kinds

Returns:

The job object created.