> ## 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와의 상호작용을 관리합니다. 이 클래스는 버킷 내 객체에 대한 작업을 수행하는 메서드를 제공합니다.

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

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

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

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

<Tip>
  앱이 여러 버킷을 사용한다면 버킷마다 `Client` 인스턴스를 하나씩 만드세요.
</Tip>

### \_\_init\_\_

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

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

**인자**:

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

### copy

`copy` 메서드는 동일한 버킷 내에서 객체를 복사합니다. 같은 위치에 객체가 이미 존재하면 원본을 덮어씁니다.

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

**인자**:

* `object_name` (str) - 원본 객체의 전체 경로입니다.
* `dest_object_name` (str) - 대상 객체의 전체 경로입니다.

**발생 예외**:

* `ObjectNotFoundError` - 지정한 경로에 원본 객체가 존재하지 않음을 나타냅니다.

### delete

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

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

**인자**:

* `object_name` (str) - 삭제할 객체의 이름입니다.
* `ignore_not_found` (bool) - `True`이면 객체가 존재하지 않을 때 발생하는 오류를 무시합니다.

**발생 예외**:

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

### download\_as\_bytes

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

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

**인자**:

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

**반환값**:

* `bytes`- 객체 내용의 원본 바이트 표현입니다.

**발생 예외**:

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

### download\_as\_text

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

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

**인자**:

* `object_name` (str) - 가져올 원본 객체의 이름입니다.

**반환값**:

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

**발생 예외**:

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

### download\_to\_filename

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

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

**인자**:

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

**발생 예외**:

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

### exists

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

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

**인자**:

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

**반환값**:

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

### list

`list` 메서드는 버킷에 있는 객체 목록을 조회합니다.

```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]
```

**인자**:

* `end_offset`(Optional\[str]) - 결과를 `end_offset`보다 사전순으로 앞에 오는 이름을 가진 객체로 필터링합니다. `start_offset`이 정의되어 있으면
  나열되는 객체는 이름이 `start_offset`(포함)과 `end_offset`(제외) 사이에 있습니다.
* `match_glob` (Optional\[str]) - glob 패턴을 사용해 결과를 필터링합니다. 예를 들어 "foo\*bar"는 "footbar", "foo baz bar", "foobar"와 일치합니다.
* `max_results` (Optional\[int]) - 응답에서 반환할 최대 결과 수입니다.
* `prefix` (Optional\[str]) - 지정한 접두사로 시작하는 이름을 가진 객체로 결과를 필터링합니다.
* `start_offset` (Optional\[str]) - 이름이 `start_offset`과 사전순으로 같거나 이후인 객체로 결과를 필터링합니다.
  `end_offset`이 설정되어 있으면 나열되는 객체는 이름이 `start_offset`(포함)과 `end_offset`(제외) 사이에 있습니다.

**반환값**:

* `List`(Object): 지정한 쿼리 매개변수와 일치하는 객체 목록입니다.

### upload\_from\_filename

로컬 디스크의 원본 파일을 App Storage에 업로드하려면 `upload_from_filename()`을 사용하세요.

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

**인자**:

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

### upload\_from\_bytes

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

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

**인자**:

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

### upload\_from\_text

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

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

**인자**:

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

### 예외 유형

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

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

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

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

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

  * `UnauthorizedError`: 권한 부여가 작업에 대한 접근을 제한했음을 나타냅니다.

## 클래스 메서드 예제

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

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

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

### 버킷의 객체 목록 조회하기

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

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

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

### 바이트로 파일 업로드하기

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

### 파일 시스템에서 객체 업로드하기

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

### 버킷에서 객체 삭제하기

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