The Replit Object Storage Client is the official Python SDK for managing interactions with Replit Object Storage. This lets you programmatically copy, delete, upload, and download objects within Replit Object Storage buckets.
This reference guide explains the Client
class from the replit-object-storage-python
package and provides code examples for its class methods.
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:
Use the following code to create a Client
instance that interacts with Replit Object Storage:
If your app uses multiple buckets, create one Client
instance per bucket.
The init
method initializes an instance of the Client class.
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.The copy
method copies an object within the same bucket. If an object exists in the same location, it overwrites the original.
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.The delete
method permanently removes an object from Object Storage.
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.The download_as_bytes
method retrieves the contents of an object as 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.The download_as_text
method downloads the contents of an object as a str
type.
Argument:
object_name
(str) - The source object name to retrieve.Returns:
Raises:
ObjectNotFoundError
- Indicates the object does not exist.Downloads the contents of an object into a file on the local disk.
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.The exists
method checks if an object exists.
Argument:
object_name
(str) - The name of the object to check for existence.Returns:
bool
: True
if the object exists, False otherwise.The list
method lists objects in the Bucket.
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.Use upload_from_filename()
to upload an object from a source file on the local disk to Object Storage.
Arguments:
dest_object_name
(str) - The name of the uploaded file.src_filename
(str) - The source file to upload.The upload_from_bytes
method uploads an object from bytes
data.
Arguments:
dest_object_name
(str) - The name of the object to upload.src_data
(str) - The bytes
data to upload.The upload_from_text
method uploads an object from a string.
Arguments:
dest_object_name
(str) - The name of the object to upload.src_data
(str)- The text data to upload.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.
The following sections provide code examples for managing your files using the Replit Object Storage SDK.