Python SDKPythonPythonAistoreSdkObj

aistore.sdk.obj.object

View as Markdown

Module Contents

Classes

NameDescription
BucketDetailsMetadata about a bucket, used by objects within that bucket.
ObjectProvides methods for interacting with an object in AIS.

API

class aistore.sdk.obj.object.BucketDetails(
    name: str,
    provider: aistore.sdk.provider.Provider,
    qparams: typing.Dict[str, str],
    path: str
)
Dataclass

Metadata about a bucket, used by objects within that bucket.

name
str
path
str
provider
Provider
qparams
Dict[str, str]
class aistore.sdk.obj.object.Object(
    client: aistore.sdk.request_client.RequestClient,
    bck_details: aistore.sdk.obj.object.BucketDetails,
    name: str,
    props: typing.Optional[aistore.sdk.obj.object_props.ObjectProps] = None
)

Provides methods for interacting with an object in AIS.

Parameters:

client
RequestClient

Client used for all http requests.

bck_details
BucketDetails

Metadata about the bucket to which this object belongs.

name
str

Name of the object.

props
ObjectPropsDefaults to None

Properties of the object, as updated by head(), optionally pre-initialized.

_bck_path
= f'{URL_PATH_OBJECTS}/{bck_details.name}'
_object_path
= f'{self._bck_path}/{quote(name)}'
bucket_name
str

Name of the bucket where this object resides.

bucket_provider
Provider

Provider of the bucket where this object resides (e.g. ais, s3, gcp).

name
str

Name of this object.

props
ObjectProps

Get the latest properties of the object.

This will make a HEAD request to the AIStore cluster to fetch up-to-date object headers and refresh the internal _props cache. Use this when you want to ensure you’re accessing the most recent metadata for the object.

props_cached
Optional[ObjectProps]

Get the cached object properties (without making a network call).

This is useful when:

  • You want to avoid a network request.
  • You’re sure the cached _props was already set via a previous call to head() or during object construction.
query_params
Dict[str, str]

Query params used as a base for constructing all requests for this object.

uname
str

Unified name (uname) of this object, which combines the bucket path and object name.

aistore.sdk.obj.object.Object.blob_download(
    chunk_size: int = None,
    num_workers: int = None,
    latest: bool = False
) -> str

A special facility to download very large remote objects a.k.a. BLOBs Returns job ID that for the blob download operation.

Parameters:

chunk_size
intDefaults to None

chunk size in bytes

num_workers
intDefaults to None

number of concurrent blob-downloading workers (readers)

latest
boolDefaults to False

GET the latest object version from the associated remote bucket

Returns: str

Job ID (as str) that can be used to check the status of the operation

Raises:

  • aistore.sdk.errors.AISError: All other types of errors with AIStore
  • requests.ConnectionError: Connection error
  • requests.ConnectionTimeout: Timed out connecting to AIStore
  • requests.exceptions.HTTPError: Service unavailable
  • requests.RequestException: “There was an ambiguous exception that occurred while handling…”
aistore.sdk.obj.object.Object.copy(
    to_obj: aistore.sdk.obj.object.Object,
    etl: typing.Optional[aistore.sdk.etl.ETLConfig] = None,
    latest: bool = False,
    sync: bool = False
) -> requests.Response

Copy this object to another object (which specifies the destination bucket and name), optionally with ETL transformation.

Parameters:

to_obj
Object

Destination object specifying both the target bucket and object name

etl
ETLConfigDefaults to None

ETL configuration for transforming the object during copy

latest
boolDefaults to False

GET the latest object version from the associated remote bucket.

sync
boolDefaults to False

In addition to the latest, also entails removing remotely deleted objects

Returns: Response

The response from the copy operation

Raises:

  • requests.RequestException: “There’s an ambiguous exception that occurred while handling…”
  • requests.ConnectionError: Connection error
  • requests.ConnectionTimeout: Timed out connecting to AIStore
  • requests.ReadTimeout: Timed out waiting response from AIStore
  • requests.exceptions.HTTPError: Service unavailable
aistore.sdk.obj.object.Object.delete() -> requests.Response

Delete an object from a bucket.

Returns: Response

None

Raises:

  • requests.RequestException: “There was an ambiguous exception that occurred while handling…”
  • requests.ConnectionError: Connection error
  • requests.ConnectionTimeout: Timed out connecting to AIStore
  • requests.ReadTimeout: Timed out waiting response from AIStore
  • requests.exceptions.HTTPError(404): The object does not exist
aistore.sdk.obj.object.Object.get_reader(
    archive_config: typing.Optional[aistore.sdk.archive_config.ArchiveConfig] = None,
    blob_download_config: typing.Optional[aistore.sdk.blob_download_config.BlobDownloadConfig] = None,
    chunk_size: typing.Optional[int] = None,
    etl: typing.Optional[aistore.sdk.etl.ETLConfig] = None,
    writer: typing.Optional[io.BufferedWriter] = None,
    latest: bool = False,
    byte_range: typing.Optional[str] = None,
    direct: bool = False,
    num_workers: typing.Optional[int] = None
) -> aistore.sdk.obj.object_reader.ObjectReader

Creates and returns an ObjectReader with access to object contents and optionally writes to a provided writer.

Parameters:

