Version 1 release (#5)

Author: Harrison Unruh

.replit

@@ -1,5 +1,4 @@
 entrypoint = "main.py"
-modules = ["python-3.10:v18-20230807-322e88b"]
 
 hidden = [".pythonlibs"]
 

Makefile

@@ -1,3 +1,7 @@
+.PHONY: docs
+docs:
+	@poetry run pydoc-markdown
+
 .PHONY: install
 install:
 	@poetry install
@@ -16,7 +20,7 @@ test-integration:
 
 .PHONY: test-integration-multi-language
 test-integration-multi-language:
-	@tox
+	@poetry run tox
 
 .PHONY: test-unit
 test-unit:

development.md

@@ -23,6 +23,13 @@ To run tests, run:
 make test
 ```
 
+## Docs
+
+To generate the markdown docs, run:
+```bash
+make docs
+```
+
 ## Release
 
 To check that the package builds, you can run:

docs/replit/__init__.md

@@ -0,0 +1,2 @@
+# replit
+

docs/replit/object_storage/__init__.md

@@ -0,0 +1,4 @@
+# replit.object\_storage
+
+Public interface for the replit.object_storage library.
+

docs/replit/object_storage/_config.md

@@ -0,0 +1,4 @@
+# replit.object\_storage.\_config
+
+Configurations for external interactions managed by the library.
+

docs/replit/object_storage/client.md

@@ -0,0 +1,230 @@
+# replit.object\_storage.client
+
+Client for interacting with Object Storage. This is the top-level interface.
+
+Note: this Client is a thin wrapper over the GCS Python Library. As a result,
+many docstrings are borrowed from the underlying library.
+
+## Class Client
+
+```python
+class Client()
+```
+
+Client manages interactions with Replit Object Storage.
+
+If multiple buckets are used within an application, one Client should be used
+per bucket
+
+Any method may return one of the following errors:
+- `BucketNotFoundError`: If the bucket configured for the client could not be found.
+- `DefaultBucketError`: If no bucket was explicitly configured and an error occurred
+    when resolving the default bucket.
+- `ForbiddenError`: If access to the requested resource is not allowed.
+- `TooManyRequestsError`: If rate limiting occurs.
+- `UnauthorizedError`: If the requested operation is not allowed.
+
+#### \_\_init\_\_
+
+```python
+def __init__(bucket_id: Optional[str] = None)
+```
+
+Creates a new Client.
+
+**Arguments**:
+
+- `bucket_id` - The ID of the bucket this Client should interface with.
+  If no ID is defined, the Repl / Deployment's default bucket will be
+  used.
+
+#### copy
+
+```python
+def copy(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.
+
+**Arguments**:
+
+- `object_name` - The full path of the object to be copied.
+- `dest_object_name` - The full path to copy the object to.
+  
+
+**Raises**:
+
+- `ObjectNotFoundError` - If the source object could not be found.
+
+#### delete
+
+```python
+def delete(object_name: str, ignore_not_found: bool = False) -> None
+```
+
+Deletes an object from Object Storage.
+
+**Arguments**:
+
+- `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.
+  
+
+**Raises**:
+
+- `ObjectNotFoundError` - If the object could not be found.
+
+#### download\_as\_bytes
+
+```python
+def download_as_bytes(object_name: str) -> bytes
+```
+
+Download the contents an object as a bytes object.
+
+**Arguments**:
+
+- `object_name` - The name of the object to be downloaded.
+  
+
+**Returns**:
+
+  The raw byte representation of the object's contents.
+  
+
+**Raises**:
+
+- `ObjectNotFoundError` - If the object could not be found.
+
+#### download\_as\_text
+
+```python
+def download_as_text(object_name: str) -> str
+```
+
+Download the contents an object as a string.
+
+**Arguments**:
+
+- `object_name` - The name of the object to be downloaded.
+  
+
+**Returns**:
+
+  The object's contents as a UTF-8 encoded string.
+  
+
+**Raises**:
+
+- `ObjectNotFoundError` - If the object could not be found.
+
+#### download\_to\_filename
+
+```python
+def download_to_filename(object_name: str, dest_filename: str) -> None
+```
+
+Download the contents an object into a file on the local disk.
+
+**Arguments**:
+
+- `object_name` - The name of the object to be downloaded.
+- `dest_filename` - The filename of the file on the local disk to be written.
+  
+
+**Raises**:
+
+- `ObjectNotFoundError` - If the object could not be found.
+
+#### exists
+
+```python
+def exists(object_name: str) -> bool
+```
+
+Checks if an object exist.
+
+**Arguments**:
+
+- `object_name` - The name of the object to be checked.
+  
+
+**Returns**:
+
+  Whether or not the object exists.
+
+#### list
+
+```python
+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]
+```
+
+Lists objects in the bucket.
+
+**Arguments**:
+
+- `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).
+  
+
+**Returns**:
+
+  A list of objects matching the given query parameters.
+
+#### upload\_from\_filename
+
+```python
+def upload_from_filename(dest_object_name: str, src_filename: str) -> None
+```
+
+Upload an object from a file on the local disk.
+
+**Arguments**:
+
+- `dest_object_name` - The name of the object to be uploaded.
+- `src_filename` - The filename of a file on the local disk
+
+#### upload\_from\_bytes
+
+```python
+def upload_from_bytes(dest_object_name: str, src_data: bytes) -> None
+```
+
+Upload an object from bytes.
+
+**Arguments**:
+
+- `dest_object_name` - The name of the object to be uploaded.
+- `src_data` - The bytes to be uploaded.
+
+#### upload\_from\_text
+
+```python
+def upload_from_text(dest_object_name: str, src_data: Union[bytes,
+                                                            str]) -> None
+```
+
+Upload an object from a string.
+
+**Arguments**:
+
+- `dest_object_name` - The name of the object to be uploaded.
+- `src_data` - The text to be uploaded.
+

