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

> 공식 Python SDK를 사용하여 Replit App Storage에서 파일을 관리하는 방법을 알아보세요.

이 참조 가이드는 `replit-object-storage-python` 패키지의 `Client` 클래스를 설명하고, 클래스 메서드에 대한 코드 예제를 제공합니다.

## Client

`Client` 클래스는 Replit App Storage와의 상호작용을 관리합니다. 이 클래스는 bucket 내 object에 대한 작업을 수행하는 메서드를 제공합니다.

`replit.object_storage` 패키지에서 클래스를 가져오려면 Python 코드에 다음 줄을 추가하세요:

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

다음 코드를 사용하여 Replit App Storage와 상호작용하는 `Client` 인스턴스를 생성하세요:

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

<Tip>
  앱이 여러 bucket을 사용하는 경우, bucket당 하나의 `Client` 인스턴스를 생성하세요.
</Tip>

### \_\_init\_\_

`init` 메서드는 Client 클래스의 인스턴스를 초기화합니다.

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

**Argument**:

* `bucket_id` (Optional\[str]): 클라이언트가 관리하는 bucket의 ID입니다. 생략하면 Client는 Replit App 또는 Deployment에 연결된 기본 bucket을 사용합니다.

### copy

`copy` 메서드는 동일한 bucket 내에서 object를 복사합니다. 동일한 위치에 object가 이미 존재하는 경우 원본을 덮어씁니다.

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

**Arguments**:

* `object_name` (str) - 소스 object의 전체 경로입니다.
* `dest_object_name` (str) - object 대상의 전체 경로입니다.

**Raises**:

* `ObjectNotFoundError` - 지정된 경로에 소스 object가 존재하지 않음을 나타냅니다.

### delete

`delete` 메서드는 App Storage에서 파일을 영구적으로 삭제합니다.

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

**Arguments**:

* `object_name` (str) - 삭제할 object의 이름입니다.
* `ignore_not_found` (bool) - `True`이면 object가 존재하지 않을 때 오류를 억제합니다.

**Raises**:

* `ObjectNotFoundError` - object가 존재하지 않음을 나타냅니다.

### download\_as\_bytes

`download_as_bytes` 메서드는 파일의 내용을 `bytes`로 가져옵니다.

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

**Argument**:

* `object_name` (str) - 다운로드할 object의 이름입니다.

**Returns**:

* `bytes`- object 내용의 원시 바이트 표현입니다.

**Raises**:

* `ObjectNotFoundError` - object가 존재하지 않음을 나타냅니다.

### download\_as\_text

`download_as_text` 메서드는 파일의 내용을 `str` 타입으로 다운로드합니다.

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

**Argument**:

* `object_name` (str) - 가져올 소스 object 이름입니다.

**Returns**:

* str: UTF-8 인코딩 문자열로 된 object의 내용입니다.

**Raises**:

* `ObjectNotFoundError` - object가 존재하지 않음을 나타냅니다.

### download\_to\_filename

로컬 디스크의 파일에 object의 내용을 다운로드합니다.

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

**Arguments**:

* `object_name` (str) - App Storage에서 가져올 소스 object의 이름입니다.
* `dest_filename` (str) - 로컬 디스크의 대상 파일 이름입니다.

**Raises**:

* `ObjectNotFoundError` - object가 존재하지 않음을 나타냅니다.

### exists

`exists` 메서드는 object가 존재하는지 확인합니다.

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

**Argument**:

* `object_name` (str) - 존재 여부를 확인할 object의 이름입니다.

**Returns**:

* `bool`: object가 존재하면 `True`, 그렇지 않으면 False입니다.

### list

`list` 메서드는 bucket 내 object를 나열합니다.

```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]) - 결과를 `end_offset`보다 사전식으로 앞에 있는 이름의 object로 필터링합니다. `start_offset`이 정의된 경우, 나열된 object의 이름은 `start_offset`(포함)과 `end_offset`(제외) 사이에 있습니다.
* `match_glob` (Optional\[str]) - glob 패턴을 사용하여 결과를 필터링합니다. 예: "foo\*bar"는 "footbar", "foo baz bar", "foobar"와 일치합니다.
* `max_results` (Optional\[int]) - 응답에서 반환할 최대 결과 수입니다.
* `prefix` (Optional\[str]) - 이름이 지정된 prefix로 시작하는 object로 결과를 필터링합니다.
* `start_offset` (Optional\[str]) - 이름이 `start_offset`과 사전식으로 같거나 이후인 object로 결과를 필터링합니다. `end_offset`이 설정된 경우, 나열된 object의 이름은 `start_offset`(포함)과 `end_offset`(제외) 사이에 있습니다.

**Returns**:

* `List`(Object): 주어진 쿼리 매개변수와 일치하는 object 목록입니다.

### upload\_from\_filename

`upload_from_filename()`을 사용하여 로컬 디스크의 소스 파일에서 App Storage로 object를 업로드합니다.

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

**Arguments**:

* `dest_object_name`(str) - 업로드된 파일의 이름입니다.
* `src_filename`(str) - 업로드할 소스 파일입니다.

### upload\_from\_bytes

`upload_from_bytes` 메서드는 `bytes` 데이터로부터 object를 업로드합니다.

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

**Arguments**:

* `dest_object_name`(str) - 업로드할 object의 이름입니다.
* `src_data`(str) - 업로드할 `bytes` 데이터입니다.

### upload\_from\_text

`upload_from_text` 메서드는 문자열로부터 object를 업로드합니다.

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

**Arguments**:

* `dest_object_name`(str) - 업로드할 object의 이름입니다.
* `src_data`(str)- 업로드할 텍스트 데이터입니다.

### 예외 타입

* `Client`를 사용하여 Replit App Storage와 상호작용할 때, 어떤 메서드든 다음 오류 중 하나를 반환할 수 있습니다:

  * `BucketNotFoundError`: 구성된 bucket 이름이 App Storage의 어떤 bucket과도 일치하지 않음을 나타냅니다.

  * `DefaultBucketError`: 기본 bucket 구성이 누락되었음을 나타냅니다.

  * `ForbiddenError`: bucket에 대한 접근 권한이 부족함을 나타냅니다.

  * `TooManyRequestsError`: 과도한 요청으로 인해 작업이 속도 제한되었음을 나타냅니다.

  * `UnauthorizedError`: 인증이 해당 작업에 대한 접근을 제한했음을 나타냅니다.

## 클래스 메서드 예제

다음 섹션에서는 Replit App Storage SDK를 사용하여 object를 관리하는 코드 예제를 제공합니다.

### 파일을 텍스트로 가져오기

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

### 파일의 원시 바이트 가져오기

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

### 로컬 파일 시스템으로 파일 다운로드

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

### bucket 내 object 나열

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

### 텍스트로 파일 업로드

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

### bytes로 파일 업로드

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

### 파일 시스템에서 object 업로드

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

### bucket에서 object 삭제

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