> ## 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

> Learn how to use the official Python SDK to manage files in Replit App Storage.

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")
```