docs/replit/object_storage/errors.md

@@ -0,0 +1,52 @@
+# replit.object\_storage.errors
+
+Errors that may be returned by the storage library.
+
+## Class BucketNotFoundError
+
+```python
+class BucketNotFoundError(Exception)
+```
+
+BucketNotFoundError may occur if the specified bucket could not be found.
+
+## Class DefaultBucketError
+
+```python
+class DefaultBucketError(Exception)
+```
+
+DefaultBucketError may occur if the default bucket could not be resolved.
+
+## Class ForbiddenError
+
+```python
+class ForbiddenError(Exception)
+```
+
+ForbiddenError may occur if access to the requested resource is not allowed.
+
+## Class ObjectNotFoundError
+
+```python
+class ObjectNotFoundError(Exception)
+```
+
+ObjectNotFoundError may occur if the requested object could not be found.
+
+## Class TooManyRequestsError
+
+```python
+class TooManyRequestsError(Exception)
+```
+
+TooManyRequestsError may occur if the rate of requests exceeds the rate limit.
+
+## Class UnauthorizedError
+
+```python
+class UnauthorizedError(Exception)
+```
+
+UnauthorizedError may occur if the requested operation is not allowed.
+

docs/replit/object_storage/object.md

@@ -0,0 +1,17 @@
+# replit.object\_storage.object
+
+Pythonic representation of an object in Object Storage.
+
+## Class Object
+
+```python
+@dataclass
+class Object()
+```
+
+Object contains metadata about an object.
+
+**Attributes**:
+
+- `name` - The name of the object.
+

docs/sidebar.json

@@ -0,0 +1,24 @@
+{
+  "items": [
+    {
+      "items": [
+        {
+          "items": [
+            "replit/object_storage/__init__",
+            "replit/object_storage/_config",
+            "replit/object_storage/client",
+            "replit/object_storage/errors",
+            "replit/object_storage/object"
+          ],
+          "label": "replit.object_storage",
+          "type": "category"
+        },
+        "replit/__init__"
+      ],
+      "label": "replit",
+      "type": "category"
+    }
+  ],
+  "label": "Reference",
+  "type": "category"
+}