Object Storage Python SDK

This reference guide explains the Client class from the replit-object-storage-python package and provides code examples for its class methods.

​

Client

The Client class manages interactions with Replit Object Storage. This class features methods for performing operations on objects in a bucket.

To import the class from the replit.object_storage package, add the following line to your Python code:

from replit.object_storage import Client

Use the following code to create a Client instance that interacts with Replit Object Storage:

client = Client()

​

__init__

The init method initializes an instance of the Client class.

def __init__(bucket_id: Optional[str] = None)

Argument:

• bucket_id (Optional[str]): The ID of the bucket the client manages. When omitted, the Client uses the default bucket associated with the Replit App or Deployment.

​

copy

The copy method copies an object within the same bucket. If an object exists in the same location, it overwrites the original.

def copy(object_name: str, dest_object_name: str) -> None

Arguments:

• object_name (str) - The full path of the source object.
• dest_object_name (str) - The full path of the object destination.

Raises:

• ObjectNotFoundError - Indicates the source object does not exist at the specified path.

​

delete

The delete method permanently removes an object from Object Storage.

def delete(object_name: str, ignore_not_found: bool = False) -> None

Arguments:

• object_name (str) - The name of the object to delete.
• ignore_not_found (bool) - When True, suppress the error if the object does not exist.

Raises:

• ObjectNotFoundError - Indicates the object does not exist.

​

download_as_bytes

The download_as_bytes method retrieves the contents of an object as bytes.

def download_as_bytes(object_name: str) -> bytes

Argument:

• object_name (str) - The name of the object to download.

Returns:

• bytes- The raw byte representation of the object’s contents.

Raises:

• ObjectNotFoundError - Indicates the object does not exist.

​

download_as_text

The download_as_text method downloads the contents of an object as a str type.

def download_as_text(object_name: str) -> str

Argument:

• object_name (str) - The source object name to retrieve.

Returns:

• str: The object’s contents as a UTF-8 encoded string.

Raises:

• ObjectNotFoundError - Indicates the object does not exist.

​

download_to_filename

Downloads the contents of an object into a file on the local disk.

def download_to_filename(object_name: str, dest_filename: str) -> None

Arguments:

• object_name (str) - The name of the source object from Object Storage to retrieve.
• dest_filename (str) - The destination filename on local disk.

Raises:

• ObjectNotFoundError - Indicates the object does not exist.

​

exists

The exists method checks if an object exists.

def exists(object_name: str) -> bool

Argument:

• object_name (str) - The name of the object to check for existence.

Returns:

• bool: True if the object exists, False otherwise.

​

list

The list method lists objects in the Bucket.

def list(end_offset: Optional[str] = None,
         match_glob: Optional[str] = None,
         max_results: Optional[int] = None,
         prefix: Optional[str] = None,
         start_offset: Optional[str] = None) -> List[Object]

Arguments:

• end_offset(Optional[str]) - Filter results to objects named lexicographically before end_offset. If start_offset is defined, the objects listed have names between start_offset (inclusive) and end_offset (exclusive).
• match_glob (Optional[str]) - Use a glob pattern to filter results. For example: “foo*bar” matches “footbar”, “foo baz bar”, and “foobar”.
• max_results (Optional[int]) - The maximum number of results to return in the response.
• prefix (Optional[str]) - Filter results to objects whose names have the specified prefix.
• start_offset (Optional[str]) - Filter results to objects whose names are lexicographically equal to or after start_offset. When end_offset is set, the objects listed have names between start_offset (inclusive) and end_offset (exclusive).

Returns:

• List(Object): A list of objects matching the given query parameters.

​

upload_from_filename

Use upload_from_filename() to upload an object from a source file on the local disk to Object Storage.

def upload_from_filename(dest_object_name: str, src_filename: str) -> None

Arguments:

• dest_object_name(str) - The name of the uploaded file.
• src_filename(str) - The source file to upload.

​

upload_from_bytes

The upload_from_bytes method uploads an object from bytes data.

def upload_from_bytes(dest_object_name: str, src_data: bytes) -> None

Arguments:

• dest_object_name(str) - The name of the object to upload.
• src_data(str) - The bytes data to upload.

​

upload_from_text

The upload_from_text method uploads an object from a string.

def upload_from_text(dest_object_name: str, src_data: Union[bytes, str]) -> None

Arguments:

• dest_object_name(str) - The name of the object to upload.
• src_data(str)- The text data to upload.

​

Exception types

• When interacting with Replit Object Storage using the Client, any method might return one of the following errors:

  • BucketNotFoundError: Indicates the configured bucket name does not match with any bucket in Object Storage.

  • DefaultBucketError: Indicates missing default bucket configuration.

  • ForbiddenError: Indicates insufficient permissions to access to the bucket.

  • TooManyRequestsError: Indicates the operation is rate-limited due to excessive requests.

  • UnauthorizedError: Indicates authorization restricted access to the operation.

​

Class method examples

The following sections provide code examples for managing your files using the Replit Object Storage SDK.

​

Retrieve an object as text

client.download_as_text("file.json")

​

Retrieve raw bytes of an object

client.download_as_bytes("file.png")

​

Download an object to the local filesystem

client.download_to_filename("file.json", dest_filename)

​

List objects in the bucket

client.list()

​

Upload an object from text

client.upload_from_text("file.json", data)

​

Upload an object as bytes

client.upload_from_bytes("file.png", data)

​

Upload an object from the filesystem

client.upload_from_filename("file.json", src_filename)

​

Delete an object from the bucket

client.delete("file.json")