# Source: https://docs.replit.com/reference/object-storage-python-sdk.md

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.replit.com/llms.txt
> Use this file to discover all available pages before exploring further.

# App Storage Python SDK

> The Replit App Storage Client is the official Python SDK for managing interactions with Replit App Storage. This lets you programmatically copy, delete, upload, and download objects within Replit App Storage buckets.

This reference guide explains the `Client` class from the `replit-object-storage-python` package and provides code examples for its class methods.

## Client

The `Client` class manages interactions with Replit App 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:

```python  theme={null}
from replit.object_storage import Client
```

Use the following code to create a `Client` instance that interacts with Replit App Storage:

```python  theme={null}
client = Client()
```

<Tip>
  If your app uses multiple buckets, create one `Client` instance per bucket.
</Tip>

### \_\_init\_\_

The `init` method initializes an instance of the Client class.

```python  theme={null}
def __init__(bucket_id: Optional[str] = None)
```

**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.

### copy

The `copy` method copies an object within the same bucket. If an object exists in the same location, it overwrites the original.

```python  theme={null}
def copy(object_name: str, dest_object_name: str) -> None
```

**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.

### delete

The `delete` method permanently removes a file from App Storage.

```python  theme={null}
def delete(object_name: str, ignore_not_found: bool = False) -> None
```

**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.

### download\_as\_bytes

The `download_as_bytes` method retrieves the contents of a file as `bytes`.

```python  theme={null}
def download_as_bytes(object_name: str) -> 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.

### download\_as\_text

The `download_as_text` method downloads the contents of a file as a `str` type.

```python  theme={null}
def download_as_text(object_name: str) -> str
```

**Argument**:

* `object_name` (str) - The source object name to retrieve.

**Returns**:

* str: The object's contents as a UTF-8 encoded string.

**Raises**:

* `ObjectNotFoundError` - Indicates the object does not exist.

### download\_to\_filename

Downloads the contents of an object into a file on the local disk.

```python  theme={null}
def download_to_filename(object_name: str, dest_filename: str) -> None
```

**Arguments**:

* `object_name` (str) - The name of the source object from App Storage to retrieve.
* `dest_filename` (str) - The destination filename on local disk.

**Raises**:

* `ObjectNotFoundError` - Indicates the object does not exist.

### exists

The `exists` method checks if an object exists.

```python  theme={null}
def exists(object_name: str) -> bool
```

**Argument**:

* `object_name` (str) - The name of the object to check for existence.

**Returns**:

* `bool`: `True` if the object exists, False otherwise.

### list

The `list` method lists objects in the Bucket.

```python  theme={null}
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]
```

**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.

### upload\_from\_filename

Use `upload_from_filename()` to upload an object from a source file on the local disk to App Storage.

```python  theme={null}
def upload_from_filename(dest_object_name: str, src_filename: str) -> None
```

**Arguments**:

* `dest_object_name`(str) - The name of the uploaded file.
* `src_filename`(str) - The source file to upload.

### upload\_from\_bytes

The `upload_from_bytes` method uploads an object from `bytes` data.

```python  theme={null}
def upload_from_bytes(dest_object_name: str, src_data: bytes) -> None
```

**Arguments**:

* `dest_object_name`(str) - The name of the object to upload.
* `src_data`(str) - The `bytes` data to upload.

### upload\_from\_text

The `upload_from_text` method uploads an object from a string.

```python  theme={null}
def upload_from_text(dest_object_name: str, src_data: Union[bytes, str]) -> None
```

**Arguments**:

* `dest_object_name`(str) - The name of the object to upload.
* `src_data`(str)- The text data to upload.

### Exception types

* When interacting with Replit App 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 App 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.

## Class method examples

The following sections provide code examples for managing your objects using the Replit App Storage SDK.

### Retrieve a file as text

```python  theme={null}
client.download_as_text("file.json")
```

### Retrieve raw bytes of a file

```python  theme={null}
client.download_as_bytes("file.png")
```

### Download a file to the local filesystem

```python  theme={null}
client.download_to_filename("file.json", dest_filename)
```

### List objects in the bucket

```python  theme={null}
client.list()
```

### Upload a file from text

```python  theme={null}
client.upload_from_text("file.json", data)
```

### Upload a file as bytes

```python  theme={null}
client.upload_from_bytes("file.png", data)
```

### Upload a objects from the filesystem

```python  theme={null}
client.upload_from_filename("file.json", src_filename)
```

### Delete an object from the bucket

```python  theme={null}
client.delete("file.json")
```