Package: r2connect
R2ConnectThe R2Connect Python module provides a convenient interface for performing common operations on AWS S3 buckets while being compatible with Cloudflare's R2 service. It allows you to create, delete, upload, download and delete objects in an S3 bucket. It also allows creating and deleting buckets, handling various exceptions that might occur during these operations.Table of ContentsInstallationInitialisationUsageCreate a BucketDelete a BucketUpload a FileDownload a FileDelete a FileException HandlingInstallationYou can install theR2Connectmodule using pip:pipinstallr2connectInitialisationBefore initialising anR2Clientclass, make sure to set the following environment variables:ENDPOINT_URL: The endpoint URL for your AWS S3 or Cloudflare R2 service.ACCESS_KEY: Your AWS S3 or Cloudflare R2 access key.SECRET_KEY: Your AWS S3 or Cloudflare R2 secret key.REGION: The AWS S3 region (Cloudflare doesn't require a region but defaults tous-east-1)To initialise an R2Client class, follow the example below:fromr2connect.r2clientimportR2Clienttry:r2_client=R2Client()exceptr2connect.exceptions.cloudflare.r2.MissingConfigaserror:# A required environment variable is missingprint(error)UsageTo use theR2Clientclass, follow the examples below:Create a BucketWith Cloudflare's R2 service, onlyus-east-1can be used. R2 uses the region for AWS compatibility only.fromr2connect.r2clientimportR2Client# Initialise the R2Client class (as shown in the previous section)# ...bucket_name="my-new-bucket"region="us-east-1"# Must be us-east-1 when using Cloudflare R2try:r2_client.create_bucket(bucket_name,region)exceptr2connect.exceptions.cloudflare.r2.BucketAlreadyExistsaserror:print(f"The specified bucket already exists:{bucket_name}")exceptExceptionaserror:print(error)Delete a BucketA bucket can be deleted in two ways. If the bucket is not empty you can attempt a safe delete which will only delete if the bucket is empty.
You can also set theforce_deleteflag to True which will delete the bucket and its contents. Below is an example for each:Safe delete a bucketfromr2connect.r2clientimportR2Client# Initialise the R2Client class (as shown in the previous section)# ...bucket_name="my-existing-bucket"try:r2_client.delete(bucket_name)exceptr2connect.exceptions.cloudflare.r2.BucketDoesNotExistaserror:print(f"The specified bucket does not exist:{bucket_name}")exceptr2connect.exceptions.cloudflare.r2.BucketIsNotEmptyaserror:print(f"The specified bucket is not empty, cannt safe delete:{bucket_name}")exceptExceptionaserror:print(error)Force delete a bucketfromr2connect.r2clientimportR2Client# Initialise the R2Client class (as shown in the previous section)# ...bucket_name="my-existing-bucket"try:r2_client.delete(bucket_name,force_delete=True)exceptr2connect.exceptions.cloudflare.r2.BucketDoesNotExistaserror:print(f"The specified bucket does not exist:{bucket_name}")exceptExceptionaserror:print(error)Upload a Filefromr2connect.r2clientimportR2Client# Initialise the R2Client class (as shown in the previous section)# ...bucket_name="my-existing-bucket"file_path="path/to/you/file.txt"object_name="file.txt"try:r2_client.upload_file(file_path,object_name,bucket_name)exceptr2connect.exceptions.cloudflare.r2.BucketDoesNotExistaserror:print(f"The specified bucket does not exist:{bucket_name}")exceptr2connect.exceptions.cloudflare.r2.ObjectAlreadyExistsaserror:print(f"An object with the same object_key already exists:{object_name}")exceptExceptionaserror:print(error)Download a FileA save filepath can be specified but is not required. If one isn't provided, the file will be saved in the same execution level
with theuser_idas the prefix and thefilenameas the suffix.fromr2connect.r2clientimportR2Client# Initialise the R2Client class (as shown in the previous section)# ...bucket_name="my-existing-bucket"download_file_path="path/to/you/file.txt"object_name="file.txt"try:r2_client.download_file(object_name,bucket_name,download_file_path)exceptr2connect.exceptions.cloudflare.r2.ObjectDoesNotExistaserror:print(f"The specified file does not exist:{object_name}")exceptr2connect.exceptions.cloudflare.r2.BucketDoesNotExistaserror:print(f"The specified bucket does not exist:{bucket_name}")exceptExceptionaserror:print(error)Delete a Filefromr2connect.r2clientimportR2Client# Initialise the R2Client class (as shown in the previous section)# ...bucket_name="my-existing-bucket"object_name="file.txt"try:r2_client.delete_file(object_name,bucket_name)exceptr2connect.exceptions.cloudflare.r2.ObjectDoesNotExistaserror:print(f"The specified object does not exist in this bucket:{object_name}")exceptr2connect.exceptions.cloudflare.r2.BucketDoesNotExistaserror:print(f"The specified bucket does not exist:{bucket_name}")exceptExceptionaserror:print(error)Exception HandlingTheR2Connectmodule provides exception handling for various scenarios.BucketAlreadyExists: Raised when attempting to create a bucket that already exists.BucketDoesNotExist: Raised when the specified bucket does not exist.BucketIsNotEmpty: Raised when trying to delete a non-empty bucket without specifyingforce_delete=TrueObjectDoesNotExist: Raised when attempting operation on a non-existing object.ObjectAlreadyExists: Raised when trying to upload an object with the same name as an existing object.MissingConfig: Raised when trying to initialise anR2Clientobject without the required environment variables.