archive_config
Optional[ArchiveConfig]Defaults to None

Settings for archive extraction.

blob_download_config
Optional[BlobDownloadConfig]Defaults to None

Settings for using blob download.

chunk_size
Optional[int]Defaults to None

Chunk size in bytes. For parallel downloads (num_workers set), defaults to the server-provided optimal size. For sequential reads, defaults to DEFAULT_CHUNK_SIZE.

etl
Optional[ETLConfig]Defaults to None

Settings for ETL-specific operations (name, args).

writer
Optional[BufferedWriter]Defaults to None

User-provided writer for writing content output. The user is responsible for closing the writer.

latest
boolDefaults to False

GET the latest object version from the associated remote bucket.

byte_range
Optional[str]Defaults to None

Byte range in RFC 7233 format for single-range requests (e.g., “bytes=0-499”, “bytes=500-”, “bytes=-500”). See: https://www.rfc-editor.org/rfc/rfc7233#section-2.1.

direct
boolDefaults to False

If True, the object content is read directly from the target node, bypassing the proxy.

num_workers
Optional[int]Defaults to None

If provided, enable parallel download — the object is split into byte ranges fetched concurrently by this many workers.

Returns: ObjectReader

An iterator for streaming object content.

Raises:

  • ValueError: If byte_range is used with blob_download_config.
  • requests.RequestException: If an error occurs during the request.
  • requests.ConnectionError: If there is a connection error.
  • requests.ConnectionTimeout: If the connection times out.
  • requests.ReadTimeout: If the read operation times out.
aistore.sdk.obj.object.Object.get_semantic_url() -> str

Get the semantic URL to the object

Returns: str

Semantic URL to get object

aistore.sdk.obj.object.Object.get_url(
    archpath: str = '',
    etl: typing.Optional[aistore.sdk.etl.ETLConfig] = None
) -> str

Get the full url to the object including base url and any query parameters

Parameters:

archpath
strDefaults to ''

If the object is an archive, use archpath to extract a single file from the archive

etl
ETLConfigDefaults to None

Settings for ETL-specific operations (name, meta).

Returns: str

Full URL to get object

aistore.sdk.obj.object.Object.get_writer() -> aistore.sdk.obj.object_writer.ObjectWriter

Create an ObjectWriter to write to object contents and attributes.

Returns: ObjectWriter

An ObjectWriter which can be used to write to an object’s contents and attributes.

aistore.sdk.obj.object.Object.head() -> requests.structures.CaseInsensitiveDict

Requests object properties and returns headers. Updates props.

Returns: CaseInsensitiveDict

Response header with the object properties.

Raises:

  • requests.RequestException: “There was an ambiguous exception that occurred while handling…”
  • requests.ConnectionError: Connection error
  • requests.ConnectionTimeout: Timed out connecting to AIStore
  • requests.ReadTimeout: Timed out waiting response from AIStore
  • requests.exceptions.HTTPError(404): The object does not exist
aistore.sdk.obj.object.Object.head_v2(
    props: str = ''
) -> aistore.sdk.obj.object_attributes.ObjectAttributesV2

Make a HEAD request with selective property retrieval (V2 API).

EXPERIMENTAL: This API is experimental and may change in future releases.

This method allows requesting specific object properties, reducing response size and processing overhead when only certain attributes are needed.

Parameters:

props
strDefaults to ''

Comma-separated list of properties to retrieve. Available values: name, size, version, checksum, atime, present, copies, ec, custom, location, chunked, last-modified, etag. See: https://github.com/NVIDIA/aistore/blob/main/api/apc/lsmsg.go If empty, returns default properties (name, size).

Returns: ObjectAttributesV2

Parsed V2 object attributes (includes chunk info, last-modified, etag).

aistore.sdk.obj.object.Object.multipart_upload() -> aistore.sdk.obj.multipart_upload.MultipartUpload

Create a multipart upload for this object.

Returns: MultipartUpload

A multipart upload instance for this object.

aistore.sdk.obj.object.Object.promote(
    path: str,
    target_id: str = '',
    recursive: bool = False,
    overwrite_dest: bool = False,
    delete_source: bool = False,
    src_not_file_share: bool = False
) -> str

Promotes a file or folder an AIS target can access to a bucket in AIS storage. These files can be either on the physical disk of an AIS target itself or on a network file system the cluster can access. See more info here: https://aiatscale.org/blog/2022/03/17/promote

Parameters:

path
str

Path to file or folder the AIS cluster can reach

target_id
strDefaults to ''

Promote files from a specific target node

recursive
boolDefaults to False

Recursively promote objects from files in directories inside the path

overwrite_dest
boolDefaults to False

Overwrite objects already on AIS

delete_source
boolDefaults to False

Delete the source files when done promoting

src_not_file_share
boolDefaults to False

Optimize if the source is guaranteed to not be on a file share

Returns: str

Job ID (as str) that can be used to check the status of the operation, or empty if job is done synchronously

Raises:

  • requests.RequestException: “There was an ambiguous exception that occurred while handling…”
  • requests.ConnectionError: Connection error
  • requests.ConnectionTimeout: Timed out connecting to AIStore
  • requests.ReadTimeout: Timed out waiting response from AIStore
  • AISError: Path does not exist on the AIS cluster storage