S3

Object storage — upload, download, list, copy, and delete

The S3 sub-client provides access to the IYREE S3-compatible object storage. Management operations go through the gateway; data operations use presigned URLs to interact with S3 directly.

from iyree import IyreeClient

with IyreeClient(api_key="my-key") as client:
    client.s3.upload_object("data/report.csv", b"id,value\n1,100")
    data = client.s3.download_object("data/report.csv")

---

Methods

list_objects

List objects under a prefix (single page). For auto-pagination, use list_objects_iter.

page = client.s3.list_objects(prefix="data/", max_keys=100)
for obj in page.objects:
    print(obj.key, obj.size)

Parameters

prefix · str · default: "\"\""

Key prefix filter. Only objects whose keys start with this prefix are returned.

max_keys · int · default: "1000"

Maximum number of keys per page.

continuation_token · str

Token from a previous page for pagination. Use page.next_continuation_token.

Returns S3ListResult

objects · List[S3Object]

Objects in this page.

Show S3Object

key · str

Object key.

size · int

Object size in bytes.

last_modified · datetime

Last modification timestamp.

etag · str

Entity tag (hash of the object content).

next_continuation_token · str

Token for fetching the next page, or None if this is the last page.

is_truncated · bool

Whether more pages are available.

key_count · int

Number of keys returned in this page.

---

list_objects_iter

Auto-paginating iterator over all S3 objects matching a prefix. Handles pagination automatically.

for obj in client.s3.list_objects_iter(prefix="data/"):
    print(obj.key, obj.size)

Parameters

prefix · str · default: "\"\""

Key prefix filter.

max_keys · int · default: "1000"

Maximum number of keys per page (controls internal page size).

Yields S3Object

Yields individual S3Object instances across all pages.

---

upload_object

Upload an object using a presigned PUT URL.

client.s3.upload_object("reports/q1.csv", b"id,revenue\n1,5000")

Parameters

key · str · required

Destination object key (the “path” in the bucket).

data · bytes | str | BinaryIO · required

Upload payload. Strings are UTF-8 encoded. File-like objects are read to bytes.

content_type · str · default: "\"application/octet-stream\""

MIME type of the object.

client.s3.upload_object("page.html", html_bytes, content_type="text/html")

Returns None

Errors

Exception	Condition
IyreeS3Error	Upload failed (HTTP error from S3)

---

download_object

Download an object and return its contents as bytes.

data = client.s3.download_object("data/report.csv")
print(data.decode("utf-8"))

Parameters

key · str · required

Object key to download.

Returns bytes

The object contents.

Errors

Exception	Condition
IyreeS3Error	Download failed (HTTP error from S3)

---

download_object_to_file

Download an object and stream it directly to a local file. Memory-efficient for large files.

client.s3.download_object_to_file("data/large.csv", "/tmp/large.csv")

Parameters

key · str · required

Object key to download.

path · str | Path · required

Local file path to write to. Parent directories must exist.

Returns None

Errors

Exception	Condition
IyreeS3Error	Download failed (HTTP error from S3)

---

copy_object

Copy an object within the bucket.

result = client.s3.copy_object("data/report.csv", "archive/report_backup.csv")
print(result.destination_key)  # "archive/report_backup.csv"

Parameters

source_key · str · required

Key of the source object.

destination_key · str · required

Key for the destination copy.

Returns S3CopyResult

source_key · str

The source object key.

destination_key · str

The destination object key.

---

delete_objects

Delete one or more objects in a single request. Partial failures are returned in the result — no exception is raised.

result = client.s3.delete_objects(["tmp/file1.csv", "tmp/file2.csv"])
print(f"Deleted: {result.deleted}")
if result.errors:
    for err in result.errors:
        print(f"Failed: {err.key} — {err.message}")

Parameters

keys · List[str] · required

List of object keys to delete.

Returns S3DeleteResult

deleted · List[str]

Keys that were successfully deleted.

errors · List[S3DeleteError]

Errors for objects that could not be deleted.

Show S3DeleteError

key · str

Object key that failed.

code · str

Error code from S3.

message · str

Error description.

---

upload_dataframe

Upload a pandas DataFrame as CSV or Parquet. Requires iyree[pandas].

import pandas as pd

df = pd.DataFrame({"id": [1, 2], "revenue": [5000, 8000]})
client.s3.upload_dataframe("reports/q1.parquet", df, format="parquet")

Parameters

key · str · required

Destination object key.

df · pd.DataFrame · required

The DataFrame to upload.

format · str · default: "\"csv\""

Output format: "csv" or "parquet".

Returns None

Errors

Exception	Condition
ImportError	pandas is not installed
ValueError	Unsupported format (not csv or parquet)

---

Examples

Upload and download

client.s3.upload_object("config/settings.json", '{"debug": true}', content_type="application/json")

data = client.s3.download_object("config/settings.json")
import json
settings = json.loads(data)
print(settings)  # {"debug": True}