|
| 1 | +"""Client for interacting with Object Storage. This is the top-level interface. |
| 2 | +
|
| 3 | +Note: this Client is a thin wrapper over the GCS Python Library. As a result, |
| 4 | +many docstrings are borrowed from the underlying library. |
| 5 | +""" |
| 6 | + |
| 7 | +from typing import Optional |
| 8 | + |
| 9 | +import requests |
| 10 | +from google.auth import identity_pool |
| 11 | +from google.cloud import storage |
| 12 | +from replit.storage.config import REPLIT_ADC, REPLIT_DEFAULT_BUCKET_URL |
| 13 | +from replit.storage.errors import DefaultBucketError |
| 14 | + |
| 15 | + |
| 16 | +class Client: |
| 17 | + """Client manages interactions with Replit Object Storage. |
| 18 | + |
| 19 | + If multiple buckets are used within an application, one Client should be used |
| 20 | + per bucket. |
| 21 | + """ |
| 22 | + |
| 23 | + __gcs_client: storage.Client |
| 24 | + |
| 25 | + __bucket_id: Optional[str] = None |
| 26 | + __gcs_bucket_handle: Optional[storage.Bucket] = None |
| 27 | + |
| 28 | + def __init__(self, bucket_id: Optional[str] = None): |
| 29 | + """Creates a new Client. |
| 30 | +
|
| 31 | + Args: |
| 32 | + bucket_id: The ID of the bucket this Client should interface with. |
| 33 | + If no ID is defined, the Repl / Deployment's default bucket will be |
| 34 | + used. |
| 35 | + """ |
| 36 | + creds = identity_pool.Credentials(**REPLIT_ADC) |
| 37 | + if bucket_id: |
| 38 | + self.__bucket_id = bucket_id |
| 39 | + self.__gcs_client = storage.Client(credentials=creds, project="") |
| 40 | + self.__gcs_bucket_handle = None |
| 41 | + |
| 42 | + def delete(self, object_name: str) -> None: |
| 43 | + """Deletes an object from Object Storage. |
| 44 | +
|
| 45 | + Args: |
| 46 | + object_name: The name of the object to be deleted. |
| 47 | + """ |
| 48 | + return self.__object(object_name).delete() |
| 49 | + |
| 50 | + def download_as_bytes(self, object_name: str) -> bytes: |
| 51 | + """Download the contents an object as a bytes object. |
| 52 | +
|
| 53 | + Args: |
| 54 | + object_name: The name of the object to be downloaded. |
| 55 | + """ |
| 56 | + return self.__object(object_name).download_as_bytes() |
| 57 | + |
| 58 | + def download_as_string(self, object_name: str) -> str: |
| 59 | + """Download the contents an object as a string. |
| 60 | +
|
| 61 | + Args: |
| 62 | + object_name: The name of the object to be downloaded. |
| 63 | + """ |
| 64 | + return self.__object(object_name).download_as_text() |
| 65 | + |
| 66 | + def download_to_file(self, object_name: str, dest_file) -> None: |
| 67 | + """Download the contents an object into a file-like object. |
| 68 | +
|
| 69 | + Args: |
| 70 | + object_name: The name of the object to be downloaded. |
| 71 | + dest_file: A file-like object. |
| 72 | + """ |
| 73 | + return self.__object(object_name).download_to_file(dest_file) |
| 74 | + |
| 75 | + def download_to_filename(self, object_name: str, dest_filename: str) -> None: |
| 76 | + """Download the contents an object into a file on the local disk. |
| 77 | +
|
| 78 | + Args: |
| 79 | + object_name: The name of the object to be downloaded. |
| 80 | + dest_filename: The filename of the file on the local disk to be written. |
| 81 | + """ |
| 82 | + return self.__object(object_name).download_to_filename(dest_filename) |
| 83 | + |
| 84 | + def exists(self, object_name: str) -> bool: |
| 85 | + """Checks if an object exist. |
| 86 | +
|
| 87 | + Args: |
| 88 | + object_name: The name of the object to be checked. |
| 89 | + """ |
| 90 | + return self.__object(object_name).exists() |
| 91 | + |
| 92 | + def upload_from_file(self, dest_object_name: str, src_file) -> None: |
| 93 | + """Uploads the contents of a file-like object. |
| 94 | +
|
| 95 | + Args: |
| 96 | + dest_object_name: The name of the object to be uploaded. |
| 97 | + src_file: A file-like object. |
| 98 | + """ |
| 99 | + self.__object(dest_object_name).upload_from_file(src_file) |
| 100 | + |
| 101 | + def upload_from_filename(self, dest_object_name: str, |
| 102 | + src_filename: str) -> None: |
| 103 | + """Upload an object from a file on the local disk. |
| 104 | +
|
| 105 | + Args: |
| 106 | + dest_object_name: The name of the object to be uploaded. |
| 107 | + src_filename: The filename of a file on the local disk |
| 108 | + """ |
| 109 | + self.__object(dest_object_name).upload_from_filename(src_filename) |
| 110 | + |
| 111 | + def upload_from_string(self, dest_object_name: str, src_data: str) -> None: |
| 112 | + """Upload an object from a string. |
| 113 | +
|
| 114 | + Args: |
| 115 | + dest_object_name: The name of the object to be uploaded. |
| 116 | + src_data: The text to be uploaded. |
| 117 | + """ |
| 118 | + self.__object(dest_object_name).upload_from_string(src_data) |
| 119 | + |
| 120 | + def __object(self, object_name: str) -> storage.Blob: |
| 121 | + if self.__gcs_bucket_handle is None: |
| 122 | + self.__gcs_bucket_handle = self.__get_bucket_handle() |
| 123 | + |
| 124 | + return self.__gcs_bucket_handle.blob(object_name) |
| 125 | + |
| 126 | + def __get_bucket_handle(self) -> storage.Bucket: |
| 127 | + if self.__bucket_id is None: |
| 128 | + self.__bucket_id = self.__get_default_bucket_id() |
| 129 | + return self.__gcs_client.bucket(self.__bucket_id) |
| 130 | + |
| 131 | + @staticmethod |
| 132 | + def __get_default_bucket_id() -> str: |
| 133 | + response = requests.get(REPLIT_DEFAULT_BUCKET_URL) |
| 134 | + try: |
| 135 | + response.raise_for_status() |
| 136 | + except requests.HTTPError as exc: |
| 137 | + raise DefaultBucketError("failed to request default bucket") from exc |
| 138 | + |
| 139 | + bucket_id = response.json().get("bucketId", "") |
| 140 | + if bucket_id == "": |
| 141 | + raise DefaultBucketError("no default bucket was specified, it may need " |
| 142 | + "to be configured in .replit") |
| 143 | + |
| 144 | + return bucket_id |
0 commit comments