Pre-beta updates (#3)

* Rework errors, add integration tests

* Pull out .replit change

* Lint fix

* Promote to 0.0.1

* Run tests during prerelease

* Multi-language support

* Relock

* Rename to new package

* Update installation for semaphore

* Fix semaphore

* Fix env

* Final cut

* Update readme

Author: Harrison Unruh

.gitignore

@@ -2,9 +2,11 @@
 .pythonlibs
 .pytest_cache
 .ruff_cache
+.tox
 .upm
 
 # Python
+.local
 __pycache__
 
 # Builds and Testing

.semaphore/semaphore.yml

@@ -32,7 +32,7 @@ blocks:
             - make lint
     dependencies:
       - install deps
-  - name: unit test
+  - name: test-unit
     task:
       prologue:
         commands:

Makefile

@@ -10,12 +10,20 @@ lint:
 lint-fix:
 	@poetry run ruff check src tests --fix
 
+.PHONY: test-integration
+test-integration:
+	@poetry run pytest --cov-report term-missing --cov=./src ./tests/integration
+
+.PHONY: test-integration-multi-language
+test-integration-multi-language:
+	@tox
+
 .PHONY: test-unit
 test-unit:
 	@poetry run pytest --cov-report term-missing --cov=./src ./tests/unit
 
 .PHONY: prerelease
-prerelease:
+prerelease: test-unit test-integration-multi-language
 	@rm -rf dist
 	@poetry build
 

README.md

@@ -1,36 +1,40 @@
-# replit-storage-python
-The library for Replit Object Storage. Development should "just work" on Replit!
+# replit-object-storage-python
+The library for interacting with Replit's Object Storage service, on Replit.
 
-## Development
+## Usage
 
-To get setup, run:
-```bash
-make install
+### Setup
+
+Start by importing the Object Storage Client:
+```python
+from replit.object_storage import Client
 ```
 
-To run the linter, run:
-```bash
-make lint
+Then to use the Client:
+```python
+client = Client()
 ```
 
-or to fix (fixable) lint issues, run:
-```bash
-make lint-fix
+### Downloading an Object
+
+```python
+contents = client.download_as_text("file.json")
 ```
 
-To run tests, run:
-```bash
-make test
+### Uploading an Object
+
+```python
+client.upload_from_text("file.json", data)
 ```
 
-## Release
+### List Objects
 
-To check that the package builds, you can run:
-```bash
-make prerelease
+```python
+client.list()
 ```
 
-To perform a release, first bump the version in `pyproject.toml`. Then run:
-```bash
-make release
-```
+### Delete an Object
+
+```python
+contents = client.delete("file.json")
+```

development.md

@@ -0,0 +1,36 @@
+# replit-object-storage-python
+The library for Replit Object Storage. Development should "just work" on Replit!
+
+## Development
+
+To get setup, run:
+```bash
+make install
+```
+
+To run the linter, run:
+```bash
+make lint
+```
+
+or to fix (fixable) lint issues, run:
+```bash
+make lint-fix
+```
+
+To run tests, run:
+```bash
+make test
+```
+
+## Release
+
+To check that the package builds, you can run:
+```bash
+make prerelease
+```
+
+To perform a release, first bump the version in `pyproject.toml`. Then run:
+```bash
+make release
+```

poetry.lock

@@ -1,25 +1,24 @@
 [tool.poetry]
-name = "replit.storage"
-version = "0.0.1.a3"
+name = "replit.object_storage"
+version = "0.0.2"
 description = "A library for interacting with Object Storage on Replit"
 authors = ["Repl.it <contact@repl.it>"]
 license = "ISC"
 readme = "README.md"
-repository = "https://github.com/replit/replit-storage-python"
-homepage = "https://github.com/replit/replit-storage-python"
+repository = "https://github.com/replit/replit-object-storage-python"
+homepage = "https://github.com/replit/replit-object-storage-python"
 classifiers = [
     "Programming Language :: Python :: 3",
     "License :: OSI Approved :: ISC License (ISCL)",
     "Operating System :: OS Independent",
 ]
 packages = [
   { include = "replit", from = "src" },
-  { include = "tests" }
 ]
 exclude = ["tests"]
 
 [tool.poetry.dependencies]
-python = ">=3.10.0,<3.11"
+python = ">=3.8.0,<3.13"
 google-cloud-storage = "^2.14.0"
 requests = "^2.31.0"
 
@@ -28,6 +27,7 @@ ruff = "^0.1.15"
 pytest = "^8.0.0"
 twine = "*"
 pytest-cov = "^4.1.0"
+tox = "^4.13.0"
 
 [tool.pyright]
 # https://github.com/microsoft/pyright/blob/main/docs/configuration.md

pyproject.toml

@@ -1,3 +1,8 @@
 { pkgs }: {
-  deps = [];
+  deps = [
+    pkgs.python38
+    pkgs.python39
+    pkgs.python311
+    pkgs.python312
+  ];
 }

replit.nix

@@ -0,0 +1,5 @@
+"""Public interface for the replit.object_storage library."""
+
+from replit.object_storage.client import Client
+from replit.object_storage.errors import DefaultBucketError
+from replit.object_storage.object import Object

src/replit/object_storage/__init__.py

@@ -4,13 +4,19 @@
 many docstrings are borrowed from the underlying library.
 """
 
-from typing import Optional
+from typing import List, Optional
 
 import requests
 from google.auth import identity_pool
 from google.cloud import storage
-from replit.storage.config import REPLIT_ADC, REPLIT_DEFAULT_BUCKET_URL
-from replit.storage.errors import DefaultBucketError
+from google.cloud.exceptions import NotFound
+from replit.object_storage.config import REPLIT_ADC, REPLIT_DEFAULT_BUCKET_URL
+from replit.object_storage.errors import (
+  DefaultBucketError,
+  ObjectNotFoundError,
+  google_error_handler,
+)
+from replit.object_storage.object import Object
 
 
 class Client:
@@ -39,14 +45,41 @@ def __init__(self, bucket_id: Optional[str] = None):
     self.__gcs_client = storage.Client(credentials=creds, project="")
     self.__gcs_bucket_handle = None
 
-  def delete(self, object_name: str) -> None:
+  @google_error_handler
+  def copy(self, object_name: str, dest_object_name: str) -> None:
+    """Copies the specified object within the same bucket.
+
+    If an object exists in the same location, it will be overwritten.
+
+    Args:
+        object_name: The full path of the object to be copied.
+        dest_object_name: The full path to copy the object to.
+    """
+    source_object = self.__object(object_name)
+    bucket = self.__bucket()
+    bucket.copy_blob(
+      source_object,
+      bucket,
+      dest_object_name,
+    )
+
+  @google_error_handler
+  def delete(self, object_name: str, ignore_not_found: bool = False) -> None:
     """Deletes an object from Object Storage.
 
     Args:
         object_name: The name of the object to be deleted.
+        ignore_not_found: Whether an error should be raised if the object does not
+          exist.
     """
-    return self.__object(object_name).delete()
+    try:
+      return self.__object(object_name).delete()
+    except NotFound as err:
+      if ignore_not_found:
+        return
+      raise ObjectNotFoundError("The requested object could not be found.") from err
 
+  @google_error_handler
   def download_as_bytes(self, object_name: str) -> bytes:
     """Download the contents an object as a bytes object.
 
@@ -55,23 +88,16 @@ def download_as_bytes(self, object_name: str) -> bytes:
     """
     return self.__object(object_name).download_as_bytes()
 
-  def download_as_string(self, object_name: str) -> str:
+  @google_error_handler
+  def download_as_text(self, object_name: str) -> str:
     """Download the contents an object as a string.
 
     Args:
         object_name: The name of the object to be downloaded.
     """
     return self.__object(object_name).download_as_text()
 
-  def download_to_file(self, object_name: str, dest_file) -> None:
-    """Download the contents an object into a file-like object.
-
-    Args:
-        object_name: The name of the object to be downloaded.
-        dest_file: A file-like object.
-    """
-    return self.__object(object_name).download_to_file(dest_file)
-
+  @google_error_handler
   def download_to_filename(self, object_name: str, dest_filename: str) -> None:
     """Download the contents an object into a file on the local disk.
 
@@ -81,6 +107,7 @@ def download_to_filename(self, object_name: str, dest_filename: str) -> None:
     """
     return self.__object(object_name).download_to_filename(dest_filename)
 
+  @google_error_handler
   def exists(self, object_name: str) -> bool:
     """Checks if an object exist.
 
@@ -89,15 +116,42 @@ def exists(self, object_name: str) -> bool:
     """
     return self.__object(object_name).exists()
 
-  def upload_from_file(self, dest_object_name: str, src_file) -> None:
-    """Uploads the contents of a file-like object.
+  @google_error_handler
+  def list(
+      self,
+      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]:
+    """Lists objects in the bucket.
 
     Args:
-        dest_object_name: The name of the object to be uploaded.
-        src_file: A file-like object.
+        end_offset: Filter results to objects whose names are lexicographically
+            before end_offset. If start_offset is also set, the objects listed
+            have names between start_offset (inclusive) and end_offset
+            (exclusive).
+        match_glob: Glob pattern used to filter results, for example foo*bar.
+        max_results: The maximum number of results that can be returned in the
+            response.
+        prefix: Filter results to objects who names have the specified prefix.
+        start_offset: Filter results to objects whose names are
+            lexicographically equal to or after start_offset. If endOffset is
+            also set, the objects listed have names between start_offset
+            (inclusive) and end_offset (exclusive).
+        
     """
-    self.__object(dest_object_name).upload_from_file(src_file)
-
+    iter = self.__bucket().list_blobs(
+        end_offset=end_offset,
+        match_glob=match_glob,
+        max_results=max_results,
+        prefix=prefix,
+        start_offset=start_offset,
+    )
+    return [Object(name=object.name) for object in iter]
+
+  @google_error_handler
   def upload_from_filename(self, dest_object_name: str,
                            src_filename: str) -> None:
     """Upload an object from a file on the local disk.
@@ -108,7 +162,8 @@ def upload_from_filename(self, dest_object_name: str,
     """
     self.__object(dest_object_name).upload_from_filename(src_filename)
 
-  def upload_from_string(self, dest_object_name: str, src_data: str) -> None:
+  @google_error_handler
+  def upload_from_text(self, dest_object_name: str, src_data: str) -> None:
     """Upload an object from a string.
 
     Args:
@@ -117,11 +172,13 @@ def upload_from_string(self, dest_object_name: str, src_data: str) -> None:
     """
     self.__object(dest_object_name).upload_from_string(src_data)
 
-  def __object(self, object_name: str) -> storage.Blob:
+  def __bucket(self) -> storage.Bucket:
     if self.__gcs_bucket_handle is None:
       self.__gcs_bucket_handle = self.__get_bucket_handle()
+    return self.__gcs_bucket_handle
 
-    return self.__gcs_bucket_handle.blob(object_name)
+  def __object(self, object_name: str) -> storage.Blob:
+    return self.__bucket().blob(object_name)
 
   def __get_bucket_handle(self) -> storage.Bucket:
     if self.__bucket_id is None: